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"
141 Customizing LyX: Features for the Advanced User
149 \begin_layout Plain Layout
151 If you have comments or error corrections, please send them to the LyX Documenta
153 \begin_inset CommandInset href
155 target "lyx-docs@lists.lyx.org"
162 \begin_inset Quotes eld
166 \begin_inset Quotes erd
169 in the subject header, and please cc the current maintainer of this file,
170 Richard Heck <rgheck@comcast.net>.
176 \begin_inset Newline newline
180 \begin_inset Newline newline
186 \begin_layout Standard
187 \begin_inset CommandInset toc
188 LatexCommand tableofcontents
195 \begin_layout Standard
196 \begin_inset Note Note
199 \begin_layout Plain Layout
200 Please use change tracking when modifying this document.
201 This makes it easier for our translators to recognize things that have
202 been changed, and it helps the maintainer keep up-to-date with what's been
211 \begin_layout Chapter
215 \begin_layout Standard
216 This manual covers the customization features present in LyX.
217 In it, we discuss issues like keyboard shortcuts, screen previewing options,
218 printer options, sending commands to LyX via the LyX Server, internationalizati
219 on, installing new LaTeX classes and LyX layouts, etc.
220 We can't possibly hope to touch on everything you can change—our developers
221 add new features faster than we can document them—but we will explain the
222 most common customizations and hopefully point you in the right direction
223 for some of the more obscure ones.
226 \begin_layout Standard
227 \begin_inset Branch OutDated
230 \begin_layout Standard
231 Information from previous versions of this document that now seems to be
232 outdated is contained in the OutDated branch of this document.
233 By default, this information will not appear in the LaTeX output.
241 \begin_layout Chapter
242 LyX configuration files
245 \begin_layout Standard
246 This chapter aims to help you to find your way through the LyX configuration
248 Before continuing to read this chapter, you should find out where your
249 LyX library and user directories are by using
250 \begin_inset Flex MenuItem
253 \begin_layout Plain Layout
254 Help\SpecialChar \menuseparator
265 The library directory is the place where LyX places its system-wide configurati
266 on files; the user directory is where you can place your modified versions.
267 We will call the former
268 \begin_inset Flex Code
271 \begin_layout Plain Layout
278 \begin_inset Flex MenuItem
281 \begin_layout Plain Layout
287 in the remainder of this document.
291 \begin_layout Section
293 \begin_inset Flex Code
296 \begin_layout Plain Layout
305 \begin_layout Standard
306 \begin_inset Flex Code
309 \begin_layout Plain Layout
315 and its sub-directories contain a number of files and that can be used
316 to customize LyX's behavior.
317 You can change many of these files from within LyX itself through the
318 \begin_inset Flex MenuItem
321 \begin_layout Plain Layout
322 Tools\SpecialChar \menuseparator
329 Most customization that you will want to do in LyX is possible through
331 However, many other inner aspects of LyX can be customized by modifying
333 \begin_inset Flex Code
336 \begin_layout Plain Layout
343 These files fall in different categories, described in the following subsection
347 \begin_layout Subsection
348 Automatically generated files
351 \begin_layout Standard
352 The files, which are to be found in
353 \begin_inset Flex MenuItem
356 \begin_layout Plain Layout
362 , are generated when you configure LyX.
363 They contain various default values that are guessed by inspection.
364 In general, it is not a good idea to modify them, since they might be overwritt
368 \begin_layout Labeling
369 \labelwidthstring 00.00.0000
370 \begin_inset Flex Code
373 \begin_layout Plain Layout
379 contains defaults for various commands.
382 \begin_layout Labeling
383 \labelwidthstring 00.00.0000
384 \begin_inset Flex Code
387 \begin_layout Plain Layout
393 contains the list of packages that have been recognized by LyX.
394 It is currently unused by the LyX program itself, but the information extracted
395 , and more, is made available with
396 \begin_inset Flex MenuItem
399 \begin_layout Plain Layout
400 Help\SpecialChar \menuseparator
413 \begin_layout Labeling
414 \labelwidthstring 00.00.0000
415 \begin_inset Flex Code
418 \begin_layout Plain Layout
424 the list of text classes that have been found in your
425 \begin_inset Flex Code
428 \begin_layout Plain Layout
434 directories, along with the associated LaTeX document class and their descripti
438 \begin_layout Labeling
439 \labelwidthstring 00.00.0000
440 \begin_inset Flex Code
443 \begin_layout Plain Layout
449 the list of layout modules found in your
450 \begin_inset Flex Code
453 \begin_layout Plain Layout
462 \begin_layout Labeling
463 \labelwidthstring 00.00.0000
464 \begin_inset Flex Code
467 \begin_layout Plain Layout
473 lists of various sorts of LaTeX-related files found on your system
476 \begin_layout Labeling
477 \labelwidthstring 00.00.0000
478 \begin_inset Flex Code
481 \begin_layout Plain Layout
487 is automatically generated during configuration from the file
488 \begin_inset Flex Code
491 \begin_layout Plain Layout
498 It contains information on your LaTeX configuration.
501 \begin_layout Subsection
505 \begin_layout Standard
506 These directories are duplicated between
507 \begin_inset Flex Code
510 \begin_layout Plain Layout
517 \begin_inset Flex Code
520 \begin_layout Plain Layout
527 If a particular files exists in both places, the one in
528 \begin_inset Flex Code
531 \begin_layout Plain Layout
540 \begin_layout Labeling
541 \labelwidthstring 00.00.0000
542 \begin_inset Flex Code
545 \begin_layout Plain Layout
551 this directory contains files with the extension
552 \begin_inset Flex Code
555 \begin_layout Plain Layout
561 that define the keybindings used in LyX.
562 If there exists an internationalized version of the bind file named
563 \begin_inset Flex Code
566 \begin_layout Plain Layout
572 , that will be used first.
575 \begin_layout Labeling
576 \labelwidthstring 00.00.0000
577 \begin_inset Flex Code
580 \begin_layout Plain Layout
586 contains graphics files that can be included in documents.
590 \begin_layout Labeling
591 \labelwidthstring 00.00.0000
592 \begin_inset Flex Code
595 \begin_layout Plain Layout
601 contains LyX documentation files (including the one you are currently reading).
603 \begin_inset Flex Code
606 \begin_layout Plain Layout
612 deserves special attention, as noted above.
613 The internationalized help docs are in subdirectories
614 \begin_inset Flex Code
617 \begin_layout Plain Layout
624 \begin_inset Quotes eld
628 \begin_inset Quotes erd
631 is the ISO language code.
637 \begin_inset CommandInset ref
639 reference "cha:Internationalizing-LyX"
646 \begin_layout Labeling
647 \labelwidthstring 00.00.0000
648 \begin_inset Flex Code
651 \begin_layout Plain Layout
657 contains example files that explain how to use some features.
658 In the file browser, press the
659 \begin_inset Flex MenuItem
662 \begin_layout Plain Layout
671 \begin_layout Labeling
672 \labelwidthstring 00.00.0000
673 \begin_inset Flex Code
676 \begin_layout Plain Layout
682 contains image files that are used by the
683 \begin_inset Flex MenuItem
686 \begin_layout Plain Layout
693 In addition, it also contains the individual icons used in the toolbar
694 and the banners that can be shown when LyX is launched.
697 \begin_layout Labeling
698 \labelwidthstring 00.00.0000
699 \begin_inset Flex Code
702 \begin_layout Plain Layout
708 contains keyboard keymapping files.
714 \begin_inset CommandInset ref
716 reference "sec:International-Keymap-Stuff"
723 \begin_layout Labeling
724 \labelwidthstring 00.00.0000
725 \begin_inset Flex Code
728 \begin_layout Plain Layout
734 contains the text class and module files described in Chapter
739 \begin_inset CommandInset ref
741 reference "cha:Installing-New-Document"
748 \begin_layout Labeling
749 \labelwidthstring 00.00.0000
750 \begin_inset Flex Code
753 \begin_layout Plain Layout
760 \begin_inset Flex Code
763 \begin_layout Plain Layout
769 Python scripts used to convert between LyX versions.
770 These can be run from the command line if, say, you want to batch-convert
774 \begin_layout Labeling
775 \labelwidthstring 00.00.0000
776 \begin_inset Flex Code
779 \begin_layout Plain Layout
785 contains some files that demonstrate the capabilities of the
786 \begin_inset Flex MenuItem
789 \begin_layout Plain Layout
800 Also contains some scripts used by LyX itself.
803 \begin_layout Labeling
804 \labelwidthstring 00.00.0000
805 \begin_inset Flex Code
808 \begin_layout Plain Layout
814 contains the standard LyX template files described in Chapter
819 \begin_inset CommandInset ref
821 reference "sub:Creating-Templates"
828 \begin_layout Labeling
829 \labelwidthstring 00.00.0000
830 \begin_inset Flex Code
833 \begin_layout Plain Layout
839 contains files with the extension
840 \begin_inset Flex Code
843 \begin_layout Plain Layout
849 that define the user interface to LyX.
850 That is, the files define which items appear in which menus and the items
851 appearing on the toolbar.
854 \begin_layout Subsection
855 Files you don't want to modify
858 \begin_layout Standard
859 These files are used internally by LyX and you generally do not need to
860 modify them unless you are a developer.
863 \begin_layout Labeling
864 \labelwidthstring 00.00.0000
865 \begin_inset Flex Code
868 \begin_layout Plain Layout
874 this file contains the list of LyX developers.
875 The contents are displayed with the menu entry
876 \begin_inset Flex MenuItem
879 \begin_layout Plain Layout
880 Help\SpecialChar \menuseparator
893 \begin_layout Labeling
894 \labelwidthstring 00.00.0000
895 \begin_inset Flex Code
898 \begin_layout Plain Layout
904 this is a LaTeX script used during the configuration process.
908 \begin_layout Labeling
909 \labelwidthstring 00.00.0000
910 \begin_inset Flex Code
913 \begin_layout Plain Layout
919 this is the script that is used to re-configure LyX.
920 It creates configuration files in the directory it was run from.
923 \begin_layout Subsection
924 Other files needing a line or two...
927 \begin_layout Labeling
928 \labelwidthstring 00.00.0000
929 \begin_inset Flex Code
932 \begin_layout Plain Layout
938 this contains tables describing how different character encodings can be
942 \begin_layout Labeling
943 \labelwidthstring 00.00.0000
944 \begin_inset Flex Code
947 \begin_layout Plain Layout
953 this file contains the templates available to the new
954 \begin_inset Flex MenuItem
957 \begin_layout Plain Layout
970 \begin_layout Labeling
971 \labelwidthstring 00.00.0000
972 \begin_inset Flex Code
975 \begin_layout Plain Layout
981 this file contains a list of all the languages currently supported by LyX.
982 \change_inserted -195340706 1334775793
986 \begin_layout Labeling
987 \labelwidthstring 00.00.0000
989 \change_inserted -195340706 1334775793
990 \begin_inset Flex Code
993 \begin_layout Plain Layout
995 \change_inserted -195340706 1334775793
1001 this file contains translations for internationalized paragraph styles
1003 \begin_inset space \thinspace{}
1007 \begin_inset CommandInset ref
1009 reference "sub:I18n"
1018 \begin_layout Section
1019 Your local configuration directory
1022 \begin_layout Standard
1023 Even if you are using LyX as an unprivileged user, you might want to change
1024 LyX configuration for your own use.
1026 \begin_inset Flex Code
1029 \begin_layout Plain Layout
1035 directory contains all your personal configuration files.
1036 This is the directory described as
1037 \begin_inset Quotes eld
1041 \begin_inset Quotes erd
1045 \begin_inset Flex MenuItem
1048 \begin_layout Plain Layout
1049 Help\SpecialChar \menuseparator
1051 \begin_inset space ~
1060 This directory is used as a mirror of
1061 \begin_inset Flex Code
1064 \begin_layout Plain Layout
1070 , which means that every file in
1071 \begin_inset Flex Code
1074 \begin_layout Plain Layout
1080 is a replacement for the corresponding file in
1081 \begin_inset Flex Code
1084 \begin_layout Plain Layout
1091 Any configuration file described in the above sections can be placed either
1092 in the system-wide directory, in which case it will affect all users, or
1093 in your local directory for your own use.
1096 \begin_layout Standard
1097 To make things clearer, let's provide a few examples:
1100 \begin_layout Itemize
1101 The preferences set in the
1102 \begin_inset Flex MenuItem
1105 \begin_layout Plain Layout
1106 Tools\SpecialChar \menuseparator
1112 dialog are saved to a file
1113 \begin_inset Flex Code
1116 \begin_layout Plain Layout
1123 \begin_inset Flex Code
1126 \begin_layout Plain Layout
1135 \begin_layout Itemize
1136 When you reconfigure using
1137 \begin_inset Flex MenuItem
1140 \begin_layout Plain Layout
1141 Tools\SpecialChar \menuseparator
1148 \begin_inset Flex Code
1151 \begin_layout Plain Layout
1157 script, and the resulting files are written in your local configuration
1159 This means that any additional text class file that you might have added
1161 \begin_inset Flex Code
1164 \begin_layout Plain Layout
1170 will be added to the list of classes in the
1171 \begin_inset Flex MenuItem
1174 \begin_layout Plain Layout
1175 Document\SpecialChar \menuseparator
1184 \begin_layout Itemize
1185 If you get some updated documentation from LyX ftp site and cannot install
1186 it because you do not have sysadmin rights on your system, you can just
1188 \begin_inset Flex Code
1191 \begin_layout Plain Layout
1197 and the items in the
1198 \begin_inset Flex MenuItem
1201 \begin_layout Plain Layout
1207 menu will open them!
1210 \begin_layout Section
1211 Running LyX with multiple configurations
1214 \begin_layout Standard
1215 The configuration freedom of the local configuration directory may not suffice
1216 if you want to have more than one configuration at your disposal.
1217 For example, you may want to be use different key bindings or printer settings
1219 You can achieve this by having several such directories.
1220 You then specify which directory to use at run-time.
1223 \begin_layout Standard
1224 Invoking LyX with the command line switch
1225 \begin_inset Flex Code
1228 \begin_layout Plain Layout
1238 instructs the program to read the configuration from that directory, and
1239 not from the default directory.
1240 (You can determine the default directory by running LyX without the
1241 \begin_inset Flex Code
1244 \begin_layout Plain Layout
1250 switch.) If the specified directory does not exist, LyX offers to create
1251 it for you, just like it does for the default directory on the first time
1252 you run the program.
1253 You can modify the configuration options in this additional user directory
1254 exactly as you would for the default directory.
1255 These directories are completely independent (but read on).
1256 Note that setting the environment variable
1257 \begin_inset Flex Code
1260 \begin_layout Plain Layout
1266 to some value has exactly the same effect.
1269 \begin_layout Standard
1270 Having several configurations also requires more maintenance: if you want
1271 to add a new layout to
1272 \begin_inset Flex Code
1275 \begin_layout Plain Layout
1281 which you want available from all your configurations, you must add it
1282 to each directory separately.
1283 You can avoid this with the following trick: after LyX creates the additional
1284 directory, most of the subdirectories (see above) are empty.
1285 If you want the new configuration to mirror an existing one, replace the
1286 empty subdirectory with a symbolic link to the matching subdirectory in
1287 the existing configuration.
1289 \begin_inset Flex Code
1292 \begin_layout Plain Layout
1298 subdirectory, however, since it contains a file written by the configuration
1299 script (also accessible through
1300 \begin_inset Flex MenuItem
1303 \begin_layout Plain Layout
1304 Tools\SpecialChar \menuseparator
1310 ) which is configuration-specific.
1313 \begin_layout Chapter
1314 The Preferences dialog
1317 \begin_layout Standard
1318 All options of the preferences dialog are described in the Appendix
1320 The Preferences Dialog
1327 For some options you might find here more details.
1330 \begin_layout Section
1332 \begin_inset CommandInset label
1341 \begin_layout Standard
1342 The first step is to define your file formats if they are not already defined.
1344 \begin_inset Flex MenuItem
1347 \begin_layout Plain Layout
1348 Tools\SpecialChar \menuseparator
1356 \begin_inset Flex MenuItem
1359 \begin_layout Plain Layout
1360 File Handling\SpecialChar \menuseparator
1367 \begin_inset Flex MenuItem
1370 \begin_layout Plain Layout
1371 New\SpecialChar \ldots{}
1377 button to define your new format.
1379 \begin_inset Flex MenuItem
1382 \begin_layout Plain Layout
1388 field contains the name used to identify the format in the GUI.
1390 \begin_inset Flex MenuItem
1393 \begin_layout Plain Layout
1399 is used to identify the format internally.
1400 You will also need to enter a file extension.
1401 These are all required.
1403 \begin_inset Flex MenuItem
1406 \begin_layout Plain Layout
1412 field is used to provide a keyboard shortcut on the menus.
1413 (For example, pressing
1414 \begin_inset Flex MenuItem
1417 \begin_layout Plain Layout
1424 \begin_inset Flex MenuItem
1427 \begin_layout Plain Layout
1428 View\SpecialChar \menuseparator
1429 View (Other Formats)\SpecialChar \menuseparator
1438 \begin_layout Standard
1440 \begin_inset Flex MenuItem
1443 \begin_layout Plain Layout
1450 \begin_inset Flex MenuItem
1453 \begin_layout Plain Layout
1460 For example, you might want to use
1461 \begin_inset Flex MenuItem
1464 \begin_layout Plain Layout
1470 to view PostScript files.
1471 You can enter the command needed to start the program in the corresponding
1473 In defining this command, you can use the four variables listed in the
1475 The viewer is launched when you view an image in LyX or use the
1476 \begin_inset Flex MenuItem
1479 \begin_layout Plain Layout
1486 The editor is for example launched when you right-click on an image and
1488 \begin_inset Flex MenuItem
1491 \begin_layout Plain Layout
1497 in the appearing context menu.
1500 \begin_layout Standard
1502 \change_inserted -195340706 1329851811
1504 \begin_inset Flex MenuItem
1507 \begin_layout Plain Layout
1513 type of a format is optional, but if it is specified, it must be unique
1515 It is used to detect files of this format from the file contents.
1516 For some important file formats there is no MIME type officially registered
1518 \begin_inset CommandInset href
1521 target "http://www.iana.org/assignments/media-types/"
1526 Therefore LyX uses the extended list of MIME types as specified by
1527 \begin_inset CommandInset href
1529 name "freedesktop.org"
1530 target "http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec"
1537 \begin_layout Standard
1539 \begin_inset Flex MenuItem
1542 \begin_layout Plain Layout
1548 option tells LyX that a format is suitable for document export.
1549 If this is set and if a suitable conversion route exists (see sec.
1550 \begin_inset space \thinspace{}
1554 \begin_inset CommandInset ref
1556 reference "sec:Converters"
1560 ), the format will appear in the
1561 \begin_inset Flex MenuItem
1564 \begin_layout Plain Layout
1565 File\SpecialChar \menuseparator
1572 The format will also appear in the
1573 \begin_inset Flex MenuItem
1576 \begin_layout Plain Layout
1582 menu if a viewer is specified for the format.
1583 Pure image formats, such as
1584 \begin_inset Flex Code
1587 \begin_layout Plain Layout
1593 , should not use this option.
1594 Formats that can both represent vector graphics and documents like
1595 \begin_inset Flex Code
1598 \begin_layout Plain Layout
1607 \begin_layout Standard
1609 \begin_inset Flex MenuItem
1612 \begin_layout Plain Layout
1613 Vector graphics format
1618 tells LyX that a format can contain vector graphics.
1619 This information is used to determine the target format of included graphics
1621 \begin_inset Flex MenuItem
1624 \begin_layout Plain Layout
1631 Included graphics may need to be converted to either
1632 \begin_inset Flex MenuItem
1635 \begin_layout Plain Layout
1642 \begin_inset Flex MenuItem
1645 \begin_layout Plain Layout
1652 \begin_inset Flex MenuItem
1655 \begin_layout Plain Layout
1662 \begin_inset Flex MenuItem
1665 \begin_layout Plain Layout
1671 cannot handle other image formats.
1672 If an included graphic is not already in
1673 \begin_inset Flex MenuItem
1676 \begin_layout Plain Layout
1683 \begin_inset Flex MenuItem
1686 \begin_layout Plain Layout
1693 \begin_inset Flex MenuItem
1696 \begin_layout Plain Layout
1702 format, it is converted to
1703 \begin_inset Flex MenuItem
1706 \begin_layout Plain Layout
1712 if the vector format option is set, and otherwise to
1713 \begin_inset Flex MenuItem
1716 \begin_layout Plain Layout
1725 \begin_layout Section
1729 \begin_layout Standard
1730 Since all conversions from one format to another take place in LyX's temporary
1731 directory, it is sometimes necessary to modify a file before copying it
1732 to the temporary directory in order that the conversion may be performed.
1736 \begin_layout Plain Layout
1737 For example, the file may refer to other files—images, for example—using
1738 relative file names, and these may become invalid when the file is copied
1739 to the temporary directory.
1744 This is done by a Copier: It copies a file to (or from) the temporary directory
1745 and may modify it in the process.
1748 \begin_layout Standard
1749 The definitions of the copiers may use four variables:
1752 \begin_layout Labeling
1753 \labelwidthstring 00.00.0000
1754 \begin_inset Flex Code
1757 \begin_layout Plain Layout
1763 The LyX system directory (e.
1764 \begin_inset space \thinspace{}
1768 \begin_inset space \space{}
1772 \begin_inset Flex MenuItem
1775 \begin_layout Plain Layout
1784 \begin_layout Labeling
1785 \labelwidthstring 00.00.0000
1786 \begin_inset Flex Code
1789 \begin_layout Plain Layout
1798 \begin_layout Labeling
1799 \labelwidthstring 00.00.0000
1800 \begin_inset Flex Code
1803 \begin_layout Plain Layout
1812 \begin_layout Labeling
1813 \labelwidthstring 00.00.0000
1814 \begin_inset Flex Code
1817 \begin_layout Plain Layout
1826 \begin_layout Standard
1827 The latter should be the filename as it would be used in a LaTeX's
1834 It is relevant only when exporting files suitable for such inclusion.
1837 \begin_layout Standard
1838 Copiers can be used to do almost anything with output files.
1839 For example, suppose you want generated pdf files to be copied to a special
1841 \begin_inset Flex Code
1844 \begin_layout Plain Layout
1851 Then you could write a shell script such as this one:
1854 \begin_layout Standard
1855 \begin_inset listings
1859 \begin_layout Plain Layout
1864 \begin_layout Plain Layout
1869 \begin_layout Plain Layout
1871 TOFILE=`basename $2`
1874 \begin_layout Plain Layout
1876 cp $FROMFILE /home/you/pdf/$TOFILE
1881 Save it in your local LyX directory—say,
1882 \begin_inset Flex Code
1885 \begin_layout Plain Layout
1886 /home/you/.lyx/scripts/pdfcopier.sh
1891 —and make it executable, if you need to do so on your platform.
1893 \begin_inset Flex MenuItem
1896 \begin_layout Plain Layout
1897 Tools\SpecialChar \menuseparator
1903 dialog, select under
1904 \begin_inset Flex MenuItem
1907 \begin_layout Plain Layout
1908 File Handling\SpecialChar \menuseparator
1915 \begin_inset Flex MenuItem
1918 \begin_layout Plain Layout
1924 format—or one of the other pdf formats—and enter
1925 \begin_inset Flex Code
1928 \begin_layout Plain Layout
1929 pdfcopier.sh $$i $$o
1935 \begin_inset Flex MenuItem
1938 \begin_layout Plain Layout
1948 \begin_layout Standard
1949 Copiers are used by LyX in various of its own conversions.
1950 For example, if appropriate programs are found, LyX will automatically
1951 install copiers for the
1952 \begin_inset Flex MenuItem
1955 \begin_layout Plain Layout
1962 \begin_inset Flex MenuItem
1965 \begin_layout Plain Layout
1967 \begin_inset space ~
1976 When these formats are exported, the copier sees that not just the main
1977 HTML file but various associated files (style files, images, etc.) are also
1979 All these files are written to a subdirectory of the directory in which
1980 the original LyX file was found.
1984 \begin_layout Plain Layout
1985 This copier can be customized.
1987 \begin_inset Quotes eld
1991 \begin_inset Quotes erd
1994 argument takes a comma-separated list of extensions to be copied; if it
1995 is omitted, all files will be copied.
1997 \begin_inset Quotes eld
2001 \begin_inset Quotes erd
2004 argument determines the extension added to the generated directory.
2006 \begin_inset Quotes eld
2010 \begin_inset Flex MenuItem
2013 \begin_layout Plain Layout
2020 \begin_inset Quotes erd
2023 , so HTML generated from
2024 \begin_inset Flex MenuItem
2027 \begin_layout Plain Layout
2028 /path/to/filename.lyx
2034 \begin_inset Flex MenuItem
2037 \begin_layout Plain Layout
2038 /path/to/filename.html.LyXconv
2052 \begin_layout Section
2054 \begin_inset CommandInset label
2056 name "sec:Converters"
2063 \begin_layout Standard
2064 You can define your own Converters to convert files between different formats.
2066 \begin_inset Flex MenuItem
2069 \begin_layout Plain Layout
2070 Tools\SpecialChar \menuseparator
2071 Preferences\SpecialChar \menuseparator
2072 File Handling\SpecialChar \menuseparator
2081 \begin_layout Standard
2082 To define a new converter, select the
2083 \begin_inset Flex MenuItem
2086 \begin_layout Plain Layout
2088 \begin_inset space ~
2097 \begin_inset Flex MenuItem
2100 \begin_layout Plain Layout
2102 \begin_inset space ~
2110 from the drop-down lists, enter the command needed for the conversion,
2112 \begin_inset Flex MenuItem
2115 \begin_layout Plain Layout
2122 Several variables can be used in the definition of converters:
2125 \begin_layout Labeling
2126 \labelwidthstring 00.00.0000
2127 \begin_inset Flex Code
2130 \begin_layout Plain Layout
2136 The LyX system directory
2139 \begin_layout Labeling
2140 \labelwidthstring 00.00.0000
2141 \begin_inset Flex Code
2144 \begin_layout Plain Layout
2153 \begin_layout Labeling
2154 \labelwidthstring 00.00.0000
2155 \begin_inset Flex Code
2158 \begin_layout Plain Layout
2167 \begin_layout Labeling
2168 \labelwidthstring 00.00.0000
2169 \begin_inset Flex Code
2172 \begin_layout Plain Layout
2178 The base filename of the input file (i.
2179 \begin_inset space \thinspace{}
2182 g., without the extension)
2185 \begin_layout Labeling
2186 \labelwidthstring 00.00.0000
2187 \begin_inset Flex Code
2190 \begin_layout Plain Layout
2196 The path to the input file
2199 \begin_layout Labeling
2200 \labelwidthstring 00.00.0000
2201 \begin_inset Flex Code
2204 \begin_layout Plain Layout
2210 The path to the original input file (this is different from $$p when a
2211 chain of converters is called)
2214 \begin_layout Labeling
2215 \labelwidthstring 00.00.0000
2216 \begin_inset Flex Code
2219 \begin_layout Plain Layout
2225 The iconv name for the encoding of the document.
2228 \begin_layout Standard
2230 \begin_inset Flex MenuItem
2233 \begin_layout Plain Layout
2235 \begin_inset space ~
2243 field you can enter the following flags, separated by commas:
2246 \begin_layout Labeling
2247 \labelwidthstring 00.00.0000
2248 \begin_inset Flex Code
2251 \begin_layout Plain Layout
2257 This converter runs some form of LaTeX.
2258 This will make LyX's LaTeX error logs available.
2261 \begin_layout Labeling
2262 \labelwidthstring 00.00.0000
2263 \begin_inset Flex Code
2266 \begin_layout Plain Layout
2273 \begin_inset Flex MenuItem
2276 \begin_layout Plain Layout
2282 file for the conversion.
2285 \begin_layout Labeling
2286 \labelwidthstring 00.00.0000
2287 \begin_inset Flex Code
2290 \begin_layout Plain Layout
2299 \begin_layout Standard
2300 The following three flags are not really flags at all because they take
2302 \begin_inset Flex MenuItem
2305 \begin_layout Plain Layout
2307 \begin_inset space ~
2311 \begin_inset space ~
2322 \begin_layout Labeling
2323 \labelwidthstring 00.00.0000
2324 \begin_inset Flex Code
2327 \begin_layout Plain Layout
2333 If set, the converter's standard error will be redirected to a file
2334 \begin_inset Flex Code
2337 \begin_layout Plain Layout
2343 , and the script given as argument will be run as:
2344 \begin_inset Flex Code
2347 \begin_layout Plain Layout
2348 script < infile.out > infile.log
2354 The argument may contain
2355 \begin_inset Flex Code
2358 \begin_layout Plain Layout
2367 \begin_layout Labeling
2368 \labelwidthstring 00.00.0000
2369 \begin_inset Flex Code
2372 \begin_layout Plain Layout
2378 The name of the directory in which the converter will dump the generated
2380 LyX will not create this directory, and it does not copy anything into
2381 it, though it will copy this directory to the destination.
2382 The argument may contain
2383 \begin_inset Flex Code
2386 \begin_layout Plain Layout
2392 , which will be replaced by the base name of the input and output files,
2393 respectively, when the directory is copied.
2394 \begin_inset Newline newline
2397 Note that resultdir and usetempdir make no sense together.
2398 The latter will be ignored if the former is given.
2401 \begin_layout Labeling
2402 \labelwidthstring 00.00.0000
2403 \begin_inset Flex Code
2406 \begin_layout Plain Layout
2412 Determines the output file name and may, contain
2413 \begin_inset Flex Code
2416 \begin_layout Plain Layout
2423 Sensible only with resultdir and optional even then; if not given, it defaults
2427 \begin_layout Standard
2428 None of these last three are presently used in any of the converters that
2429 are installed with LyX.
2433 \begin_layout Standard
2434 You do not have to define converters for all formats between which you want
2436 For example, you will note that there is no `LyX to PostScript' converter,
2437 but LyX will export PostScript.
2438 It does so by first creating a LaTeX file (no converter needs to be defined
2439 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2440 and finally converting the resulting DVI file to PostScript.
2441 LyX finds such `chains' of converters automatically, and it will always
2442 choose the shortest possible chain.
2443 You can, though, still define multiple conversion methods between file
2445 For example, the standard LyX configuration provides three ways to convert
2446 LaTeX to PDF: Directly, using
2447 \begin_inset Flex MenuItem
2450 \begin_layout Plain Layout
2456 ; via (DVI and) PostScript, using
2457 \begin_inset Flex MenuItem
2460 \begin_layout Plain Layout
2467 \begin_inset Flex MenuItem
2470 \begin_layout Plain Layout
2477 To define such alternate chains, you must define multiple target `file
2478 formats', as described in section
2479 \begin_inset CommandInset ref
2481 reference "sec:Formats"
2486 For example, in the standard configuration, the formats named
2487 \begin_inset Flex MenuItem
2490 \begin_layout Plain Layout
2497 \begin_inset Flex MenuItem
2500 \begin_layout Plain Layout
2507 \begin_inset Flex MenuItem
2510 \begin_layout Plain Layout
2516 are defined, all of which share the extension
2517 \begin_inset Flex MenuItem
2520 \begin_layout Plain Layout
2526 , and which correspond to the conversion methods just mentioned.
2529 \begin_layout Chapter
2530 Internationalizing LyX
2531 \begin_inset CommandInset label
2533 name "cha:Internationalizing-LyX"
2540 \begin_layout Standard
2541 LyX supports using a translated interface.
2542 Last time we checked, LyX provided text in thirty languages.
2543 The language of choice is called your
2548 (For further reading on locale settings, see also the documentation for
2549 locale that comes with your operating system.
2550 For Linux, the manual page for
2551 \begin_inset Flex Code
2554 \begin_layout Plain Layout
2560 could be a good place to start).
2563 \begin_layout Standard
2564 Notice that these translations will work, but do contain a few flaws.
2565 In particular, all dialogs have been designed with the English text in
2566 mind, which means that some of the translated text will be too large to
2567 fit within the space allocated.
2568 This is only a display problem and will not cause any harm.
2569 Also, you will find that some of the translations do not define shortcut
2570 keys for everything.
2571 Sometimes, there are simply not enough free letters to do it.
2572 Other times, the translator just hasn't got around to doing it yet.
2573 Our localization team, which you may wish to join,
2577 \begin_layout Plain Layout
2578 If you are a fluent speaker of a language other than English, joining these
2579 teams is a great way to give back to the LyX community!
2584 will of course try to fix these shortcomings in future versions of LyX.
2587 \begin_layout Section
2591 \begin_layout Subsection
2592 Translating the graphical user interface (text messages).
2595 \begin_layout Standard
2597 \begin_inset Flex Code
2600 \begin_layout Plain Layout
2606 library to handle the internationalization of the interface.
2607 To have LyX speak your favorite language in all menus and dialogs, you
2609 \begin_inset Flex Code
2612 \begin_layout Plain Layout
2618 -file for that language.
2619 When this is available, you'll have to generate a
2620 \begin_inset Flex Code
2623 \begin_layout Plain Layout
2629 -file from it and install the
2630 \begin_inset Flex Code
2633 \begin_layout Plain Layout
2640 The process of doing all of this is explained in the documentation for
2642 \begin_inset Flex Code
2645 \begin_layout Plain Layout
2652 It is possible to do this just for yourself, but if you're going to do
2653 it, you might as well share the results of your labors with the rest of
2655 Send a message to the LyX developers' list for more information about how
2659 \begin_layout Standard
2660 In short, this is what you should do (xx denotes the language code):
2663 \begin_layout Itemize
2664 Check out the LyX source code.
2666 \begin_inset CommandInset href
2668 name "information on the web"
2669 target "http://www.lyx.org/HowToUseSVN"
2676 \begin_layout Itemize
2678 \begin_inset Flex Code
2681 \begin_layout Plain Layout
2687 to the folder of the
2688 \begin_inset Flex Code
2691 \begin_layout Plain Layout
2699 \begin_inset Flex Code
2702 \begin_layout Plain Layout
2710 \begin_inset Flex Code
2713 \begin_layout Plain Layout
2719 doesn't exist anywhere, it can be remade with the console command
2720 \begin_inset Flex Code
2723 \begin_layout Plain Layout
2729 in that directory, or you can use an existing po-file for some other language
2733 \begin_layout Itemize
2735 \begin_inset Flex Code
2738 \begin_layout Plain Layout
2748 \begin_layout Plain Layout
2749 This is just a text file, so it can be edited in any text editor.
2750 But there are also specialized programs that support such editing, such
2755 (for all platforms) or
2764 contains a `mode' for editing
2765 \begin_inset Flex Code
2768 \begin_layout Plain Layout
2779 For some menu- and widget-labels, there are also shortcut keys that should
2781 Those keys are marked after a `|', and should be translated according to
2782 the words and phrases of the language.
2783 You should also fill also out the information at the beginning of the new
2785 \begin_inset Flex Code
2788 \begin_layout Plain Layout
2794 -file with your email-address, etc., so people know where to reach you with
2795 suggestions and entertaining flames.
2798 \begin_layout Standard
2799 If you are just doing this on your own, then:
2802 \begin_layout Itemize
2804 \begin_inset Flex Code
2807 \begin_layout Plain Layout
2814 This can be done with
2815 \begin_inset Flex Code
2818 \begin_layout Plain Layout
2819 msgfmt -o xx.mo < xx.po
2827 \begin_layout Itemize
2829 \begin_inset Flex Code
2832 \begin_layout Plain Layout
2838 -file to your locale-tree, at the correct directory for application messages
2843 xx, and under the name
2844 \begin_inset Flex Code
2847 \begin_layout Plain Layout
2854 \begin_inset space \thinspace{}
2858 \begin_inset space \space{}
2862 \begin_inset Flex Code
2865 \begin_layout Plain Layout
2866 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2876 \begin_layout Standard
2877 As said, however, it would be best if the new
2878 \begin_inset Flex Code
2881 \begin_layout Plain Layout
2887 -file could be added to the LyX distribution, so others can use it.
2888 Adding it involves making additional changes to LyX.
2889 So send an email to the developers' mailing list if you're interested in
2893 \begin_layout Subsubsection
2897 \begin_layout Standard
2898 Sometimes it turns out that one English message needs to be translated into
2899 different messages in the target language.
2900 One example is the message
2901 \begin_inset Flex Code
2904 \begin_layout Plain Layout
2910 which has the German translation
2918 , depending upon exactly what the English
2919 \begin_inset Quotes eld
2923 \begin_inset Quotes erd
2928 \begin_inset Flex Code
2931 \begin_layout Plain Layout
2937 does not handle such ambiguous translations.
2938 Therefore you have to add some context information to the message: Instead
2940 \begin_inset Flex Code
2943 \begin_layout Plain Layout
2950 \begin_inset Flex Code
2953 \begin_layout Plain Layout
2954 To[[as in 'From format x to format y']]
2960 \begin_inset Flex Code
2963 \begin_layout Plain Layout
2964 To[[as in 'From page x to page y']].
2969 Now the two occurrences of
2970 \begin_inset Flex Code
2973 \begin_layout Plain Layout
2980 \begin_inset Flex Code
2983 \begin_layout Plain Layout
2989 and can be translated correctly to
3000 \begin_layout Standard
3001 Of course the context information needs to be stripped off the original
3002 message when no translation is used.
3003 Therefore you have to put it in double square brackets at the end of the
3004 message (see the example above).
3005 The translation mechanism of LyX ensures that everything in double square
3006 brackets at the end of messages is removed before displaying the message.
3009 \begin_layout Subsection
3010 Translating the documentation.
3013 \begin_layout Standard
3014 The online documentation (in the
3015 \begin_inset Flex MenuItem
3018 \begin_layout Plain Layout
3024 -menu) can (and should!) be translated.
3025 If there are translated versions of the documentation available
3029 \begin_layout Plain Layout
3030 As of March 2008, at least some of the documents have been translated into
3031 fourteen languages, with the Tutorial available in a few more.
3036 and the locale is set accordingly, these will be used automagically by
3038 LyX looks for translated versions as
3039 \begin_inset Flex Code
3042 \begin_layout Plain Layout
3043 LyXDir/doc/xx/DocName.lyx
3049 \begin_inset Flex Code
3052 \begin_layout Plain Layout
3058 is the code for the language currently in use.
3059 If there are no translated documents, the default English versions will
3061 Note that the translated versions must have the same filenames (
3062 \begin_inset Flex Code
3065 \begin_layout Plain Layout
3071 above) as the original.
3072 If you feel up to translating the documentation (an excellent way to proof-read
3073 the original documentation by the way!), there are a few things you should
3077 \begin_layout Itemize
3078 Check out the documentation translation web page at
3079 \begin_inset CommandInset href
3081 name "http://www.lyx.org/Translation"
3082 target "http://www.lyx.org/Translation"
3087 That way, you can find out which (if any) documents have already been translate
3088 d into your language.
3089 You can also find out who (if anyone) is organizing the effort to translate
3090 the documentation into your language.
3091 If no one is organizing the effort, please let us know that you're interested.
3094 \begin_layout Standard
3095 Once you get to actually translating, here's a few hints for you that may
3099 \begin_layout Itemize
3100 Join the documentation team! There is information on how to do that in
3101 \begin_inset Flex Code
3104 \begin_layout Plain Layout
3111 \begin_inset Flex MenuItem
3114 \begin_layout Plain Layout
3115 Help\SpecialChar \menuseparator
3121 ), which by the way is the first document you should translate.
3124 \begin_layout Itemize
3125 Learn the typographic conventions for the language you are translating to.
3126 Typography is an ancient art and over the centuries, a great variety of
3127 conventions have developed throughout different parts of the world.
3128 Also study the professional terminology amongst typographers in your country.
3129 Inventing your own terminology will only confuse the users.
3132 (Warning! Typography is addictive!)
3135 \begin_layout Itemize
3136 Make a copy of the document.
3137 This will be your working copy.
3138 You can use this as your personal translated help-file by placing it in
3140 \begin_inset Flex Code
3143 \begin_layout Plain Layout
3152 \begin_layout Itemize
3153 Sometimes the original document (from the LyX-team) will be updated.
3154 Use the source viewer at
3155 \begin_inset CommandInset href
3157 name "http://www.lyx.org/trac/timeline"
3158 target "http://www.lyx.org/trac/timeline"
3162 to see what has been changed.
3163 That way you can easily see which parts of the translated document need
3167 \begin_layout Standard
3168 If you ever find an error in the original document, fix it and notify the
3169 rest of the documentation team of the changes! (You didn't forget to join
3170 the documentation team, did you?)
3173 \begin_layout Standard
3174 \begin_inset Branch OutDated
3177 \begin_layout Section
3178 International Keyboard Support
3181 \begin_layout Standard
3184 [Editor's Note: The following section is by
3192 It needs to be fixed to conform to the new Documentation Style sheet and
3193 to make use of the new v1.0 features.
3194 The whole thing also needs to be merged with the section following it.-jw
3195 It may also be badly out of date.-rh (2008)]
3198 \begin_layout Subsection
3199 Defining Own Keymaps: Keymap File Format
3202 \begin_layout Standard
3203 Let's look at a keyboard definition file a little closer.
3204 It is a plain text file defining
3207 \begin_layout Itemize
3208 key-to-key or key-to-string translations
3211 \begin_layout Itemize
3215 \begin_layout Itemize
3216 dead keys exceptions
3219 \begin_layout Standard
3220 To define key-to-key or key-to-string translation, use this command:
3223 \begin_layout Quotation
3224 \begin_inset Flex Code
3227 \begin_layout Plain Layout
3236 \begin_inset Flex Code
3239 \begin_layout Plain Layout
3248 \begin_layout Standard
3250 \begin_inset Flex Code
3253 \begin_layout Plain Layout
3259 is the key to be translated and
3260 \begin_inset Flex Code
3263 \begin_layout Plain Layout
3269 is the string to be inserted into the document.
3270 To define dead keys, use:
3273 \begin_layout Quotation
3274 \begin_inset Flex Code
3277 \begin_layout Plain Layout
3286 \begin_inset Flex Code
3289 \begin_layout Plain Layout
3298 \begin_layout Standard
3300 \begin_inset Flex Code
3303 \begin_layout Plain Layout
3309 is a keyboard key and
3310 \begin_inset Flex Code
3313 \begin_layout Plain Layout
3320 The following dead keys are supported (shortcut name is in parentheses):
3323 \begin_layout Quotation
3327 \begin_inset space \hfill{}
3333 \begin_layout Quotation
3335 \begin_inset space \hfill{}
3341 \begin_layout Quotation
3343 \begin_inset space \hfill{}
3349 \begin_layout Quotation
3351 \begin_inset space \hfill{}
3357 \begin_layout Quotation
3359 \begin_inset space \hfill{}
3365 \begin_layout Quotation
3367 \begin_inset space \hfill{}
3374 \begin_layout Plain Layout
3386 \begin_layout Quotation
3388 \begin_inset space \hfill{}
3394 \begin_layout Quotation
3396 \begin_inset space \hfill{}
3403 \begin_layout Plain Layout
3415 \begin_layout Quotation
3417 \begin_inset space \hfill{}
3423 \begin_layout Quotation
3425 \begin_inset space \hfill{}
3431 \begin_layout Quotation
3433 \begin_inset space \hfill{}
3440 \begin_layout Plain Layout
3452 \begin_layout Quotation
3454 \begin_inset space \hfill{}
3461 \begin_layout Plain Layout
3473 \begin_layout Quotation
3475 \begin_inset space \hfill{}
3481 \begin_layout Quotation
3482 hungarian umlaut (hug)
3483 \begin_inset space \hfill{}
3489 \begin_layout Quotation
3491 \begin_inset space \hfill{}
3497 \begin_layout Quotation
3499 \begin_inset space \hfill{}
3506 \begin_layout Plain Layout
3518 \begin_layout Standard
3519 Since in many international keyboards there are exceptions to what some
3520 dead keys should do, you can define them using
3523 \begin_layout Quotation
3524 \begin_inset Flex Code
3527 \begin_layout Plain Layout
3535 deadkey key outstring
3538 \begin_layout Standard
3539 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3543 \begin_layout Quotation
3544 \begin_inset Flex Code
3547 \begin_layout Plain Layout
3560 \begin_layout Standard
3561 to make it work correctly.
3562 Also, you have to define as exceptions dead keys over i and j, to remove
3563 the dot from them before inserting an accent mark.
3564 I will change this when the time comes, but so far I haven't had time.
3567 \begin_layout Standard
3568 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3571 \begin_inset Flex Code
3574 \begin_layout Plain Layout
3580 have different meaning.
3582 \begin_inset Flex Code
3585 \begin_layout Plain Layout
3591 marks comments, quotes start and end LaTeX-style commands.
3592 To enter quote, you'll need to use
3593 \begin_inset Flex Code
3596 \begin_layout Plain Layout
3605 \begin_inset Flex Code
3608 \begin_layout Plain Layout
3615 \begin_inset Flex Code
3618 \begin_layout Plain Layout
3629 \begin_layout Standard
3630 If you make a keyboard description file that works for your language, please
3631 mail it to me, so I can include it in the next keymap distribution.
3634 \begin_layout Standard
3635 More keywords will be supported in keymap configuration file in future,
3639 \begin_layout Itemize
3640 \begin_inset Flex Code
3643 \begin_layout Plain Layout
3654 \begin_inset space \hfill{}
3658 \begin_inset Flex Code
3661 \begin_layout Plain Layout
3670 \begin_layout Itemize
3671 \begin_inset Flex Code
3674 \begin_layout Plain Layout
3685 \begin_inset space \hfill{}
3689 \begin_inset Flex Code
3692 \begin_layout Plain Layout
3698 an external keymap translation program
3701 \begin_layout Standard
3702 Also, it should look into
3703 \begin_inset Flex Code
3706 \begin_layout Plain Layout
3712 file for defaults, too (for example, a
3713 \begin_inset Flex Code
3716 \begin_layout Plain Layout
3724 option to include default keyboard).
3732 \begin_layout Section
3733 International Keymap Stuff
3734 \begin_inset CommandInset label
3736 name "sec:International-Keymap-Stuff"
3743 \begin_layout Standard
3744 \begin_inset Note Note
3747 \begin_layout Plain Layout
3748 In doing the revisions on this document in March 2008, I did not look over
3749 this stuff, as I do not understand it.
3750 It would be good if someone else could do so.
3759 \begin_layout Standard
3760 The next two sections describe the
3761 \begin_inset Flex Code
3764 \begin_layout Plain Layout
3773 \begin_inset Flex Code
3776 \begin_layout Plain Layout
3784 file syntax in detail.
3785 These sections should help you design your own key map if the ones provided
3786 do not meet your needs.
3789 \begin_layout Subsection
3793 \begin_layout Standard
3797 \begin_inset Flex Code
3800 \begin_layout Plain Layout
3806 file maps keystrokes to characters or strings.
3807 As the name suggests, it sets a keyboard mapping.
3809 \begin_inset Flex Code
3812 \begin_layout Plain Layout
3823 \begin_inset Flex Code
3826 \begin_layout Plain Layout
3841 \begin_inset Flex Code
3844 \begin_layout Plain Layout
3857 \begin_inset Flex Code
3860 \begin_layout Plain Layout
3869 \begin_inset Flex Code
3872 \begin_layout Plain Layout
3880 are described in this section.
3883 \begin_layout Labeling
3884 \labelwidthstring 00.00.0000
3885 \begin_inset Flex Code
3888 \begin_layout Plain Layout
3896 Map a character to a string
3899 \begin_layout LyX-Code
3914 \begin_layout Standard
3947 the double-quote (")
3964 must be escaped with a preceding backslash (
3975 \begin_layout Standard
3977 \begin_inset Flex MenuItem
3980 \begin_layout Plain Layout
3988 statement to cause the symbol
3989 \begin_inset Flex MenuItem
3992 \begin_layout Plain Layout
4000 to be output for the keystroke
4001 \begin_inset Flex MenuItem
4004 \begin_layout Plain Layout
4015 \begin_layout LyX-Code
4021 \begin_layout Labeling
4022 \labelwidthstring 00.00.0000
4023 \begin_inset Flex Code
4026 \begin_layout Plain Layout
4034 Specify an accent character
4037 \begin_layout LyX-Code
4046 \begin_layout Standard
4047 This will make the cha
4085 This is the dead key
4089 \begin_layout Plain Layout
4096 refers to a key that does not produce a character by itself, but when followed
4097 with another key, produces the desired accent character.
4098 For example, a German characte
4100 r with an umlaut like
4110 can be produced in this manner.
4119 \begin_layout Standard
4132 and then another key not in
4149 followed by the other, not allowed key, as output.
4153 \begin_inset Flex MenuItem
4156 \begin_layout Plain Layout
4164 cancels a dead key, so if
4175 \begin_inset Flex MenuItem
4178 \begin_layout Plain Layout
4187 , the cursor will not go one position backwards but will instead cancel
4203 might have had on the next keystroke.
4207 \begin_layout Standard
4208 The following example specifies that the character ' is to be an acute accent,
4209 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4212 \begin_layout LyX-Code
4215 kmod ' acute aeiouAEIOU
4218 \begin_layout Labeling
4219 \labelwidthstring 00.00.0000
4220 \begin_inset Flex Code
4223 \begin_layout Plain Layout
4229 Specify an exception to the accent character
4232 \begin_layout LyX-Code
4241 \begin_layout Standard
4242 This defines an exce
4283 have been assigned a keystroke with a previous
4286 \begin_inset Flex Code
4289 \begin_layout Plain Layout
4313 must not belong in the
4360 If such a declaration does not exist in
4368 \begin_inset Flex Code
4371 \begin_layout Plain Layout
4405 \begin_inset Flex Code
4408 \begin_layout Plain Layout
4422 \begin_layout Standard
4423 The following command produces causes äi to be produced when you enter acute-i
4427 \begin_layout LyX-Code
4441 \begin_layout Labeling
4442 \labelwidthstring 00.00.0000
4443 \begin_inset Flex Code
4446 \begin_layout Plain Layout
4452 Combine two accent characters
4455 \begin_layout LyX-Code
4461 accent1 accent2 allowed
4464 \begin_layout Standard
4465 This one is getting pretty esoteric.
4466 It allows you to combine the effect
4522 \begin_inset Flex Code
4525 \begin_layout Plain Layout
4553 \begin_layout Standard
4554 Consider this example from the
4555 \begin_inset Flex Code
4558 \begin_layout Plain Layout
4569 \begin_layout LyX-Code
4572 kmod ; acute aeioyvhAEIOYVH
4576 kcomb acute umlaut iyIY
4579 \begin_layout Standard
4580 This allows you to press
4581 \begin_inset Flex MenuItem
4584 \begin_layout Plain Layout
4592 and get the effect of
4593 \begin_inset Flex Code
4596 \begin_layout Plain Layout
4615 in this case cancels the last dead key, so if you press
4616 \begin_inset Flex MenuItem
4619 \begin_layout Plain Layout
4628 \begin_inset Flex Code
4631 \begin_layout Plain Layout
4644 \begin_layout Subsection
4648 \begin_layout Standard
4650 \begin_inset Flex Code
4653 \begin_layout Plain Layout
4661 mapping is performed, a
4662 \begin_inset Flex Code
4665 \begin_layout Plain Layout
4675 file maps the strings that the symbols generate to characters in the current
4677 The LyX distribution currently includes at least the
4678 \begin_inset Flex Code
4681 \begin_layout Plain Layout
4690 \begin_inset Flex Code
4693 \begin_layout Plain Layout
4704 \begin_layout Standard
4706 \begin_inset Flex Code
4709 \begin_layout Plain Layout
4717 file is a sequence of declarations of the form
4720 \begin_layout LyX-Code
4733 \begin_layout Standard
4734 For example, in order to map
4735 \begin_inset Flex MenuItem
4738 \begin_layout Plain Layout
4748 to the corresponding character in the iso-8859-1 set (233), the following
4752 \begin_layout LyX-Code
4760 \begin_layout Standard
4762 \begin_inset Flex Code
4765 \begin_layout Plain Layout
4774 \begin_inset Flex Code
4777 \begin_layout Plain Layout
4795 the same character can apply to more than one string.
4797 \begin_inset Flex Code
4800 \begin_layout Plain Layout
4811 \begin_layout LyX-Code
4823 \begin_inset Newline newline
4839 \begin_layout Standard
4840 If LyX cannot find a mapping for the string produced by the keystroke or
4841 a deadkey sequence, it will check if it looks like an accented char and
4842 try to draw an accent over the character on screen.
4845 \begin_layout Subsection
4849 \begin_layout Standard
4850 There is a second way to add support for international characters through
4851 so-called dead-keys.
4852 A dead-key works in combination with a letter to produce an accented character.
4853 Here, we'll explain how to create a really simple dead-key to illustrate
4857 \begin_layout Standard
4858 Suppose you happen to need the circumflex character,
4859 \begin_inset Quotes eld
4863 \begin_inset Quotes erd
4868 \begin_inset Flex MenuItem
4871 \begin_layout Plain Layout
4878 \begin_inset space ~
4882 \begin_inset Flex MenuItem
4885 \begin_layout Plain Layout
4891 ] to the LyX command
4892 \begin_inset Flex Code
4895 \begin_layout Plain Layout
4902 \begin_inset Flex Code
4905 \begin_layout Plain Layout
4912 Now, whenever you type the
4913 \begin_inset Flex MenuItem
4916 \begin_layout Plain Layout
4922 -key followed by a letter, that letter will have a circumflex accent on
4924 For example, the sequence
4925 \begin_inset Quotes eld
4929 \begin_inset Flex MenuItem
4932 \begin_layout Plain Layout
4939 \begin_inset Quotes erd
4942 produces the letter:
4943 \begin_inset Quotes eld
4947 \begin_inset Quotes erd
4951 If you tried to type
4952 \begin_inset Quotes eld
4956 \begin_inset Flex MenuItem
4959 \begin_layout Plain Layout
4966 \begin_inset Quotes erd
4969 , however, LyX will complain with a beep, since a
4970 \begin_inset Quotes eld
4974 \begin_inset Flex MenuItem
4977 \begin_layout Plain Layout
4984 \begin_inset Quotes erd
4987 never takes a circumflex accent.
4989 \begin_inset Flex MenuItem
4992 \begin_layout Plain Layout
4998 after a dead-key produces the bare-accent.
4999 Please note this last point! If you bind a key to a dead-key, you'll need
5000 to rebind the character on that key to yet another key.
5002 \begin_inset Flex MenuItem
5005 \begin_layout Plain Layout
5011 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5014 \begin_layout Standard
5015 One common way to bind dead-keys is to use
5016 \begin_inset Flex MenuItem
5019 \begin_layout Plain Layout
5026 \begin_inset Flex MenuItem
5029 \begin_layout Plain Layout
5036 \begin_inset Flex MenuItem
5039 \begin_layout Plain Layout
5045 in combination with an accent, like
5046 \begin_inset Quotes eld
5050 \begin_inset Flex MenuItem
5053 \begin_layout Plain Layout
5060 \begin_inset Quotes erd
5064 \begin_inset Quotes eld
5068 \begin_inset Flex MenuItem
5071 \begin_layout Plain Layout
5078 \begin_inset Quotes erd
5082 \begin_inset Quotes eld
5086 \begin_inset Flex MenuItem
5089 \begin_layout Plain Layout
5096 \begin_inset Quotes erd
5100 Another way involves using
5101 \begin_inset Flex Code
5104 \begin_layout Plain Layout
5111 \begin_inset Flex Code
5114 \begin_layout Plain Layout
5120 to set up the special
5121 \begin_inset Flex Code
5124 \begin_layout Plain Layout
5132 \begin_inset Flex Code
5135 \begin_layout Plain Layout
5141 acts in some ways just like
5142 \begin_inset Flex MenuItem
5145 \begin_layout Plain Layout
5151 and permits you to bind keys to accented characters.
5152 You can also turn keys into dead-keys by binding them to something like
5154 \begin_inset Flex Code
5157 \begin_layout Plain Layout
5163 and then binding this symbolic key to the corresponding LyX command.
5167 \begin_layout Plain Layout
5172 : This is exactly what I do in my
5173 \begin_inset Flex Code
5176 \begin_layout Plain Layout
5183 \begin_inset Flex Code
5186 \begin_layout Plain Layout
5194 \begin_inset Flex MenuItem
5197 \begin_layout Plain Layout
5199 \begin_inset space ~
5208 \begin_inset Flex Code
5211 \begin_layout Plain Layout
5217 and a bunch of these
5218 \begin_inset Quotes eld
5222 \begin_inset Flex Code
5225 \begin_layout Plain Layout
5232 \begin_inset Quotes erd
5235 symbolic keys bound such things as
5236 \begin_inset Flex MenuItem
5239 \begin_layout Plain Layout
5241 \begin_inset space ~
5250 \begin_inset Flex MenuItem
5253 \begin_layout Plain Layout
5255 \begin_inset space ~
5264 This is how I produce my accented characters.
5269 You can make just about anything into the
5270 \begin_inset Flex Code
5273 \begin_layout Plain Layout
5280 \begin_inset Flex MenuItem
5283 \begin_layout Plain Layout
5289 keys, a spare function key, etc.
5290 As for the LyX commands that produce accents, check the entry for
5291 \begin_inset Flex Code
5294 \begin_layout Plain Layout
5305 You'll find the complete list there.
5308 \begin_layout Subsection
5309 Saving your Language Configuration
5312 \begin_layout Standard
5313 You can edit your preferences so that your desired language environment
5314 is automatically configured when LyX starts up, via the
5315 \begin_inset Flex MenuItem
5318 \begin_layout Plain Layout
5319 Edit\SpecialChar \menuseparator
5328 \begin_layout Chapter
5329 Installing New Document Classes, Layouts, and Templates
5330 \begin_inset CommandInset label
5332 name "cha:Installing-New-Document"
5337 \begin_inset Argument
5340 \begin_layout Plain Layout
5341 Installing New Document Classes
5349 \begin_layout Standard
5350 In this chapter, we describe the procedures for creating and installing
5351 new LyX layout and template files, as well as offer a refresher on correctly
5352 installing new LaTeX document classes.
5356 \begin_layout Standard
5357 First, let us a say a few words about how one ought to think about the relation
5358 between LyX and LaTeX.
5359 The thing to understand is that, in a certain sense, LyX doesn't know anything
5361 Indeed, from LyX's point of view, LaTeX is just one of several
5362 \begin_inset Quotes eld
5366 \begin_inset Quotes erd
5369 in which it is capable of producing output.
5370 Other such formats are DocBook, plaintext, and XHTML.
5371 LaTeX is, of course, a particularly important format, but very little of
5372 the information LyX has about LaTeX is actually contained in the program
5377 \begin_layout Plain Layout
5378 Some commands are sufficiently complex that they are
5379 \begin_inset Quotes eld
5383 \begin_inset Quotes erd
5387 But the developers generally regard this as a Bad Thing.
5392 Rather, that information, even for the standard classes like
5393 \begin_inset Flex Code
5396 \begin_layout Plain Layout
5402 , is contained in `layout files'.
5403 Similarly, LyX itself does not know much about DocBook or XHTML.
5404 What it knows is contained in layout files.
5407 \begin_layout Standard
5408 You can think of the layout file for a given document class as a translation
5409 manual between LyX constructs---paragraphs with their corresponding styles,
5410 certain sorts of insets, etc---and the corresponding LaTeX, DocBook, or
5412 Almost everything LyX knows about
5413 \begin_inset Flex Code
5416 \begin_layout Plain Layout
5422 , for example, is contained in the file
5423 \begin_inset Flex Code
5426 \begin_layout Plain Layout
5432 and in various other files it includes.
5433 For this reason, anyone intending to write layout files should plan to
5434 study the existing files.
5435 A good place to start is with
5436 \begin_inset Flex Code
5439 \begin_layout Plain Layout
5445 , which is included in
5446 \begin_inset Flex Code
5449 \begin_layout Plain Layout
5456 \begin_inset Flex Code
5459 \begin_layout Plain Layout
5465 , and many of the other layout files for document classes.
5466 This file is where sections and the like are defined:
5467 \begin_inset Flex Code
5470 \begin_layout Plain Layout
5476 tells LyX how paragraphs that are marked with the Section, Subsection,
5477 etc, styles can be translated into corresponding LaTeX, DocBook, and XHTML
5480 \begin_inset Flex Code
5483 \begin_layout Plain Layout
5489 file basically just includes several of these
5490 \begin_inset Flex Code
5493 \begin_layout Plain Layout
5502 \begin_layout Standard
5503 Defining the LyX--LaTeX correspondence is not the only thing layout files
5505 Their other job is to define how the LyX constructs themselves will appear
5507 The fact that layout files have these two jobs is often a source of confusion,
5508 because they are completely separate.
5509 Telling LyX how to translate a certain paragraph style into LaTeX does
5510 not tell LyX how to display it; conversely, telling LyX how to display
5511 a certain paragraph style does not tell LyX how to translate it into LaTeX
5512 (let alone tell LaTeX how to display it).
5513 So, in general, when you define a new LyX construct, you must always do
5514 two quite separate things: (i)
5515 \begin_inset space ~
5518 tell LyX how to translate it into LaTeX and (ii)
5519 \begin_inset space ~
5522 tell LyX how to display it.
5525 \begin_layout Standard
5526 Much the same is true, of course, as regards LyX's other backend formats,
5527 though XHTML is in some ways different, because in that case LyX
5531 able, to some extent, to use information about how it should display a
5532 paragraph on the screen to output information (in the form of CSS) about
5533 how the paragraph should be displayed in a browser.
5534 Even in this case, however, the distinction between what LyX does internally
5535 and how things are rendered externally remains in force, and the two can
5536 be controlled separately.
5538 \begin_inset CommandInset ref
5540 reference "sec:Tags-for-XHTML"
5547 \begin_layout Section
5548 Installing new LaTeX files
5551 \begin_layout Standard
5552 Some installations may not include a LaTeX package or class file that you
5553 would like to use within LyX.
5554 For example, you might need FoilTeX, a package for preparing slides for
5555 overhead projectors.
5556 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5557 a user interface for installing such packages.
5558 For example, with MiKTeX, you start the program
5559 \begin_inset Quotes eld
5563 \begin_inset space ~
5567 \begin_inset Quotes erd
5570 to get a list of available packages.
5571 To install one of them, right click on it or use the corresponding toolbar
5575 \begin_layout Standard
5576 If your LaTeX distribution does not provide such a `package manager', or
5577 if the package is not available from your distribution, then follow these
5578 steps to install it manually:
5581 \begin_layout Enumerate
5582 Get the package from
5583 \begin_inset CommandInset href
5586 target "http://www.ctan.org/"
5593 \begin_layout Enumerate
5594 If the package contains a file with the ending
5595 \begin_inset Quotes eld
5599 \begin_inset Flex Code
5602 \begin_layout Plain Layout
5609 \begin_inset Quotes erd
5612 (is the case for FoilTeX) then open a console, change to the folder of
5613 this file and execute the command
5614 \begin_inset Flex Code
5617 \begin_layout Plain Layout
5624 You have now unpacked the package and have all files to install it.
5625 Most LaTeX-packages are not packed and you can skip this step.
5628 \begin_layout Enumerate
5629 Now you need to decide if the package should be available for all users
5634 \begin_layout Enumerate
5635 On *nix systems (Linux, OSX, etc.), if you want the new package to be available
5636 for all users on your system, then install it in your `local' TeX tree,
5637 otherwise install it in your own `user' TeX tree.
5638 Where these trees should be created, if they do not already exist, depends
5640 To find this out, look in the file
5641 \begin_inset Flex Code
5644 \begin_layout Plain Layout
5654 \begin_layout Plain Layout
5655 This is usually in the directory
5656 \begin_inset Flex Code
5659 \begin_layout Plain Layout
5665 , though you can execute the command
5666 \begin_inset Flex Code
5669 \begin_layout Plain Layout
5680 The location of the `local' TeX tree is defined by the
5681 \begin_inset Flex Code
5684 \begin_layout Plain Layout
5690 variable; this is usually somewhere like
5691 \begin_inset Flex Code
5694 \begin_layout Plain Layout
5695 /usr/local/share/texmf
5701 The location of the `user' TeX tree is defined by
5702 \begin_inset Flex Code
5705 \begin_layout Plain Layout
5712 \begin_inset Flex Code
5715 \begin_layout Plain Layout
5722 (If these variables are not predefined, you have to define them.) You'll
5723 probably need root permissions to create or modify the `local' tree, but
5724 not for your `user' tree.
5725 \begin_inset Newline newline
5728 In general, it is recommended to install in the user tree because your user
5729 will not be modified or even overwritten when you upgrade your system.
5730 It will typically also be backed up together with everything else when
5731 you backup your home directory (which, of course, you do on a regular basis).
5734 \begin_layout Enumerate
5735 On Windows, if you want the new package to be available for all users on
5736 your system, change to the folder where LaTeX is installed and then change
5738 \begin_inset Flex Code
5741 \begin_layout Plain Layout
5752 (For MiKTeX, this would be by default the folder
5753 \begin_inset Flex Code
5756 \begin_layout Plain Layout
5774 \begin_layout Plain Layout
5775 Note that this will be the correct path only on English installations.
5776 On a German one, it would be
5777 \begin_inset Flex Code
5780 \begin_layout Plain Layout
5794 , and similarly for other languages.
5799 Create there a new folder
5800 \begin_inset Flex Code
5803 \begin_layout Plain Layout
5809 and copy all files of the package into it.
5811 \begin_inset Newline newline
5814 If the package should only available for you or you don't have admin permissions
5815 , do the same, but in the local LaTeX folder.
5817 \begin_inset space \thinspace{}
5821 \begin_inset space ~
5824 2.8 under Windows XP, this would be the folder:
5825 \begin_inset Newline newline
5831 \begin_inset Flex Code
5834 \begin_layout Plain Layout
5837 Documents and Settings
5849 \begin_inset Newline newline
5855 \begin_inset Phantom HPhantom
5858 \begin_layout Plain Layout
5869 \begin_inset Flex Code
5872 \begin_layout Plain Layout
5885 \begin_inset Newline newline
5888 On Vista, it would be:
5889 \begin_inset Newline newline
5893 \begin_inset Flex Code
5896 \begin_layout Plain Layout
5922 \begin_layout Enumerate
5923 Now one only need to tell LaTeX that there are new files.
5924 This depends on the used LaTeX-Distribution:
5928 \begin_layout Enumerate
5929 For TeXLive execute the command
5930 \begin_inset Flex Code
5933 \begin_layout Plain Layout
5940 If you installed the package for all users, then you will probably need
5941 to have root permissions for that.
5944 \begin_layout Enumerate
5945 For MiKTeX, if you have installed the package for all users, start the program
5947 \begin_inset Quotes eld
5951 \begin_inset space ~
5955 \begin_inset Quotes erd
5958 and press the button marked
5959 \begin_inset Quotes eld
5963 \begin_inset Quotes erd
5967 Otherwise start the program
5968 \begin_inset Quotes eld
5972 \begin_inset Quotes erd
5979 \begin_layout Enumerate
5980 Finally, you need to tell LyX that there are new packages available.
5981 So, in LyX, use the menu
5982 \begin_inset Flex MenuItem
5985 \begin_layout Plain Layout
5988 \SpecialChar \menuseparator
5994 and then restart LyX.
5997 \begin_layout Standard
5998 Now the package is installed.
5999 In our example, the document class
6000 \begin_inset Flex Code
6003 \begin_layout Plain Layout
6005 \begin_inset space ~
6012 \begin_layout Plain Layout
6024 will now be available under
6025 \begin_inset Flex MenuItem
6028 \begin_layout Plain Layout
6029 Document\SpecialChar \menuseparator
6030 Settings\SpecialChar \menuseparator
6040 \begin_layout Standard
6041 If you would like to use a LaTeX document class that is not even listed
6043 \begin_inset Flex MenuItem
6046 \begin_layout Plain Layout
6047 Document\SpecialChar \menuseparator
6048 Settings\SpecialChar \menuseparator
6054 , then you need to create a `layout' file for it.
6055 That is the topic of the next section.
6058 \begin_layout Section
6059 Types of layout files
6062 \begin_layout Standard
6063 This section describes the various sorts of LyX files that contain layout
6065 These files describe various paragraph and character styles, determining
6066 how LyX should display them and how they should be translated into LaTeX,
6067 DocBook, XHTML, or whatever output format is being used.
6071 \begin_layout Standard
6072 We shall try to provide a thorough description of the process of writing
6074 However, there are so many different types of documents supported even
6075 by just LaTeX that we can't hope to cover every different possibility or
6076 problem you might encounter.
6077 The LyX users' list is frequented by people with lots of experience with
6078 layout design who are willing to share what they've learned, so please
6079 feel free to ask questions there.
6082 \begin_layout Standard
6083 As you prepare to write a new layout, it is extremely helpful to look at
6084 the layouts distributed with LyX.
6085 If you write a LyX layout for a LaTeX document class that might also be
6086 used by others, or write a module that might be useful to others, then
6087 you should consider posting your layout to the
6088 \begin_inset CommandInset href
6090 name "layout section on the LyX wiki"
6091 target "http://wiki.lyx.org/Layouts/Layouts"
6095 or even to the LyX developers' list, so that it might be included in LyX
6100 \begin_layout Plain Layout
6101 Note that LyX is licensed under the General Public License, so any material
6102 that is contributed to LyX must be similarly licensed.
6110 \begin_layout Subsection
6112 \begin_inset CommandInset label
6114 name "sub:Layout-modules"
6121 \begin_layout Standard
6122 We have spoken to this point about `layout files'.
6123 But there are different sorts of files that contain layout information.
6124 Layout files, strictly so called, have the
6125 \begin_inset Flex Code
6128 \begin_layout Plain Layout
6134 extension and provide LyX with information about document classes.
6135 As of LyX 1.6, however, layout information can also be contained in layout
6141 \begin_inset Flex Code
6144 \begin_layout Plain Layout
6151 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6152 some modules—such as the
6153 \begin_inset Flex Code
6156 \begin_layout Plain Layout
6162 module—specifically provide support for one package.
6163 In a sense, layout modules are similar to included
6167 \begin_layout Plain Layout
6168 These can have any extension, but by convention have the
6169 \begin_inset Flex Code
6172 \begin_layout Plain Layout
6184 \begin_inset Flex Code
6187 \begin_layout Plain Layout
6193 —in that modules are not specific to a given document class but may be used
6194 with many different classes.
6195 The difference is that using an included file with
6196 \begin_inset Flex Code
6199 \begin_layout Plain Layout
6205 requires editing that file.
6206 Modules, by contrast, are selected in the
6207 \begin_inset Flex MenuItem
6210 \begin_layout Plain Layout
6211 Document\SpecialChar \menuseparator
6220 \begin_layout Standard
6221 Building modules is the easiest way to get started with layout editing,
6222 since it can be as simple as adding a single new paragraph style or flex
6224 But modules may, in principle, contain anything a layout file can contain.
6227 \begin_layout Standard
6228 After creating a new module and copying it to the
6229 \begin_inset Flex Code
6232 \begin_layout Plain Layout
6238 folder, you will need to reconfigure and then restart LyX for the module
6239 to appear in the menu.
6240 However, changes you make to the module will be seen immediately, if you
6242 \begin_inset Flex MenuItem
6245 \begin_layout Plain Layout
6246 Document\SpecialChar \menuseparator
6252 , highlight something, and then hit
6253 \begin_inset Quotes eld
6257 \begin_inset Quotes erd
6263 It is strongly recommended that you save your work before doing this
6268 it is strongly recommended that you not attempt to edit modules while simultaneo
6269 usly working on actual documents
6272 Though of course the developers strive to keep LyX stable in such situations,
6273 syntax errors and the like in your module file could cause strange behavior.
6276 \begin_layout Subsubsection
6280 \begin_layout Standard
6281 Modules are to LyX as packages are to LaTeX.
6282 Sometimes, however, you find yourself wanting a specific inset or character
6283 style just for one document and writing a module that will also be available
6284 to other documents makes little sense.
6285 What you need is LyX's
6286 \begin_inset Quotes eld
6290 \begin_inset Quotes erd
6296 \begin_layout Standard
6297 You will find it under
6299 Document\SpecialChar \menuseparator
6300 Settings\SpecialChar \menuseparator
6304 The large text box allows you to enter anything that you might enter in
6305 a layout file or module.
6306 You can think of a document's local layout, in fact, as a module that belongs
6308 So, in particular, you must enter a
6309 \begin_inset Flex Code
6312 \begin_layout Plain Layout
6319 Any format is acceptable, but one would normally use the format current
6321 (In LyX 2.0, the current layout format is 35.) You should be aware that local
6322 layout is not supported by versions of LyX prior to 1.6, so you should not
6323 use it if you want to be able to export your document to LyX 1.5 or earlier
6324 (without, that is, losing the local layout information).
6325 If you wish to be able to export to 1.6---local layout is supported in 1.6,
6326 though there is no UI for it---then you should use format 11 and, of course,
6327 use only layout constructs that were available in LyX 1.6.
6330 \begin_layout Standard
6331 When you have entered something in the
6332 \begin_inset Flex Code
6335 \begin_layout Plain Layout
6341 pane, LyX will enable the
6342 \begin_inset Quotes eld
6346 \begin_inset Quotes erd
6349 button at the bottom.
6350 Clicking this button will cause LyX to determine whether what you have
6351 entered is valid layout information for the chosen format.
6352 LyX will report the result but, unfortunately, will not tell you what errors
6353 there might have been.
6354 These will be written to the terminal, however, if LyX is started from
6356 You will not be permitted to save your local layout until you have entered
6360 \begin_layout Standard
6361 The warnings at the end of the previous section apply here, too.
6362 Do not play with local layout while you are actually working, especially
6363 if you have not saved your document.
6364 That said, using local layout with a test document can be a very convenient
6365 way to try out layout ideas, or even to start developing a module.
6368 \begin_layout Subsection
6370 \begin_inset Flex MenuItem
6373 \begin_layout Plain Layout
6382 \begin_layout Standard
6383 There are two situations you are likely to encounter when wanting to support
6384 a new LaTeX document class, involving style (
6385 \begin_inset Flex Code
6388 \begin_layout Plain Layout
6394 ) files and LaTeX2e class (
6395 \begin_inset Flex Code
6398 \begin_layout Plain Layout
6405 Supporting a style file is usually fairly easy.
6406 Supporting a new class file is a bit harder.
6407 We'll discuss the former in this section and the latter in the next.
6408 Similar remarks apply, of course, if you want to support a new DocBook
6412 \begin_layout Standard
6413 The easier case is the one in which your new document class is provided
6414 as a style file that is to be used in conjunction with an already supported
6416 For the sake of the example, we'll assume that the style file is called
6418 \begin_inset Flex MenuItem
6421 \begin_layout Plain Layout
6427 and that it is meant to be used with
6428 \begin_inset Flex MenuItem
6431 \begin_layout Plain Layout
6437 , which is a standard class.
6441 \begin_layout Standard
6442 Start by copying the existing class's layout file into your local directory:
6446 \begin_layout Plain Layout
6447 Of course, which directory is your local directory will vary by platform,
6448 and LyX allows you to specify your local directory on startup, too, using
6450 \begin_inset Flex Code
6453 \begin_layout Plain Layout
6467 \begin_layout LyX-Code
6468 cp report.layout ~/.lyx/layouts/myclass.layout
6471 \begin_layout Standard
6473 \begin_inset Flex Code
6476 \begin_layout Plain Layout
6482 and change the line:
6485 \begin_layout LyX-Code
6488 DeclareLaTeXClass{report}
6491 \begin_layout Standard
6495 \begin_layout LyX-Code
6498 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6501 \begin_layout Standard
6505 \begin_layout LyX-Code
6507 \begin_inset Newline newline
6513 \begin_inset Newline newline
6519 \begin_layout Standard
6520 near the top of the file.
6523 \begin_layout Standard
6524 Start LyX and select
6525 \begin_inset Flex MenuItem
6528 \begin_layout Plain Layout
6529 Tools\SpecialChar \menuseparator
6536 Then restart LyX and try creating a new document.
6538 \begin_inset Flex MenuItem
6541 \begin_layout Plain Layout
6547 " as a document class option in the
6548 \begin_inset Flex MenuItem
6551 \begin_layout Plain Layout
6552 Document\SpecialChar \menuseparator
6559 It is likely that some of the sectioning commands and such in your new
6560 class will work differently from how they worked in the base class—
6561 \begin_inset Flex Code
6564 \begin_layout Plain Layout
6570 in this example—so you can fiddle around with the settings for the different
6571 sections if you wish.
6572 The layout information for sections is contained in
6573 \begin_inset Flex Code
6576 \begin_layout Plain Layout
6582 , but you do not need to copy and change this file.
6583 Instead, you can simply add your changes to your layout file, after the
6585 \begin_inset Flex Code
6588 \begin_layout Plain Layout
6594 , which itself includes
6595 \begin_inset Flex Code
6598 \begin_layout Plain Layout
6605 For example, you might add these lines:
6608 \begin_layout LyX-Code
6612 \begin_layout LyX-Code
6616 \begin_layout LyX-Code
6620 \begin_layout LyX-Code
6624 \begin_layout LyX-Code
6628 \begin_layout Standard
6629 to change the font for chapter headings to sans-serif.
6630 This will override (or, in this case, add to) the existing declaration
6631 for the Chapter style.
6635 \begin_layout Standard
6636 Your new package may also provide commands or environments not present in
6638 In this case, you will want to add these to the layout file.
6640 \begin_inset CommandInset ref
6642 reference "sec:TextClass"
6646 for information on how to do so.
6649 \begin_layout Standard
6651 \begin_inset Flex MenuItem
6654 \begin_layout Plain Layout
6660 can be used with several different document classes, and even if it cannot,
6661 you might find it easiest just to write a module that you can load with
6663 The simplest possible such module would be:
6666 \begin_layout LyX-Code
6669 DeclareLyXModule{My Package}
6672 \begin_layout LyX-Code
6676 \begin_layout LyX-Code
6677 #Support for mypkg.sty.
6680 \begin_layout LyX-Code
6682 \begin_inset Newline newline
6688 \begin_layout LyX-Code
6690 \begin_inset Newline newline
6696 \begin_layout LyX-Code
6698 \begin_inset Newline newline
6704 \begin_inset Newline newline
6710 \begin_layout Standard
6711 A more complex module might modify the behavior of some existing constructs
6712 or define some new ones.
6714 \begin_inset CommandInset ref
6716 reference "sec:TextClass"
6723 \begin_layout Subsection
6725 \begin_inset Flex MenuItem
6728 \begin_layout Plain Layout
6737 \begin_layout Standard
6738 There are two possibilities here.
6739 One is that the class file is itself based upon an existing document class.
6740 For example, many thesis classes are based upon
6741 \begin_inset Flex MenuItem
6744 \begin_layout Plain Layout
6751 To see whether yours is, look for a line like
6754 \begin_layout LyX-Code
6760 \begin_layout Standard
6762 If so, then you may proceed largely as in the previous section, though
6764 \begin_inset Flex Code
6767 \begin_layout Plain Layout
6773 line will be different.
6774 If your new class is
6775 \begin_inset Flex Code
6778 \begin_layout Plain Layout
6784 and it is based upon
6785 \begin_inset Flex Code
6788 \begin_layout Plain Layout
6794 , then the line should read:
6798 \begin_layout Plain Layout
6799 And it will be easiest if you save the file to
6800 \begin_inset Flex Code
6803 \begin_layout Plain Layout
6809 : LyX assumes that the document class has the same name as the layout file.
6818 \begin_layout LyX-Code
6821 DeclareLaTeXClass[thesis,book]{thesis}
6824 \begin_layout Standard
6825 If, on the other hand, the new class is not based upon an existing class,
6826 you will probably have to
6827 \begin_inset Quotes eld
6831 \begin_inset Quotes erd
6835 We strongly suggest copying an existing layout file which uses a similar
6836 LaTeX class and then modifying it, if you can do so.
6837 At least use an existing file as a starting point so you can find out what
6838 items you need to worry about.
6839 Again, the specifics are covered below.
6842 \begin_layout Subsection
6844 \begin_inset CommandInset label
6846 name "sub:Creating-Templates"
6853 \begin_layout Standard
6854 Once you have written a layout file for a new document class, you might
6855 want to consider writing a
6860 A template acts as a kind of tutorial for your layout, showing how it might
6861 be used, though containing dummy content.
6862 You can of course look at the various templates included with LyX for ideas.
6865 \begin_layout Standard
6866 Templates are created just like usual documents: using LyX.
6867 The only difference is that usual documents contain all possible settings,
6868 including the font scheme and the paper size.
6869 Usually a user doesn't want a template to overwrite his preferred settings
6870 for such parameters.
6871 For that reason, the designer of a template should remove the corresponding
6873 \begin_inset Flex Code
6876 \begin_layout Plain Layout
6885 \begin_inset Flex Code
6888 \begin_layout Plain Layout
6896 from the template LyX file.
6897 This can be done with any simple text-editor, for example
6898 \begin_inset Flex Code
6901 \begin_layout Plain Layout
6908 \begin_inset Flex Code
6911 \begin_layout Plain Layout
6921 \begin_layout Standard
6922 Put the edited template files you create in
6923 \begin_inset Flex Code
6926 \begin_layout Plain Layout
6932 , copy the ones you use from the global template directory in
6933 \begin_inset Flex Code
6936 \begin_layout Plain Layout
6942 to the same place, and redefine the template path in the
6943 \begin_inset Flex MenuItem
6946 \begin_layout Plain Layout
6947 Tools\SpecialChar \menuseparator
6948 Preferences\SpecialChar \menuseparator
6957 \begin_layout Standard
6958 Note, by the way, that there is a template which has a particular meaning:
6960 \begin_inset Flex Code
6963 \begin_layout Plain Layout
6970 This template is loaded every time you create a new document with
6971 \begin_inset Flex MenuItem
6974 \begin_layout Plain Layout
6975 File\SpecialChar \menuseparator
6981 in order to provide useful defaults.
6982 To create this template from inside LyX, all you have to do is to open
6983 a document with the correct settings, and use the
6984 \begin_inset Flex MenuItem
6987 \begin_layout Plain Layout
6988 Save as Document Defaults
6996 \begin_layout Subsection
6997 Upgrading old layout files
7000 \begin_layout Standard
7001 The format of layout files changes with each LyX release, so old layout
7002 files need to be converted to the new format.
7003 This process has been automated since LyX 1.4: If LyX reads a layout file
7004 in an older format, it automatically calls the script
7005 \begin_inset Flex Code
7008 \begin_layout Plain Layout
7014 to convert it to a temporary file in current format.
7015 The original file is left untouched.
7016 If you use the layout file often, then, you may want to convert it permanently,
7017 so that LyX does not have to do so itself every time.
7018 To do this, you can call the converter manually:
7021 \begin_layout LyX-Code
7022 mv myclass.layout myclass.old
7025 \begin_layout LyX-Code
7026 python LyXDir/scripts/layout2layout.py myclass.old myclass.layout
7029 \begin_layout Standard
7031 \begin_inset Flex Code
7034 \begin_layout Plain Layout
7040 with the name of your LyX system directory, of course.
7043 \begin_layout Standard
7044 Note that manual conversion does not affect included files, so these will
7045 have to be converted separately.
7048 \begin_layout Section
7049 \begin_inset CommandInset label
7051 name "sec:TextClass"
7055 The layout file format
7058 \begin_layout Standard
7059 When it's finally time to get your hands dirty and create or edit your own
7060 layout file, the following sections describe what you're up against.
7061 Our advice is to go slowly, save and test often, listen to soothing music,
7062 and enjoy one or two of your favorite adult beverages; more if you are
7063 getting particularly stuck.
7064 It's really not that hard, except that the multitude of options can become
7065 overwhelming if you try to do too much in one sitting.
7066 Go have another adult beverage, just for good measure.
7069 \begin_layout Standard
7070 Note that all the tags used in layout files are case-insensitive.
7072 \begin_inset Flex Code
7075 \begin_layout Plain Layout
7082 \begin_inset Flex Code
7085 \begin_layout Plain Layout
7092 \begin_inset Flex Code
7095 \begin_layout Plain Layout
7101 are really the same tag.
7102 The possible values are printed in brackets after the feature's name.
7103 The default value if a feature isn't specified inside a text class-description
7105 \begin_inset Flex Code
7108 \begin_layout Plain Layout
7117 If the argument has a data type like
7118 \begin_inset Quotes eld
7122 \begin_inset Quotes erd
7126 \begin_inset Quotes eld
7130 \begin_inset Quotes erd
7133 , the default is shown like this:
7134 \begin_inset Flex Code
7137 \begin_layout Plain Layout
7148 \begin_layout Subsection
7149 The document class declaration
7152 \begin_layout Standard
7153 Lines in a layout file which begin with
7154 \begin_inset Flex Code
7157 \begin_layout Plain Layout
7164 There is one exception to this rule.
7166 \begin_inset Flex Code
7169 \begin_layout Plain Layout
7175 files should begin with a line like:
7178 \begin_layout LyX-Code
7181 #% Do not delete the line below; configure depends on this
7184 \begin_layout LyX-Code
7189 DeclareLaTeXClass{article}
7192 \begin_layout Standard
7193 The second line is used when you (re)configure LyX.
7194 The layout file is read by the LaTeX script
7195 \begin_inset Flex Code
7198 \begin_layout Plain Layout
7204 , in a special mode where
7205 \begin_inset Flex Code
7208 \begin_layout Plain Layout
7215 The first line is just a LaTeX comment, and the second one contains the
7216 declaration of the text class.
7217 If these lines appear in a file named
7218 \begin_inset Flex Code
7221 \begin_layout Plain Layout
7227 , then they define a text class of name
7228 \begin_inset Flex Code
7231 \begin_layout Plain Layout
7237 (the name of the layout file) which uses the LaTeX document class
7238 \begin_inset Flex Code
7241 \begin_layout Plain Layout
7247 (the default is to use the same name as the layout).
7249 \begin_inset Quotes eld
7253 \begin_inset Quotes erd
7256 that appears above is used as a description of the text class in the
7257 \begin_inset Flex MenuItem
7260 \begin_layout Plain Layout
7261 Document\SpecialChar \menuseparator
7270 \begin_layout Standard
7271 Let's assume that you wrote your own text class that uses the
7272 \begin_inset Flex Code
7275 \begin_layout Plain Layout
7281 document class, but where you changed the appearance of the section headings.
7282 If you put it in a file
7283 \begin_inset Flex Code
7286 \begin_layout Plain Layout
7292 , the header of this file should be:
7295 \begin_layout LyX-Code
7298 #% Do not delete the line below; configure depends on this
7301 \begin_layout LyX-Code
7306 DeclareLaTeXClass[article]{article (with my own headings)}
7309 \begin_layout Standard
7310 This declares a text class
7311 \begin_inset Flex Code
7314 \begin_layout Plain Layout
7320 , associated with the LaTeX document class
7321 \begin_inset Flex Code
7324 \begin_layout Plain Layout
7331 \begin_inset Quotes eld
7334 article (with my own headings)
7335 \begin_inset Quotes erd
7339 If your text class depends on several packages, you can declare it as:
7342 \begin_layout LyX-Code
7345 #% Do not delete the line below; configure depends on this
7348 \begin_layout LyX-Code
7353 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
7356 \begin_layout Standard
7357 This indicates that your text class uses the
7358 \begin_inset Flex Code
7361 \begin_layout Plain Layout
7368 Finally, it is also possible to declare classes for DocBook code.
7369 Typical declarations will look like:
7372 \begin_layout LyX-Code
7375 #% Do not delete the line below; configure depends on this
7378 \begin_layout LyX-Code
7383 DeclareDocBookClass[article]{SGML (DocBook article)}
7386 \begin_layout Standard
7387 Note that these declarations can also be given an optional parameter declaring
7388 the name of the document class (but not a list).
7391 \begin_layout Standard
7392 So, to be as explicit as possible, the form of the layout declaration is:
7395 \begin_layout LyX-Code
7400 DeclareLaTeXClass[class,package.sty]{layout description}
7403 \begin_layout Standard
7404 The class need only be specified if the name of the LaTeX class file and
7405 the name of the layout file are different or if there are packages to load.
7406 If the name of the class file is not specified, then LyX will simply assume
7407 that it is the same as the name of the layout file.
7410 \begin_layout Standard
7411 When the text class has been modified to your taste, all you have to do
7412 is to copy it either to
7413 \begin_inset Flex Code
7416 \begin_layout Plain Layout
7423 \begin_inset Flex Code
7426 \begin_layout Plain Layout
7433 \begin_inset Flex MenuItem
7436 \begin_layout Plain Layout
7437 Tools\SpecialChar \menuseparator
7443 , exit LyX and restart.
7444 Then your new text class should be available along with the others.
7447 \begin_layout Standard
7448 Once the layout file is installed, you can edit it and see your changes
7449 without having to reconfigure or to restart LyX.
7454 \begin_layout Plain Layout
7455 In versions of LyX prior to 1.6, this was not true.
7456 As a result, editing layout files was very time consuming, since you had
7457 constantly to restart LyX to see changes.
7462 You can force a reload of the current layout by using the LyX function
7464 \begin_inset Flex MenuItem
7467 \begin_layout Plain Layout
7474 There is no default binding for this function—though, of course, you can
7475 bind it to a key yourself.
7476 But you will normally use this function simply by entering it in the mini-buffe
7481 \begin_layout Standard
7487 \begin_inset Flex MenuItem
7490 \begin_layout Plain Layout
7496 is very much an `advanced feature'.
7501 recommended that you save your work before using this function.
7506 recommended that you not attempt to edit layout information while simultaneousl
7507 y working on a document that you care about.
7508 Use a test document.
7509 Syntax errors and the like in your layout file could cause peculiar behavior.
7510 In particular, such errors could cause LyX to regard the current layout
7511 as invalid and to attempt to switch to some other layout.
7515 \begin_layout Plain Layout
7516 Really bad syntax errors may even caused LyX to exit.
7517 This is because certain sorts of errors may make LyX unable to read
7527 The LyX team strives to keep LyX stable in such situations, but safe is
7532 \begin_layout Plain Layout
7533 While we're giving advice: make regular backups.
7534 And be nice to your mother.
7542 \begin_layout Subsection
7543 The Module declaration
7546 \begin_layout Standard
7547 A module must begin with a line like the following:
7550 \begin_layout LyX-Code
7553 DeclareLyXModule[endnotes.sty]{Endnotes}
7556 \begin_layout Standard
7557 The mandatory argument, in curly brackets, is the name of the module, as
7559 \begin_inset Flex MenuItem
7562 \begin_layout Plain Layout
7563 Document\SpecialChar \menuseparator
7564 Settings\SpecialChar \menuseparator
7571 The argument in square brackets is optional: It declares any LaTeX packages
7572 on which the module depends.
7573 Please note that only packages about which LyX knows should be listed in
7574 the square brackets.
7578 \begin_layout Plain Layout
7579 The list of such packages is documented only in the source code.
7584 LyX will not check for arbitrary packages.
7585 It is also possible to use the form
7586 \begin_inset Flex MenuItem
7589 \begin_layout Plain Layout
7595 as an optional argument, which declares that the module can only be used
7596 when there exists a conversion chain between the formats `
7597 \begin_inset Flex Code
7600 \begin_layout Plain Layout
7607 \begin_inset Flex Code
7610 \begin_layout Plain Layout
7619 \begin_layout Standard
7620 The module declaration should then be followed by lines like the following
7624 \begin_layout Plain Layout
7625 Preferably in English if the module should be published with LyX.
7626 This description will appear in the list of messages to be translated and
7627 will be thus translated with the next interface update.
7635 \begin_layout LyX-Code
7639 \begin_layout LyX-Code
7640 #Adds an endnote command, in addition to footnotes.
7644 \begin_layout LyX-Code
7645 #You will need to add
7647 theendnotes in TeX code where you
7650 \begin_layout LyX-Code
7651 #want the endnotes to appear.
7655 \begin_layout LyX-Code
7659 \begin_layout LyX-Code
7660 #Requires: somemodule | othermodule
7663 \begin_layout LyX-Code
7664 #Excludes: badmodule
7667 \begin_layout Standard
7668 The description is used in
7669 \begin_inset Flex MenuItem
7672 \begin_layout Plain Layout
7673 Document\SpecialChar \menuseparator
7674 Settings\SpecialChar \menuseparator
7680 to provide the user with information about what the module does.
7682 \begin_inset Flex Code
7685 \begin_layout Plain Layout
7691 line is used to identify other modules with which this one must be used;
7693 \begin_inset Flex Code
7696 \begin_layout Plain Layout
7702 line is used to identify modules with which this one may not be used.
7703 Both are optional, and, as shown, multiple modules should be separated
7704 with the pipe symbol: |.
7705 Note that the required modules are treated disjunctively:
7709 of the required modules must be used.
7714 excluded module may be used.
7715 Note that modules are identified here by their
7720 \begin_inset Flex Code
7723 \begin_layout Plain Layout
7731 \begin_inset Flex Code
7734 \begin_layout Plain Layout
7741 \begin_inset Flex Code
7744 \begin_layout Plain Layout
7753 \begin_layout Subsection
7757 \begin_layout Standard
7758 The first non-comment line of any layout file, included file, or module
7763 contain the file format number:
7766 \begin_layout Description
7767 \begin_inset Flex Code
7770 \begin_layout Plain Layout
7777 \begin_inset Flex Code
7780 \begin_layout Plain Layout
7786 ] The format of the layout file.
7789 \begin_layout Standard
7790 This tag was introduced with LyX 1.4.0.
7791 Layout files from LyX 1.3.x and earlier don't have an explicit file format
7792 and are considered to be of format 1.
7793 The format for the present version of LyX is format 21.
7794 But each version of LyX is capable of reading earlier versions' layout
7795 files, just as they are capable of reading files produced by earlier versions
7797 There is, however, no provision for converting to earlier formats.
7798 So LyX 1.6.x will not read layout files in format 21 but only files in format
7802 \begin_layout Subsection
7803 \begin_inset CommandInset label
7805 name "sub:General-text-class"
7809 General text class parameters
7812 \begin_layout Standard
7813 These are general parameters that govern the behavior of an entire document
7819 mean that they must appear in
7820 \begin_inset Flex Code
7823 \begin_layout Plain Layout
7829 files rather than in modules.
7830 A module can contain any layout tag.)
7833 \begin_layout Description
7834 \begin_inset Flex Code
7837 \begin_layout Plain Layout
7843 Adds information that will be output in the
7844 \begin_inset Flex Code
7847 \begin_layout Plain Layout
7853 block when this document class is output to XHTML.
7854 Typically, this would be used to output CSS style information, but it can
7855 be used for anything that can appear in
7856 \begin_inset Flex Code
7859 \begin_layout Plain Layout
7867 \begin_inset Quotes eld
7871 \begin_inset Flex Code
7874 \begin_layout Plain Layout
7881 \begin_inset Quotes erd
7887 \begin_layout Description
7888 \begin_inset Flex Code
7891 \begin_layout Plain Layout
7897 Adds CSS styling information.
7898 This will either be output in a
7899 \begin_inset Quotes eld
7903 \begin_inset Flex Code
7906 \begin_layout Plain Layout
7913 \begin_inset Quotes erd
7916 block or, if the user has so chosen, to a separate CSS file.Must end with
7918 \begin_inset Quotes eld
7922 \begin_inset Flex Code
7925 \begin_layout Plain Layout
7932 \begin_inset Quotes erd
7938 \begin_layout Description
7939 \begin_inset Flex Code
7942 \begin_layout Plain Layout
7948 Adds information to the document preamble.
7950 \begin_inset Quotes eld
7954 \begin_inset Flex Code
7957 \begin_layout Plain Layout
7964 \begin_inset Quotes erd
7970 \begin_layout Description
7971 \begin_inset Flex Code
7974 \begin_layout Plain Layout
7980 Defines formats for use in the display of bibliographic information.
7982 \begin_inset CommandInset ref
7984 reference "sub:Citation-format-description"
7990 \begin_inset Quotes eld
7994 \begin_inset Flex Code
7997 \begin_layout Plain Layout
8004 \begin_inset Quotes erd
8010 \begin_layout Description
8011 \begin_inset Flex Code
8014 \begin_layout Plain Layout
8020 Describes various global options supported by the document class.
8022 \begin_inset space ~
8026 \begin_inset CommandInset ref
8028 reference "sub:ClassOptions"
8034 \begin_inset Quotes eld
8038 \begin_inset Flex Code
8041 \begin_layout Plain Layout
8048 \begin_inset Quotes erd
8054 \begin_layout Description
8055 \begin_inset Flex Code
8058 \begin_layout Plain Layout
8065 \begin_inset Flex Code
8068 \begin_layout Plain Layout
8077 \begin_inset Flex Code
8080 \begin_layout Plain Layout
8086 ] Whether the class should
8090 to having one or two columns.
8091 Can be changed in the
8092 \begin_inset Flex MenuItem
8095 \begin_layout Plain Layout
8096 Document\SpecialChar \menuseparator
8105 \begin_layout Description
8106 \begin_inset Flex Code
8109 \begin_layout Plain Layout
8116 \begin_inset Flex Code
8119 \begin_layout Plain Layout
8125 ] This sequence defines the properties for a counter.
8126 If the counter does not yet exist, it is created; if it does exist, it
8129 \begin_inset Quotes eld
8133 \begin_inset Flex Code
8136 \begin_layout Plain Layout
8143 \begin_inset Quotes erd
8147 \begin_inset Newline newline
8151 \begin_inset space ~
8155 \begin_inset CommandInset ref
8157 reference "sub:Counters"
8161 for details on counters.
8164 \begin_layout Description
8165 \begin_inset Flex Code
8168 \begin_layout Plain Layout
8174 Sets the default font used to display the document.
8176 \begin_inset space ~
8180 \begin_inset CommandInset ref
8182 reference "sub:Font-description"
8186 for how to declare fonts.
8188 \begin_inset Quotes eld
8192 \begin_inset Flex Code
8195 \begin_layout Plain Layout
8202 \begin_inset Quotes erd
8208 \begin_layout Description
8209 \begin_inset Flex Code
8212 \begin_layout Plain Layout
8219 \begin_inset Flex Code
8222 \begin_layout Plain Layout
8228 Specifies a module to be included by default with this document class.
8229 The module should be specified by filename without the
8230 \begin_inset Flex Code
8233 \begin_layout Plain Layout
8240 The user can still remove the module, but it will be active at the outset.
8241 (This applies only when new files are created, or when this class is chosen
8242 for an existing document.)
8245 \begin_layout Description
8246 \begin_inset Flex Code
8249 \begin_layout Plain Layout
8256 \begin_inset Flex Code
8259 \begin_layout Plain Layout
8265 ] This is the style that will be assigned to new paragraphs, usually
8266 \begin_inset Flex MenuItem
8269 \begin_layout Plain Layout
8276 This will default to the first defined style if not given, but you are
8277 encouraged to use this directive.
8280 \begin_layout Description
8281 \begin_inset Flex Code
8284 \begin_layout Plain Layout
8291 \begin_inset Flex Code
8294 \begin_layout Plain Layout
8300 ] This tag indicates that the module in question—which should be specified
8301 by filename without the
8302 \begin_inset Flex Code
8305 \begin_layout Plain Layout
8311 extension—cannot be used with this document class.
8312 This might be used in a journal-specific layout file to prevent, say, the
8314 \begin_inset Flex Code
8317 \begin_layout Plain Layout
8323 module that numbers theorems by section.
8328 be used in a module.
8329 Modules have their own way of excluding other modules (see
8330 \begin_inset CommandInset ref
8332 reference "sub:Layout-modules"
8339 \begin_layout Description
8340 \begin_inset Flex Code
8343 \begin_layout Plain Layout
8349 Defines a new float.
8351 \begin_inset space ~
8355 \begin_inset CommandInset ref
8357 reference "sub:Floats"
8363 \begin_inset Quotes eld
8367 \begin_inset Flex Code
8370 \begin_layout Plain Layout
8377 \begin_inset Quotes erd
8383 \begin_layout Description
8384 \begin_inset Flex Code
8387 \begin_layout Plain Layout
8393 Sets the information that will be output in the
8394 \begin_inset Flex Code
8397 \begin_layout Plain Layout
8403 block when this document class is output to XHTML.
8404 Note that this will completely override any prior
8405 \begin_inset Flex Code
8408 \begin_layout Plain Layout
8415 \begin_inset Flex Code
8418 \begin_layout Plain Layout
8426 \begin_inset Flex Code
8429 \begin_layout Plain Layout
8435 if you just want to add material to the preamble.) Must end with
8436 \begin_inset Quotes eld
8440 \begin_inset Flex Code
8443 \begin_layout Plain Layout
8450 \begin_inset Quotes erd
8456 \begin_layout Description
8457 \begin_inset Flex Code
8460 \begin_layout Plain Layout
8466 Sets CSS styling information.
8467 This will either be output in a
8468 \begin_inset Quotes eld
8472 \begin_inset Flex Code
8475 \begin_layout Plain Layout
8482 \begin_inset Quotes erd
8485 block or, if the user has so chosen, to a separate CSS file.
8486 Note that this will completely override any prior
8487 \begin_inset Flex Code
8490 \begin_layout Plain Layout
8497 \begin_inset Flex Code
8500 \begin_layout Plain Layout
8508 \begin_inset Flex Code
8511 \begin_layout Plain Layout
8517 if you just want to add material.) Must end with
8518 \begin_inset Quotes eld
8522 \begin_inset Flex Code
8525 \begin_layout Plain Layout
8532 \begin_inset Quotes erd
8538 \begin_layout Description
8539 \begin_inset Flex Code
8542 \begin_layout Plain Layout
8549 \begin_inset Flex Code
8552 \begin_layout Plain Layout
8558 ] The layout to use for the table of contents, bibliography, and so forth,
8559 when the document is output to HTML.
8560 For articles, this should normally be Section; for books, Chapter.
8561 If it is not given, then LyX will attempt to figure out which layout to
8565 \begin_layout Description
8566 \begin_inset Flex Code
8569 \begin_layout Plain Layout
8576 \begin_inset Flex Code
8579 \begin_layout Plain Layout
8585 ] Modifies the properties of the given counter.
8586 If the counter does not exist, the section is ignored.
8588 \begin_inset Quotes eld
8592 \begin_inset Flex Code
8595 \begin_layout Plain Layout
8602 \begin_inset Quotes erd
8606 \begin_inset Newline newline
8610 \begin_inset space ~
8614 \begin_inset CommandInset ref
8616 reference "sub:Counters"
8620 for details on counters.
8623 \begin_layout Description
8624 \begin_inset Flex Code
8627 \begin_layout Plain Layout
8634 \begin_inset Flex Code
8637 \begin_layout Plain Layout
8643 ] Modifies the properties of the given paragraph style.
8644 If the style does not exist, the section is ignored.
8646 \begin_inset Quotes eld
8650 \begin_inset Flex Code
8653 \begin_layout Plain Layout
8660 \begin_inset Quotes erd
8666 \begin_layout Description
8667 \begin_inset Flex Code
8670 \begin_layout Plain Layout
8676 As its name implies, this command allows you to include another layout
8677 definition file within yours to avoid duplicating commands.
8678 Common examples are the standard layout files, for example,
8679 \begin_inset Flex Code
8682 \begin_layout Plain Layout
8688 , which contains most of the basic layouts.
8691 \begin_layout Description
8692 \begin_inset Flex Code
8695 \begin_layout Plain Layout
8701 This section (re-)defines the layout of an inset.
8702 It can be applied to an existing inset or to a new, user-defined inset,
8703 e.g., a new character style.
8705 \begin_inset Quotes eld
8709 \begin_inset Flex Code
8712 \begin_layout Plain Layout
8719 \begin_inset Quotes erd
8723 \begin_inset Newline newline
8727 \begin_inset space ~
8731 \begin_inset CommandInset ref
8733 reference "sub:Flex-insets-and"
8737 for more information.
8741 \begin_layout Description
8742 \begin_inset Flex Code
8745 \begin_layout Plain Layout
8752 \begin_inset Flex Code
8755 \begin_layout Plain Layout
8761 ] A string that indicates the width of the left margin on the screen, for
8763 \begin_inset Quotes eld
8767 \begin_inset Quotes erd
8771 (Note that this is not a `length', like
8772 \begin_inset Quotes eld
8776 \begin_inset Quotes erd
8782 \begin_layout Description
8783 \begin_inset Flex Code
8786 \begin_layout Plain Layout
8793 \begin_inset Flex Code
8796 \begin_layout Plain Layout
8802 ] This command deletes an existing counter, usually one defined in an included
8806 \begin_layout Description
8807 \begin_inset Flex Code
8810 \begin_layout Plain Layout
8816 This command deletes an existing float.
8817 This is particularly useful when you want to suppress a float that has
8818 been defined in an input file.
8821 \begin_layout Description
8822 \begin_inset Flex Code
8825 \begin_layout Plain Layout
8831 This command deletes an existing style.
8832 This is particularly useful when you want to suppress a style that has
8833 be defined in an input file.
8836 \begin_layout Description
8837 \begin_inset Flex Code
8840 \begin_layout Plain Layout
8846 A string indicating the file format (as defined in the Preferences dialog)
8847 produced by this class.
8848 It is mainly useful when
8849 \begin_inset Flex Code
8852 \begin_layout Plain Layout
8858 is `literate' and one wants to define a new type of literate document.
8859 This string is reset to `docbook', `latex', or `literate' when the correspondin
8861 \begin_inset Flex Code
8864 \begin_layout Plain Layout
8870 parameter is encountered.
8873 \begin_layout Description
8874 \begin_inset Flex Code
8877 \begin_layout Plain Layout
8883 A string indicating what sort of output documents using this class will
8885 At present, the options are: `docbook', `latex', and `literate'.
8888 \begin_layout Description
8889 \begin_inset Flex Code
8892 \begin_layout Plain Layout
8899 \begin_inset Flex Code
8902 \begin_layout Plain Layout
8911 \begin_inset Flex Code
8914 \begin_layout Plain Layout
8921 \begin_inset Flex Code
8924 \begin_layout Plain Layout
8930 ] The default pagestyle.
8931 Can be changed in the
8932 \begin_inset Flex MenuItem
8935 \begin_layout Plain Layout
8936 Document\SpecialChar \menuseparator
8945 \begin_layout Description
8946 \begin_inset Flex Code
8949 \begin_layout Plain Layout
8955 Sets the preamble for the LaTeX document.
8956 Note that this will completely override any prior
8957 \begin_inset Flex Code
8960 \begin_layout Plain Layout
8967 \begin_inset Flex Code
8970 \begin_layout Plain Layout
8978 \begin_inset Flex Code
8981 \begin_layout Plain Layout
8987 if you just want to add material to the preamble.) Must end with
8988 \begin_inset Quotes eld
8992 \begin_inset Flex Code
8995 \begin_layout Plain Layout
9002 \begin_inset Quotes erd
9008 \begin_layout Description
9009 \begin_inset Flex Code
9012 \begin_layout Plain Layout
9019 \begin_inset Flex Code
9022 \begin_layout Plain Layout
9029 \begin_inset Flex Code
9032 \begin_layout Plain Layout
9041 \begin_inset Flex Code
9044 \begin_layout Plain Layout
9050 ] Whether the class already provides the feature
9051 \begin_inset Flex Code
9054 \begin_layout Plain Layout
9061 A feature is in general the name of a package (
9062 \begin_inset Flex Code
9065 \begin_layout Plain Layout
9072 \begin_inset Flex Code
9075 \begin_layout Plain Layout
9081 , \SpecialChar \ldots{}
9083 \begin_inset Flex Code
9086 \begin_layout Plain Layout
9093 \begin_inset Flex Code
9096 \begin_layout Plain Layout
9102 ,\SpecialChar \ldots{}
9103 ); the complete list of supported features is unfortunately not documented
9104 outside the LyX source code—but see
9105 \begin_inset Flex Code
9108 \begin_layout Plain Layout
9114 if you're interested.
9116 \begin_inset Flex MenuItem
9119 \begin_layout Plain Layout
9120 Help\SpecialChar \menuseparator
9126 also gives an overview of the supported packages.
9129 \begin_layout Description
9130 \begin_inset Flex Code
9133 \begin_layout Plain Layout
9140 \begin_inset Flex Code
9143 \begin_layout Plain Layout
9149 ] Indicates that this layout provides the functionality of the module mentioned,
9150 which should be specified by the filename without the
9151 \begin_inset Flex Code
9154 \begin_layout Plain Layout
9161 This will typically be used if the layout includes the module directly,
9162 rather than using the
9163 \begin_inset Flex Code
9166 \begin_layout Plain Layout
9172 tag to indicate that it ought to be used.
9173 It could also be used in a module that provided an alternate implementation
9174 of the same functionality.
9177 \begin_layout Description
9178 \begin_inset Flex Code
9181 \begin_layout Plain Layout
9188 \begin_inset Flex Code
9191 \begin_layout Plain Layout
9197 ] Whether the class requires the feature
9198 \begin_inset Flex Code
9201 \begin_layout Plain Layout
9208 Multiple features must be separated by commas.
9209 Note that you can only request supported features.
9211 \begin_inset Flex Code
9214 \begin_layout Plain Layout
9220 for a list of these.)
9223 \begin_layout Description
9224 \begin_inset Flex Code
9227 \begin_layout Plain Layout
9233 A string that indicates the width of the right margin on the screen, for
9235 \begin_inset Quotes eld
9239 \begin_inset Quotes erd
9245 \begin_layout Description
9246 \begin_inset Flex Code
9249 \begin_layout Plain Layout
9255 Sets which divisions get numbered.
9257 \begin_inset Flex Code
9260 \begin_layout Plain Layout
9269 \begin_layout Description
9270 \begin_inset Flex Code
9273 \begin_layout Plain Layout
9280 \begin_inset Flex Code
9283 \begin_layout Plain Layout
9292 \begin_inset Flex Code
9295 \begin_layout Plain Layout
9301 ] Whether the class-default should be printing on one or both sides of the
9303 Can be changed in the
9304 \begin_inset Flex MenuItem
9307 \begin_layout Plain Layout
9308 Document\SpecialChar \menuseparator
9317 \begin_layout Description
9318 \begin_inset Flex Code
9321 \begin_layout Plain Layout
9327 This sequence defines a paragraph style.
9328 If the style does not yet exist, it is created; if it does exist, its parameter
9331 \begin_inset Quotes eld
9335 \begin_inset Flex Code
9338 \begin_layout Plain Layout
9345 \begin_inset Quotes erd
9349 \begin_inset Newline newline
9353 \begin_inset space ~
9357 \begin_inset CommandInset ref
9359 reference "sub:Paragraph-Styles"
9363 for details on paragraph styles.
9366 \begin_layout Description
9367 \begin_inset Flex Code
9370 \begin_layout Plain Layout
9377 \begin_inset Flex Code
9380 \begin_layout Plain Layout
9386 ] The name of the command or environment to be used with
9387 \begin_inset Flex Code
9390 \begin_layout Plain Layout
9399 \begin_layout Description
9400 \begin_inset Flex Code
9403 \begin_layout Plain Layout
9410 \begin_inset Flex Code
9413 \begin_layout Plain Layout
9422 \begin_inset Flex Code
9425 \begin_layout Plain Layout
9431 ] Indicates what kind of markup is used to define the title of a document.
9433 \begin_inset Flex Code
9436 \begin_layout Plain Layout
9442 means that the macro with name
9443 \begin_inset Flex Code
9446 \begin_layout Plain Layout
9452 will be inserted after the last layout which has
9453 \begin_inset Quotes eld
9457 \begin_inset Flex Code
9460 \begin_layout Plain Layout
9467 \begin_inset Quotes erd
9472 \begin_inset Flex Code
9475 \begin_layout Plain Layout
9481 corresponds to the case where the block of paragraphs which have
9482 \begin_inset Quotes eld
9486 \begin_inset Flex Code
9489 \begin_layout Plain Layout
9496 \begin_inset Quotes erd
9499 should be enclosed into the
9500 \begin_inset Flex Code
9503 \begin_layout Plain Layout
9512 \begin_layout Description
9513 \begin_inset Flex Code
9516 \begin_layout Plain Layout
9522 Sets which divisions are included in the table of contents.
9524 \begin_inset Flex Code
9527 \begin_layout Plain Layout
9536 \begin_layout Subsection
9537 \begin_inset Flex Code
9540 \begin_layout Plain Layout
9547 \begin_inset CommandInset label
9549 name "sub:ClassOptions"
9556 \begin_layout Standard
9558 \begin_inset Flex Code
9561 \begin_layout Plain Layout
9567 section can contain the following entries:
9570 \begin_layout Description
9571 \begin_inset Flex Code
9574 \begin_layout Plain Layout
9581 \begin_inset Flex Code
9584 \begin_layout Plain Layout
9590 ] The list of available font sizes for the document's main font, separated
9592 \begin_inset Quotes eld
9596 \begin_inset Flex Code
9599 \begin_layout Plain Layout
9606 \begin_inset Quotes erd
9612 \begin_layout Description
9613 \begin_inset Flex Code
9616 \begin_layout Plain Layout
9622 Used to set the DTD line with XML-based output classes.
9624 \begin_inset space \thinspace{}
9628 \begin_inset Quotes eld
9631 -//OASIS//DTD DocBook V4.2//EN
9632 \begin_inset Quotes erd
9638 \begin_layout Description
9639 \begin_inset Flex Code
9642 \begin_layout Plain Layout
9649 \begin_inset Flex Code
9652 \begin_layout Plain Layout
9653 string="empty|plain|headings|fancy"
9658 ] The list of available page styles, separated by
9659 \begin_inset Quotes eld
9663 \begin_inset Flex Code
9666 \begin_layout Plain Layout
9673 \begin_inset Quotes erd
9679 \begin_layout Description
9680 \begin_inset Flex Code
9683 \begin_layout Plain Layout
9690 \begin_inset Flex Code
9693 \begin_layout Plain Layout
9699 ] Some document class options, separated by a comma, that will be added
9700 to the optional part of the
9701 \begin_inset Flex Code
9704 \begin_layout Plain Layout
9715 \begin_layout Standard
9717 \begin_inset Flex Code
9720 \begin_layout Plain Layout
9726 section must end with
9727 \begin_inset Quotes eld
9731 \begin_inset Flex Code
9734 \begin_layout Plain Layout
9741 \begin_inset Quotes erd
9747 \begin_layout Subsection
9749 \begin_inset CommandInset label
9751 name "sub:Paragraph-Styles"
9758 \begin_layout Standard
9759 A paragraph style description looks like this:
9763 \begin_layout Plain Layout
9764 Note that this will either define a new style or modify an existing one.
9772 \begin_layout LyX-Code
9779 \begin_layout LyX-Code
9783 \begin_layout LyX-Code
9787 \begin_layout Standard
9788 where the following commands are allowed:
9791 \begin_layout Description
9792 \begin_inset Flex Code
9795 \begin_layout Plain Layout
9802 \begin_inset Flex Code
9805 \begin_layout Plain Layout
9810 , left, right, center
9815 ] Paragraph alignment.
9818 \begin_layout Description
9819 \begin_inset Flex Code
9822 \begin_layout Plain Layout
9829 \begin_inset Flex Code
9832 \begin_layout Plain Layout
9837 , left, right, center
9842 ] A comma separated list of permitted alignments.
9843 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
9845 For example a right-aligned or centered enumeration isn't possible.)
9848 \begin_layout Description
9849 \begin_inset Flex Code
9852 \begin_layout Plain Layout
9858 Note that this will completely override any prior
9859 \begin_inset Flex Code
9862 \begin_layout Plain Layout
9868 declaration for this style.
9870 \begin_inset Quotes eld
9874 \begin_inset Flex Code
9877 \begin_layout Plain Layout
9884 \begin_inset Quotes erd
9889 \begin_inset CommandInset ref
9891 reference "sub:I18n"
9895 for details on its use.
9898 \begin_layout Description
9899 \begin_inset Flex Code
9902 \begin_layout Plain Layout
9909 \begin_inset Flex Code
9912 \begin_layout Plain Layout
9922 \begin_layout Plain Layout
9923 Note that a `float' here is a real number, such as: 1.5.
9928 The vertical space with which the last of a chain of paragraphs with this
9929 style is separated from the following paragraph.
9930 If the next paragraph has another style, the separations are not simply
9931 added, but the maximum is taken.
9934 \begin_layout Description
9935 \begin_inset Flex Code
9938 \begin_layout Plain Layout
9945 \begin_inset Flex Code
9948 \begin_layout Plain Layout
9954 The category for this style.
9955 This is used to group related styles in the style combobox on the toolbar.
9956 Any string can be used, but you may want to use existing categories with
9961 \begin_layout Description
9962 \begin_inset Flex Code
9965 \begin_layout Plain Layout
9971 Depth of XML command.
9972 Used only with XML-type formats.
9975 \begin_layout Description
9976 \begin_inset Flex Code
9979 \begin_layout Plain Layout
9986 \begin_inset Flex Code
9989 \begin_layout Plain Layout
9995 Copies all the features of an existing style into the current one.
9999 \begin_layout Description
10000 \begin_inset Flex Code
10003 \begin_layout Plain Layout
10009 The name of a style whose preamble should be output
10014 This allows to ensure some ordering of the preamble snippets when macros
10015 definitions depend on one another.
10019 \begin_layout Plain Layout
10020 Note that, besides that functionality, there is no way to ensure any ordering
10022 The ordering that you see in a given version of LyX may change without
10023 warning in later versions.
10031 \begin_layout Description
10032 \begin_inset Flex Code
10035 \begin_layout Plain Layout
10042 \begin_inset Flex Code
10045 \begin_layout Plain Layout
10050 , Box, Filled_Box, Static
10055 ] The type of label that stands at the end of the paragraph (or sequence
10057 \begin_inset Flex Code
10060 \begin_layout Plain Layout
10067 \begin_inset Flex Code
10070 \begin_layout Plain Layout
10077 \begin_inset Flex Code
10080 \begin_layout Plain Layout
10087 \begin_inset Flex Code
10090 \begin_layout Plain Layout
10098 \begin_inset Flex Code
10101 \begin_layout Plain Layout
10108 \begin_inset Quotes eld
10112 \begin_inset Quotes erd
10116 \begin_inset Flex Code
10119 \begin_layout Plain Layout
10126 \begin_inset Flex Code
10129 \begin_layout Plain Layout
10130 \begin_inset space ~
10138 ) is a white (resp.
10139 \begin_inset space ~
10142 black) square suitable for end of proof markers,
10143 \begin_inset Flex Code
10146 \begin_layout Plain Layout
10152 is an explicit text string.
10155 \begin_layout Description
10156 \begin_inset Flex Code
10159 \begin_layout Plain Layout
10166 \begin_inset Flex Code
10169 \begin_layout Plain Layout
10175 ] The string used for a label with a
10176 \begin_inset Flex Code
10179 \begin_layout Plain Layout
10186 \begin_inset Flex Code
10189 \begin_layout Plain Layout
10199 \begin_layout Description
10200 \begin_inset Flex Code
10203 \begin_layout Plain Layout
10209 The font used for both the text body
10215 \begin_inset space ~
10219 \begin_inset CommandInset ref
10221 reference "sub:Font-description"
10226 Note that defining this font automatically defines the
10227 \begin_inset Flex Code
10230 \begin_layout Plain Layout
10237 So you should define this one first if you also want to define
10238 \begin_inset Flex Code
10241 \begin_layout Plain Layout
10250 \begin_layout Description
10251 \begin_inset Flex Code
10254 \begin_layout Plain Layout
10261 \begin_inset CommandInset label
10263 name "des:FreeSpacing"
10268 \begin_inset Flex Code
10271 \begin_layout Plain Layout
10280 \begin_inset Flex Code
10283 \begin_layout Plain Layout
10289 ] Usually LyX doesn't allow you to insert more than one space between words,
10290 since a space is considered as the separation between two words, not a
10291 character or symbol of its own.
10292 This is a very fine thing but sometimes annoying, for example, when typing
10293 program code or plain LaTeX code.
10295 \begin_inset Flex Code
10298 \begin_layout Plain Layout
10305 Note that LyX will create protected blanks for the additional blanks when
10306 in another mode than LaTeX-mode.
10309 \begin_layout Description
10310 \begin_inset Flex Code
10313 \begin_layout Plain Layout
10319 These tags are used with XHTML output.
10321 \begin_inset CommandInset ref
10323 reference "sub:Paragraph-Style-XHTML"
10330 \begin_layout Description
10331 \begin_inset Flex Code
10334 \begin_layout Plain Layout
10340 [[FIXME]] (Used only with XML-type formats.)
10343 \begin_layout Description
10344 \begin_inset Flex Code
10347 \begin_layout Plain Layout
10354 \begin_inset Flex Code
10357 \begin_layout Plain Layout
10363 If 1, marks the style as to be included in the document preamble rather
10364 than in the document body.
10365 This is useful for document classes that want such information as the title
10366 and author to appear in the preamble.
10367 Note that this works only for styles for which the
10368 \begin_inset Flex Code
10371 \begin_layout Plain Layout
10378 \begin_inset Flex Code
10381 \begin_layout Plain Layout
10388 \begin_inset Flex Code
10391 \begin_layout Plain Layout
10400 \begin_layout Description
10401 \begin_inset Flex Code
10404 \begin_layout Plain Layout
10411 \begin_inset Flex Code
10414 \begin_layout Plain Layout
10420 If 1, marks the style as being part of a title block (see also the
10421 \begin_inset Flex Code
10424 \begin_layout Plain Layout
10431 \begin_inset Flex Code
10434 \begin_layout Plain Layout
10443 \begin_layout Description
10444 \begin_inset Flex Code
10447 \begin_layout Plain Layout
10454 \begin_inset Flex Code
10457 \begin_layout Plain Layout
10463 ] This provides extra space between paragraphs that have the same style.
10464 If you put other styles into an environment, each is separated with the
10466 \begin_inset Flex Code
10469 \begin_layout Plain Layout
10476 But the whole items of the environment are additionally separated with
10478 \begin_inset Flex Code
10481 \begin_layout Plain Layout
10488 Note that this is a
10493 \begin_layout Description
10494 \begin_inset Flex Code
10497 \begin_layout Plain Layout
10503 [[FIXME]] (Used only with XML-type formats.)
10506 \begin_layout Description
10507 \begin_inset Flex Code
10510 \begin_layout Plain Layout
10517 \begin_inset Flex Code
10520 \begin_layout Plain Layout
10529 \begin_inset Flex Code
10532 \begin_layout Plain Layout
10538 ] Usually LyX does not allow you to leave a paragraph empty, since it would
10539 lead to empty LaTeX output.
10540 There are some cases where this could be desirable however: in a letter
10541 template, the required fields can be provided as empty fields, so that
10542 people do not forget them; in some special classes, a style can be used
10543 as some kind of break, which does not contain actual text.
10546 \begin_layout Description
10547 \begin_inset Flex Code
10550 \begin_layout Plain Layout
10556 [float=0] The vertical space between the label and the text body.
10557 Only used for labels that are above the text body (
10558 \begin_inset Flex Code
10561 \begin_layout Plain Layout
10568 \begin_inset Flex Code
10571 \begin_layout Plain Layout
10572 Centered_Top_Environment
10580 \begin_layout Description
10581 \begin_inset Flex Code
10584 \begin_layout Plain Layout
10591 \begin_inset Flex Code
10594 \begin_layout Plain Layout
10601 \begin_inset Newline newline
10604 The name of the counter for automatic numbering.
10606 \begin_inset Newline newline
10614 \begin_inset Flex Code
10617 \begin_layout Plain Layout
10624 \begin_inset Flex Code
10627 \begin_layout Plain Layout
10634 In that case, the counter will be stepped each time the style appears.
10636 \begin_inset Newline newline
10644 \begin_inset Flex Code
10647 \begin_layout Plain Layout
10654 \begin_inset Flex Code
10657 \begin_layout Plain Layout
10663 , though this case is a bit complicated.
10664 Suppose you declare
10665 \begin_inset Quotes eld
10669 \begin_inset Flex Code
10672 \begin_layout Plain Layout
10673 LabelCounter myenum
10679 \begin_inset Quotes erd
10683 Then the actual counters used are
10684 \begin_inset Flex Code
10687 \begin_layout Plain Layout
10694 \begin_inset Flex Code
10697 \begin_layout Plain Layout
10704 \begin_inset Flex Code
10707 \begin_layout Plain Layout
10714 \begin_inset Flex Code
10717 \begin_layout Plain Layout
10723 , much as in LaTeX.
10724 These counters must all be declared separately.
10725 \begin_inset Newline newline
10729 \begin_inset CommandInset ref
10731 reference "sub:Counters"
10735 for details on counters.
10738 \begin_layout Description
10739 \begin_inset Flex Code
10742 \begin_layout Plain Layout
10748 The font used for the label.
10750 \begin_inset space ~
10754 \begin_inset CommandInset ref
10756 reference "sub:Font-description"
10763 \begin_layout Description
10764 \begin_inset Flex Code
10767 \begin_layout Plain Layout
10773 Text that indicates how far a label should be indented.
10776 \begin_layout Description
10777 \begin_inset Flex Code
10780 \begin_layout Plain Layout
10787 \begin_inset Flex Code
10790 \begin_layout Plain Layout
10796 ] The horizontal space between the label and the text body.
10797 Only used for labels that are not above the text body.
10800 \begin_layout Description
10801 \begin_inset Flex Code
10804 \begin_layout Plain Layout
10811 \begin_inset Flex Code
10814 \begin_layout Plain Layout
10820 ] The string used for a label with a
10821 \begin_inset Flex Code
10824 \begin_layout Plain Layout
10832 \begin_inset Flex Code
10835 \begin_layout Plain Layout
10841 is set, this string can be contain the special formatting commands described
10843 \begin_inset CommandInset ref
10845 reference "sub:Counters"
10853 \begin_layout Plain Layout
10854 For the sake of backwards compatibility, the string
10855 \begin_inset Flex Code
10858 \begin_layout Plain Layout
10868 will be replaced by the expanded
10869 \begin_inset Flex Code
10872 \begin_layout Plain Layout
10879 \begin_inset Flex Code
10882 \begin_layout Plain Layout
10891 This feature is now obsolete and should be replaced by the mechanisms of
10893 \begin_inset CommandInset ref
10895 reference "sub:Counters"
10907 \begin_layout Description
10908 \begin_inset Flex Code
10911 \begin_layout Plain Layout
10912 LabelStringAppendix
10918 \begin_inset Flex Code
10921 \begin_layout Plain Layout
10927 ] This is used inside the appendix instead of
10928 \begin_inset Flex Code
10931 \begin_layout Plain Layout
10939 \begin_inset Flex Code
10942 \begin_layout Plain Layout
10949 \begin_inset Flex Code
10952 \begin_layout Plain Layout
10953 LabelStringAppendix
10961 \begin_layout Description
10962 \begin_inset Flex Code
10965 \begin_layout Plain Layout
10971 [FIXME] (Used only with XML-type formats.)
10974 \begin_layout Description
10975 \begin_inset Flex Code
10978 \begin_layout Plain Layout
10985 \begin_inset Flex Code
10988 \begin_layout Plain Layout
10993 , Manual, Static, Top_Environment, Centered_Top_Environment, Counter, Sensitive,
10994 Enumerate, Itemize, Bibliography
11003 \begin_layout Itemize
11004 \begin_inset Flex Code
11007 \begin_layout Plain Layout
11013 means the label is the very first word (up to the first real blank).
11014 Use protected spaces (like
11015 \begin_inset space ~
11018 that one) if you want more than one word as the label.
11022 \begin_layout Itemize
11023 \begin_inset Flex Code
11026 \begin_layout Plain Layout
11032 means the label is simply whatever
11033 \begin_inset Flex Code
11036 \begin_layout Plain Layout
11043 Note that this really is `static'.
11046 \begin_layout Itemize
11047 \begin_inset Flex Code
11050 \begin_layout Plain Layout
11057 \begin_inset Flex Code
11060 \begin_layout Plain Layout
11061 Centered_Top_Environment
11066 are special cases of
11067 \begin_inset Flex Code
11070 \begin_layout Plain Layout
11077 The label will be printed above the paragraph, but only at the top of an
11078 environment or the top of a chain of paragraphs with this style.
11079 This might be used with the
11080 \begin_inset Flex MenuItem
11083 \begin_layout Plain Layout
11089 style, for example.
11092 \begin_layout Itemize
11093 \begin_inset Flex Code
11096 \begin_layout Plain Layout
11102 is a special case for the caption-labels
11103 \begin_inset Quotes eld
11107 \begin_inset Quotes erd
11111 \begin_inset Quotes eld
11115 \begin_inset Quotes erd
11120 \begin_inset Flex Code
11123 \begin_layout Plain Layout
11129 means the (hardcoded) label string depends on the kind of float: It is
11130 hardcoded to be `FloatType N', where N is the value of the counter associated
11134 \begin_layout Itemize
11136 \begin_inset Flex Code
11139 \begin_layout Plain Layout
11145 label type defines automatically numbered labels.
11147 \begin_inset Flex Code
11150 \begin_layout Plain Layout
11156 will be expanded to resolve any counter references it contains: For example,
11158 \begin_inset Quotes eld
11162 \begin_inset Flex Code
11165 \begin_layout Plain Layout
11176 \begin_inset Quotes erd
11181 \begin_inset CommandInset ref
11183 reference "sub:Counters"
11187 for more information on counters.
11190 \begin_layout Itemize
11191 \begin_inset Flex Code
11194 \begin_layout Plain Layout
11200 produces the usual sort of enumeration labels.
11201 At present, it is hardcoded to use Arabic numerals, lowercase letters,
11202 small Roman numerals, and uppercase letters for the four possible depths.
11205 \begin_layout Itemize
11206 \begin_inset Flex Code
11209 \begin_layout Plain Layout
11215 produces various bullets at the different levels.
11216 It is also hardcoded.
11219 \begin_layout Itemize
11220 \begin_inset Flex Code
11223 \begin_layout Plain Layout
11229 is used internally by LyX and should be used only with
11230 \begin_inset Flex Code
11233 \begin_layout Plain Layout
11234 LatexType BibEnvironment
11243 \begin_layout Description
11244 \begin_inset Flex Code
11247 \begin_layout Plain Layout
11253 Note that this will completely override any prior
11254 \begin_inset Flex Code
11257 \begin_layout Plain Layout
11263 declaration for this style.
11265 \begin_inset Quotes eld
11269 \begin_inset Flex Code
11272 \begin_layout Plain Layout
11279 \begin_inset Quotes erd
11284 \begin_inset CommandInset ref
11286 reference "sub:I18n"
11290 for details on its use.
11293 \begin_layout Description
11294 \begin_inset Flex Code
11297 \begin_layout Plain Layout
11303 The name of the corresponding LaTeX stuff.
11304 Either the environment or command name.
11307 \begin_layout Description
11308 \begin_inset Flex Code
11311 \begin_layout Plain Layout
11317 An optional parameter for the corresponding
11318 \begin_inset Flex Code
11321 \begin_layout Plain Layout
11328 This parameter cannot be changed from within LyX.
11331 \begin_layout Description
11332 \begin_inset Flex Code
11335 \begin_layout Plain Layout
11342 \begin_inset Flex Code
11345 \begin_layout Plain Layout
11350 , Command, Environment, Item_Environment,
11356 \begin_inset Flex Code
11359 \begin_layout Plain Layout
11360 List_Environment, Bib_Environment
11365 ] How the style should be translated into LaTeX.
11369 \begin_layout Plain Layout
11370 \begin_inset Flex Code
11373 \begin_layout Plain Layout
11379 is perhaps a bit misleading, since these rules apply to SGML classes, too.
11380 Visit the SGML class files for specific examples.
11389 \begin_layout Itemize
11390 \begin_inset Flex Code
11393 \begin_layout Plain Layout
11399 means nothing special.
11403 \begin_layout Itemize
11404 \begin_inset Flex Code
11407 \begin_layout Plain Layout
11414 \begin_inset Flex Code
11417 \begin_layout Plain Layout
11424 {\SpecialChar \ldots{}
11433 \begin_layout Itemize
11434 \begin_inset Flex Code
11437 \begin_layout Plain Layout
11444 \begin_inset Flex Code
11447 \begin_layout Plain Layout
11454 }\SpecialChar \ldots{}
11470 \begin_layout Itemize
11471 \begin_inset Flex Code
11474 \begin_layout Plain Layout
11481 \begin_inset Flex Code
11484 \begin_layout Plain Layout
11491 \begin_inset Flex Code
11494 \begin_layout Plain Layout
11502 is generated for each paragraph of this environment.
11506 \begin_layout Itemize
11507 \begin_inset Flex Code
11510 \begin_layout Plain Layout
11517 \begin_inset Flex Code
11520 \begin_layout Plain Layout
11527 \begin_inset Flex Code
11530 \begin_layout Plain Layout
11536 is passed as an argument to the environment.
11538 \begin_inset Flex Code
11541 \begin_layout Plain Layout
11547 can be defined in the
11548 \begin_inset Flex MenuItem
11551 \begin_layout Plain Layout
11552 Edit\SpecialChar \menuseparator
11554 \begin_inset space ~
11566 \begin_layout Standard
11567 Putting the last few things together, the LaTeX output will be either:
11570 \begin_layout LyX-Code
11573 latexname[latexparam]{\SpecialChar \ldots{}
11577 \begin_layout Standard
11581 \begin_layout LyX-Code
11584 begin{latexname}[latexparam] \SpecialChar \ldots{}
11590 \begin_layout Standard
11591 depending upon the LaTeX type.
11595 \begin_layout Description
11596 \begin_inset Flex Code
11599 \begin_layout Plain Layout
11606 \begin_inset Flex Code
11609 \begin_layout Plain Layout
11615 ] If you put styles into environments, the leftmargins are not simply added,
11616 but added with a factor
11617 \begin_inset Formula $\frac{4}{depth+4}$
11621 Note that this parameter is also used when the margin is defined as
11622 \begin_inset Flex Code
11625 \begin_layout Plain Layout
11632 \begin_inset Flex Code
11635 \begin_layout Plain Layout
11642 Then it is added to the manual or dynamic margin.
11644 \begin_inset Newline newline
11647 The argument is passed as a string.
11649 \begin_inset Quotes eld
11653 \begin_inset Flex Code
11656 \begin_layout Plain Layout
11663 \begin_inset Quotes erd
11666 means that the paragraph is indented with the width of
11667 \begin_inset Quotes eld
11671 \begin_inset Flex Code
11674 \begin_layout Plain Layout
11681 \begin_inset Quotes erd
11684 in the normal font.
11685 You can get a negative width by prefixing the string with
11686 \begin_inset Quotes eld
11690 \begin_inset Flex Code
11693 \begin_layout Plain Layout
11700 \begin_inset Quotes erd
11704 This way was chosen so that the look is the same with each used screen
11709 \begin_layout Description
11710 \begin_inset Flex Code
11713 \begin_layout Plain Layout
11720 \begin_inset Flex Code
11723 \begin_layout Plain Layout
11728 , Manual, Dynamic, First_Dynamic, Right_Address_Box
11734 \begin_inset Newline newline
11737 The kind of margin that the style has on the left side.
11739 \begin_inset Flex Code
11742 \begin_layout Plain Layout
11748 just means a fixed margin.
11750 \begin_inset Flex Code
11753 \begin_layout Plain Layout
11759 means that the left margin depends on the string entered in the
11760 \begin_inset Flex MenuItem
11763 \begin_layout Plain Layout
11764 Edit\SpecialChar \menuseparator
11766 \begin_inset space ~
11775 This is used to typeset nice lists without tabulators.
11777 \begin_inset Flex Code
11780 \begin_layout Plain Layout
11786 means that the margin depends on the size of the label.
11787 This is used for automatic enumerated headlines.
11788 It is obvious that the headline
11789 \begin_inset Quotes eld
11792 5.4.3.2.1 Very long headline
11793 \begin_inset Quotes erd
11796 must have a wider left margin (as wide as
11797 \begin_inset Quotes eld
11801 \begin_inset Quotes erd
11804 plus the space) than
11805 \begin_inset Quotes eld
11808 3.2 Very long headline
11809 \begin_inset Quotes erd
11813 \begin_inset Quotes eld
11817 \begin_inset Quotes erd
11820 are not able to do this.
11822 \begin_inset Flex Code
11825 \begin_layout Plain Layout
11831 is similar, but only the very first row of the paragraph is dynamic, while
11832 the others are static; this is used, for example, for descriptions.
11834 \begin_inset Flex Code
11837 \begin_layout Plain Layout
11843 means the margin is chosen in a way that the longest row of this paragraph
11844 fits to the right margin.
11845 This is used to typeset an address on the right edge of the page.
11848 \begin_layout Description
11849 \begin_inset Flex Code
11852 \begin_layout Plain Layout
11859 \begin_inset Flex Code
11862 \begin_layout Plain Layout
11871 \begin_inset Flex Code
11874 \begin_layout Plain Layout
11880 ] Whether fragile commands in this style should be
11881 \begin_inset Flex Code
11884 \begin_layout Plain Layout
11897 whether this command should itself be protected.)
11900 \begin_layout Description
11901 \begin_inset Flex Code
11904 \begin_layout Plain Layout
11911 \begin_inset Flex Code
11914 \begin_layout Plain Layout
11921 \begin_inset Flex Code
11924 \begin_layout Plain Layout
11932 ] Whether newlines are translated into LaTeX newlines (
11933 \begin_inset Flex Code
11936 \begin_layout Plain Layout
11947 The translation can be switched off to allow more comfortable LaTeX editing
11951 \begin_layout Description
11952 \begin_inset Flex Code
11955 \begin_layout Plain Layout
11962 \begin_inset Flex Code
11965 \begin_layout Plain Layout
11972 \begin_inset Flex Code
11975 \begin_layout Plain Layout
11983 ] If set to true, and if
11984 \begin_inset Flex Code
11987 \begin_layout Plain Layout
11994 \begin_inset Flex Code
11997 \begin_layout Plain Layout
12003 ) paragraphs are being indented, then the indentation of such a paragraph
12004 following one of this type will be suppressed.
12005 (So this will not affect the display of non-default paragraphs.)
12008 \begin_layout Description
12009 \begin_inset Flex Code
12012 \begin_layout Plain Layout
12018 Name of a style that has replaced this style.
12019 This is used to rename a style, while keeping backward compatibility.
12022 \begin_layout Description
12023 \begin_inset Flex Code
12026 \begin_layout Plain Layout
12033 \begin_inset Flex Code
12036 \begin_layout Plain Layout
12042 ] The number of optional arguments that can be used with this style.
12043 This is useful for things like section headings, and only makes sense with
12045 Note that, on output, the optional arguments will all precede any required
12046 arguments (see below).
12047 So one can have constructs like:
12051 \begin_layout LyX-Code
12054 mycmd[opt1]{req1}{contents of paragraph}
12057 \begin_layout Standard
12058 but one cannot have things like:
12061 \begin_layout LyX-Code
12064 mycmd[opt1]{req1}[opt2]{contents of paragraph}
12067 \begin_layout Standard
12068 at least, not without ERT (with which you can have anything).
12073 \begin_layout Description
12074 \begin_inset Flex Code
12077 \begin_layout Plain Layout
12084 \begin_inset Flex Code
12087 \begin_layout Plain Layout
12096 \begin_inset Flex Code
12099 \begin_layout Plain Layout
12105 ] Indicates that paragraphs will not be separated by an empty line in LaTeX
12106 output, but only by a line break; together with
12107 \begin_inset Flex Code
12110 \begin_layout Plain Layout
12116 , this allows to emulate a plain text editor (like the ERT inset).
12119 \begin_layout Description
12120 \begin_inset Flex Code
12123 \begin_layout Plain Layout
12130 \begin_inset Flex Code
12133 \begin_layout Plain Layout
12139 ] The indent of the very first line of a paragraph.
12141 \begin_inset Flex Code
12144 \begin_layout Plain Layout
12150 will be fixed for a certain style.
12151 The exception is the default style, since the indentation for these paragraphs
12152 can be prohibited with
12153 \begin_inset Flex Code
12156 \begin_layout Plain Layout
12164 \begin_inset Flex Code
12167 \begin_layout Plain Layout
12173 style paragraphs inside environments use the
12174 \begin_inset Flex Code
12177 \begin_layout Plain Layout
12183 of the environment, not their native one.
12185 \begin_inset Flex Code
12188 \begin_layout Plain Layout
12194 paragraphs inside an enumeration are not indented.
12197 \begin_layout Description
12198 \begin_inset Flex Code
12201 \begin_layout Plain Layout
12208 \begin_inset Flex Code
12211 \begin_layout Plain Layout
12217 ] The vertical space between two paragraphs of this style.
12220 \begin_layout Description
12221 \begin_inset Flex Code
12224 \begin_layout Plain Layout
12231 \begin_inset Flex Code
12234 \begin_layout Plain Layout
12240 ] LyX allows the user to choose either
12241 \begin_inset Quotes eld
12245 \begin_inset Quotes erd
12249 \begin_inset Quotes eld
12253 \begin_inset Quotes erd
12256 to typeset a document.
12258 \begin_inset Quotes eld
12262 \begin_inset Quotes erd
12265 is chosen, this value is completely ignored.
12267 \begin_inset Quotes eld
12271 \begin_inset Quotes erd
12274 is chosen, the parindent of a LaTeXtype
12275 \begin_inset Quotes eld
12279 \begin_inset Quotes erd
12282 style is ignored and all paragraphs are separated by this parskip argument.
12283 The vertical space is calculated with
12284 \begin_inset Flex Code
12287 \begin_layout Plain Layout
12289 \begin_inset space ~
12298 \begin_inset Flex Code
12301 \begin_layout Plain Layout
12307 is the height of a row with the normal font.
12308 This way, the look stays the same with different screen fonts.
12311 \begin_layout Description
12312 \begin_inset Flex Code
12315 \begin_layout Plain Layout
12322 \begin_inset Flex Code
12325 \begin_layout Plain Layout
12334 \begin_inset Flex Code
12337 \begin_layout Plain Layout
12343 ] Whether the contents of this paragraph should be output in raw form, meaning
12344 without special translations that LaTeX would require.
12347 \begin_layout Description
12348 \begin_inset Flex Code
12351 \begin_layout Plain Layout
12357 Information to be included in the LaTeX preamble when this style is used.
12358 Used to define macros, load packages, etc., required by this particular
12361 \begin_inset Quotes eld
12365 \begin_inset Flex Code
12368 \begin_layout Plain Layout
12375 \begin_inset Quotes erd
12381 \begin_layout Description
12382 \begin_inset Flex Code
12385 \begin_layout Plain Layout
12392 \begin_inset Flex Code
12395 \begin_layout Plain Layout
12401 ] The prefix to use when creating labels referring to paragraphs of this
12403 This allows the use of formatted references.
12406 \begin_layout Description
12407 \begin_inset Flex Code
12410 \begin_layout Plain Layout
12417 \begin_inset Flex Code
12420 \begin_layout Plain Layout
12426 ] The number of required arguments that the LaTeX command or environment
12427 corresponding to this style expects.
12428 In the case of a command, these are required arguments
12432 that associated with the content of the paragraph itself.
12433 These do not actually have to be provided: LyX will output empty arguments
12435 Note that optional arguments will be output before required arguments.
12436 See the discussion of the
12437 \begin_inset Flex Code
12440 \begin_layout Plain Layout
12446 tag above for more information.
12449 \begin_layout Description
12450 \begin_inset Flex Code
12453 \begin_layout Plain Layout
12460 \begin_inset Flex Code
12463 \begin_layout Plain Layout
12469 ] Whether the style requires the feature
12470 \begin_inset Flex Code
12473 \begin_layout Plain Layout
12480 See the description of
12481 \begin_inset Flex Code
12484 \begin_layout Plain Layout
12491 \begin_inset CommandInset ref
12492 LatexCommand pageref
12493 reference "des:FreeSpacing"
12497 ) for information on `features'.
12501 \begin_layout Description
12502 \begin_inset Flex Code
12505 \begin_layout Plain Layout
12512 \begin_inset Flex Code
12515 \begin_layout Plain Layout
12522 \begin_inset Flex Code
12525 \begin_layout Plain Layout
12534 \begin_layout Description
12535 \begin_inset Flex Code
12538 \begin_layout Plain Layout
12545 \begin_inset Flex Code
12548 \begin_layout Plain Layout
12553 , onehalf, double, other
12562 ] This defines what the default spacing should be in the style.
12564 \begin_inset Flex Code
12567 \begin_layout Plain Layout
12574 \begin_inset Flex Code
12577 \begin_layout Plain Layout
12584 \begin_inset Flex Code
12587 \begin_layout Plain Layout
12593 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
12594 If you specify the argument
12595 \begin_inset Flex Code
12598 \begin_layout Plain Layout
12604 , then you should also provide a numerical argument which will be the actual
12606 Note that, contrary to other parameters,
12607 \begin_inset Flex Code
12610 \begin_layout Plain Layout
12616 implies the generation of specific LaTeX code, using the package
12619 \begin_inset Flex Code
12622 \begin_layout Plain Layout
12631 \begin_layout Description
12632 \begin_inset Flex Code
12635 \begin_layout Plain Layout
12642 \begin_inset Flex Code
12645 \begin_layout Plain Layout
12652 \begin_inset Flex Code
12655 \begin_layout Plain Layout
12663 ] Spellcheck paragraphs of this style.
12667 \begin_layout Description
12668 \begin_inset Flex Code
12671 \begin_layout Plain Layout
12677 The font used for the text body .
12679 \begin_inset CommandInset ref
12681 reference "sub:Font-description"
12688 \begin_layout Description
12689 \begin_inset Flex Code
12692 \begin_layout Plain Layout
12701 \begin_inset Flex Code
12704 \begin_layout Plain Layout
12714 The level of the style in the table of contents.
12715 This is used for automatic numbering of section headings.
12718 \begin_layout Description
12719 \begin_inset Flex Code
12722 \begin_layout Plain Layout
12729 \begin_inset Flex Code
12732 \begin_layout Plain Layout
12738 ] The vertical space with which the very first of a chain of paragraphs
12739 with this style is separated from the previous paragraph.
12740 If the previous paragraph has another style, the separations are not simply
12741 added, but the maximum is taken.
12744 \begin_layout Subsection
12745 \begin_inset CommandInset label
12751 Internationalization of Paragraph Styles
12754 \begin_layout Standard
12755 LyX has long supported internationalization of layout information, but,
12756 until version 2.0, this applied only to the user interface and not to, say,
12758 Thus, French authors were forced to resort to ugly hacks if they wanted
12763 1' instead of `Theorem 1'.
12764 Thanks to Georg Baum, that is no longer the case.
12767 \begin_layout Standard
12769 \begin_inset Flex Code
12772 \begin_layout Plain Layout
12778 defines text that is to appear in the typeset document, it may use
12779 \begin_inset Flex Code
12782 \begin_layout Plain Layout
12789 \begin_inset Flex Code
12792 \begin_layout Plain Layout
12798 to support non-English and even multi-language documents correctly.
12799 The following excerpt (from the
12800 \begin_inset Flex Code
12803 \begin_layout Plain Layout
12809 file) shows how this works:
12812 \begin_layout LyX-Code
12817 \begin_layout LyX-Code
12820 theoremstyle{remark}
12823 \begin_layout LyX-Code
12826 newtheorem{claim}[thm]{
12833 \begin_layout LyX-Code
12837 \begin_layout LyX-Code
12841 \begin_layout LyX-Code
12846 claimname}{_(Claim)}
12849 \begin_layout LyX-Code
12853 \begin_layout LyX-Code
12857 \begin_layout LyX-Code
12866 claimname}{_(Claim)}}
12869 \begin_layout LyX-Code
12874 \begin_layout Standard
12875 In principle, any legal LaTeX may appear in the
12876 \begin_inset Flex Code
12879 \begin_layout Plain Layout
12886 \begin_inset Flex Code
12889 \begin_layout Plain Layout
12895 tags, but in practice they will typically look as they do here.
12896 The key to correct translation of the typeset text is the definition of
12898 \begin_inset Flex Code
12901 \begin_layout Plain Layout
12910 \begin_inset Flex Code
12913 \begin_layout Plain Layout
12925 \begin_layout Standard
12927 \begin_inset Flex Code
12930 \begin_layout Plain Layout
12936 tag provides for internationalization based upon the overall language of
12938 The contents of the tag will be included in the preamble, just as with
12940 \begin_inset Flex Code
12943 \begin_layout Plain Layout
12950 What makes it special is the use of the
12951 \begin_inset Quotes eld
12955 \begin_inset Quotes erd
12959 \begin_inset Flex Code
12962 \begin_layout Plain Layout
12968 , which will be replaced, when LyX produces LaTeX output, with the translation
12969 of its argument into the document language.
12972 \begin_layout Standard
12974 \begin_inset Flex Code
12977 \begin_layout Plain Layout
12983 tag is more complex, since it is meant to provide support for multi-language
12984 documents and so offers an interface to the
12985 \begin_inset Flex Code
12988 \begin_layout Plain Layout
12995 Its contents will be added to the preamble once for each language that
12996 appears in the document.
12997 In this case, the argument to
12998 \begin_inset Flex Code
13001 \begin_layout Plain Layout
13007 will be replaced with its translation into the language in question; the
13009 \begin_inset Flex Code
13012 \begin_layout Plain Layout
13018 is replaced by the language name (as used by the babel package).
13021 \begin_layout Standard
13022 A German document that also included a French section would thus have the
13023 following in the preamble:
13026 \begin_layout LyX-Code
13035 claimname}{Affirmation}}
13043 claimname}{Behauptung}}
13047 claimname}{Behauptung}
13050 \begin_layout Standard
13052 \begin_inset Flex Code
13055 \begin_layout Plain Layout
13061 will then conspire to produce the correct text in the output.
13064 \begin_layout Standard
13065 One important point to note here is that the translations are provided by
13066 LyX itself, through the
13067 \change_inserted -195340706 1334775793
13069 \begin_inset Flex Code
13072 \begin_layout Plain Layout
13074 \change_inserted -195340706 1334775793
13081 \change_deleted -195340706 1334775793
13082 same mechanism it uses for internationalization of the user interface
13085 This means, in effect, that
13086 \begin_inset Flex Code
13089 \begin_layout Plain Layout
13096 \begin_inset Flex Code
13099 \begin_layout Plain Layout
13105 are really only of use in layout files that are provided with LyX, since
13106 text entered in user-created layout files will not be seen by LyX's internation
13108 \change_inserted -195340706 1334775793
13110 \begin_inset Flex Code
13113 \begin_layout Plain Layout
13115 \change_inserted -195340706 1334775793
13121 file is modified accordingly
13124 That said, however, any layout created with the intention that it will
13125 be included with LyX should use these tags where appropriate.
13127 \change_inserted -195340706 1334775793
13128 Please note that the paragraph style translations provided by LyX will
13129 never change with a minor update (e.g.
13130 from version 2.1.x to 2.1.y).
13131 It is however quite likely that a major update (e.g.
13132 from 2.0.x to 2.1.y) will introduce new translations or corrections.
13137 \begin_layout Subsection
13139 \begin_inset CommandInset label
13148 \begin_layout Standard
13149 Since version 1.3.0 of LyX, it is has been both possible and necessary to
13150 define the floats (
13151 \begin_inset Flex MenuItem
13154 \begin_layout Plain Layout
13161 \begin_inset Flex MenuItem
13164 \begin_layout Plain Layout
13170 , \SpecialChar \ldots{}
13171 ) in the text class itself.
13172 Standard floats are included in the file
13173 \begin_inset Flex Code
13176 \begin_layout Plain Layout
13182 , so you may have to do no more than add
13185 \begin_layout LyX-Code
13186 Input stdfloats.inc
13189 \begin_layout Standard
13190 to your layout file.
13191 If you want to implement a text class that proposes some other float types
13192 (like the AGU class bundled with LyX), the information below will hopefully
13196 \begin_layout Description
13197 \begin_inset Flex Code
13200 \begin_layout Plain Layout
13207 \begin_inset Flex Code
13210 \begin_layout Plain Layout
13217 \begin_inset Quotes erd
13221 \begin_inset Quotes erd
13224 ] The file name extension of an auxiliary file for the list of figures (or
13226 LaTeX writes the captions to this file.
13229 \begin_layout Description
13230 \begin_inset Flex Code
13233 \begin_layout Plain Layout
13240 \begin_inset Flex Code
13243 \begin_layout Plain Layout
13250 \begin_inset Quotes erd
13254 \begin_inset Quotes erd
13257 ] The string that will be used in the menus and also for the caption.
13258 This is translated to the current language if babel is used.
13261 \begin_layout Description
13262 \begin_inset Flex Code
13265 \begin_layout Plain Layout
13271 These are used for XHTML output.
13273 \begin_inset CommandInset ref
13275 reference "sec:Tags-for-XHTML"
13282 \begin_layout Description
13283 \begin_inset Flex Code
13286 \begin_layout Plain Layout
13295 \begin_inset Flex Code
13298 \begin_layout Plain Layout
13307 \begin_inset Flex Code
13310 \begin_layout Plain Layout
13316 ] Indicates whether the float is already defined in the document class or
13317 if we instead need to load
13318 \begin_inset Flex Code
13321 \begin_layout Plain Layout
13327 and use what it provides to define it on-the-fly.
13329 \begin_inset Flex Code
13332 \begin_layout Plain Layout
13339 \begin_inset Flex Code
13342 \begin_layout Plain Layout
13349 It should be set to
13350 \begin_inset Flex Code
13353 \begin_layout Plain Layout
13359 if the float is already defined by the LaTeX document class.
13362 \begin_layout Description
13363 \begin_inset Flex Code
13366 \begin_layout Plain Layout
13373 \begin_inset Flex Code
13376 \begin_layout Plain Layout
13383 \begin_inset Quotes erd
13387 \begin_inset Quotes erd
13390 ] The command used to generate a list of floats of this type; the leading
13393 ' should be omitted.
13399 \begin_inset Flex Code
13402 \begin_layout Plain Layout
13408 is false, since there is no standard way to generate this command.
13410 \begin_inset Flex Code
13413 \begin_layout Plain Layout
13419 is true, since in that case there is a standard way to define the command.
13422 \begin_layout Description
13423 \begin_inset Flex Code
13426 \begin_layout Plain Layout
13433 \begin_inset Flex Code
13436 \begin_layout Plain Layout
13443 \begin_inset Quotes erd
13447 \begin_inset Quotes erd
13450 ] A title for a list of floats of this kind (list of figures, tables, or
13452 It is used for the screen label within LyX; it is passed to LaTeX for use
13453 as the title there; and it is used as the title in XHTML output.
13454 It will be translated to the document language.
13457 \begin_layout Description
13458 \begin_inset Flex Code
13461 \begin_layout Plain Layout
13468 \begin_inset Flex Code
13471 \begin_layout Plain Layout
13478 \begin_inset Quotes erd
13482 \begin_inset Quotes erd
13485 ] This (optional) argument determines whether floats of this class will
13486 be numbered within some sectional unit of the document.
13487 For example, if within is equal to
13488 \begin_inset Flex Code
13491 \begin_layout Plain Layout
13497 , the floats will be numbered within chapters.
13501 \begin_layout Description
13502 \begin_inset Flex Code
13505 \begin_layout Plain Layout
13512 \begin_inset Flex Code
13515 \begin_layout Plain Layout
13522 \begin_inset Quotes erd
13526 \begin_inset Quotes erd
13529 ] The default placement for the given class of floats.
13530 The string should be as in standard LaTeX:
13531 \begin_inset Flex Code
13534 \begin_layout Plain Layout
13541 \begin_inset Flex Code
13544 \begin_layout Plain Layout
13551 \begin_inset Flex Code
13554 \begin_layout Plain Layout
13561 \begin_inset Flex Code
13564 \begin_layout Plain Layout
13570 for top, bottom, page, and here, respectively.
13574 \begin_layout Plain Layout
13575 Note that the order of these letters in the string is irrelevant, like in
13581 On top of that there is a new type,
13582 \begin_inset Flex Code
13585 \begin_layout Plain Layout
13591 , which does not really correspond to a float, since it means: put it
13592 \begin_inset Quotes eld
13596 \begin_inset Quotes erd
13600 Note however that the
13601 \begin_inset Flex Code
13604 \begin_layout Plain Layout
13610 specifier is special and, because of implementation details, cannot be
13611 used in non-built in float types.
13612 If you do not understand what this means, just use
13613 \begin_inset Quotes eld
13617 \begin_inset Flex Code
13620 \begin_layout Plain Layout
13627 \begin_inset Quotes erd
13633 \begin_layout Description
13634 \begin_inset Flex Code
13637 \begin_layout Plain Layout
13644 \begin_inset Flex Code
13647 \begin_layout Plain Layout
13653 ] The prefix to use when creating labels referring to floats of this type.
13654 This allows the use of formatted references.
13655 Note that you can remove any
13656 \begin_inset Flex Code
13659 \begin_layout Plain Layout
13665 set by a copied style by using the special value
13666 \begin_inset Quotes eld
13670 \begin_inset Quotes erd
13673 , which must be all caps.
13676 \begin_layout Description
13677 \begin_inset Flex Code
13680 \begin_layout Plain Layout
13687 \begin_inset Flex Code
13690 \begin_layout Plain Layout
13697 \begin_inset Quotes erd
13701 \begin_inset Quotes erd
13704 ] The style used when defining the float using
13705 \begin_inset Flex Code
13708 \begin_layout Plain Layout
13719 \begin_layout Description
13720 \begin_inset Flex Code
13723 \begin_layout Plain Layout
13730 \begin_inset Flex Code
13733 \begin_layout Plain Layout
13740 \begin_inset Quotes erd
13744 \begin_inset Quotes erd
13748 \begin_inset Quotes eld
13752 \begin_inset Quotes erd
13755 of the new class of floats, like program or algorithm.
13756 After the appropriate
13757 \begin_inset Flex Code
13760 \begin_layout Plain Layout
13769 \begin_inset Flex Code
13772 \begin_layout Plain Layout
13781 \begin_inset Flex Code
13784 \begin_layout Plain Layout
13795 \begin_layout Description
13796 \begin_inset Flex Code
13799 \begin_layout Plain Layout
13806 \begin_inset Flex Code
13809 \begin_layout Plain Layout
13816 \begin_inset Flex Code
13819 \begin_layout Plain Layout
13827 ] Tells us whether this float is defined using the facilities provided by
13829 \begin_inset Flex Code
13832 \begin_layout Plain Layout
13838 , either by the class file or a package, or on-the-fly by LyX itself.
13841 \begin_layout Standard
13842 Note that defining a float with type
13843 \begin_inset Flex Code
13846 \begin_layout Plain Layout
13854 automatically defines the corresponding counter with name
13855 \begin_inset Flex Code
13858 \begin_layout Plain Layout
13869 \begin_layout Subsection
13870 Flex insets and InsetLayout
13871 \begin_inset CommandInset label
13873 name "sub:Flex-insets-and"
13880 \begin_layout Standard
13881 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
13882 these are called Flex insets.
13886 \begin_layout Standard
13887 Flex insets come in three different kinds:
13890 \begin_layout Itemize
13892 \begin_inset Flex Code
13895 \begin_layout Plain Layout
13901 ): These define semantic markup corresponding to such LaTeX commands as
13903 \begin_inset Flex Code
13906 \begin_layout Plain Layout
13915 \begin_inset Flex Code
13918 \begin_layout Plain Layout
13929 \begin_layout Itemize
13931 \begin_inset Flex Code
13934 \begin_layout Plain Layout
13940 ): These can be used to define custom collapsible insets, similar to TeX
13941 code, footnote, and the like.
13942 An obvious example is an endnote inset, which is defined in the
13943 \begin_inset Flex Code
13946 \begin_layout Plain Layout
13955 \begin_layout Itemize
13957 \begin_inset Flex Code
13960 \begin_layout Plain Layout
13966 ): For use with DocBook classes.
13969 \begin_layout Standard
13970 Flex insets are defined using the
13971 \begin_inset Flex Code
13974 \begin_layout Plain Layout
13980 tag, which shall be explained in a moment.
13983 \begin_layout Standard
13985 \begin_inset Flex Code
13988 \begin_layout Plain Layout
13994 tag also serves another function: It can be used to customize the general
13995 layout of many different types of insets.
13997 \begin_inset Flex Code
14000 \begin_layout Plain Layout
14006 can be used to customize the layout parameters for footnotes, marginal
14007 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
14008 boxes, tables, algorithms, URLs, and optional arguments, as well as to
14009 define Flex insets.
14012 \begin_layout Standard
14014 \begin_inset Flex Code
14017 \begin_layout Plain Layout
14023 definition must begin with a line of the form:
14026 \begin_layout LyX-Code
14030 \begin_layout Standard
14032 \begin_inset Flex Code
14035 \begin_layout Plain Layout
14041 indicates the inset whose layout is being defined, and here there are
14042 \change_inserted 5863208 1334489266
14044 \change_deleted 5863208 1334489267
14050 \begin_layout Enumerate
14051 The layout for a pre-existing inset is being modified.
14052 In this case, can be
14053 \begin_inset Flex Code
14056 \begin_layout Plain Layout
14062 any one of the following:
14063 \begin_inset Flex Code
14066 \begin_layout Plain Layout
14073 \begin_inset Flex Code
14076 \begin_layout Plain Layout
14083 \begin_inset Flex Code
14086 \begin_layout Plain Layout
14093 \begin_inset Flex Code
14096 \begin_layout Plain Layout
14103 \begin_inset Flex Code
14106 \begin_layout Plain Layout
14113 \begin_inset Flex Code
14116 \begin_layout Plain Layout
14123 \begin_inset Flex Code
14126 \begin_layout Plain Layout
14133 \begin_inset Flex Code
14136 \begin_layout Plain Layout
14143 \begin_inset Flex Code
14146 \begin_layout Plain Layout
14153 \begin_inset Flex Code
14156 \begin_layout Plain Layout
14163 \begin_inset Flex Code
14166 \begin_layout Plain Layout
14173 \begin_inset Flex Code
14176 \begin_layout Plain Layout
14183 \begin_inset Flex Code
14186 \begin_layout Plain Layout
14193 \begin_inset Flex Code
14196 \begin_layout Plain Layout
14203 \begin_inset Flex Code
14206 \begin_layout Plain Layout
14213 \begin_inset Flex Code
14216 \begin_layout Plain Layout
14223 \begin_inset Flex Code
14226 \begin_layout Plain Layout
14233 \begin_inset Flex Code
14236 \begin_layout Plain Layout
14243 \begin_inset Flex Code
14246 \begin_layout Plain Layout
14253 \begin_inset Flex Code
14256 \begin_layout Plain Layout
14265 \begin_layout Enumerate
14266 The layout for a Flex inset is being defined.
14268 \begin_inset Flex Code
14271 \begin_layout Plain Layout
14277 must be of the form
14278 \begin_inset Quotes eld
14282 \begin_inset Flex Code
14285 \begin_layout Plain Layout
14292 \begin_inset Quotes erd
14296 \begin_inset Flex Code
14299 \begin_layout Plain Layout
14305 may be be any valid identifier not used by a pre-existing Flex inset.
14306 The identifier may include spaces, but in that case the whole thing must
14307 be wrapped in quotes.
14308 Note that the definition of a flex inset
14313 \begin_inset Flex Code
14316 \begin_layout Plain Layout
14322 entry, declaring which type of inset it defines.
14323 \change_inserted 5863208 1334489312
14327 \begin_layout Enumerate
14329 \change_inserted 5863208 1334492248
14330 The layout for user specific branch is being defined.
14332 \begin_inset Flex Code
14335 \begin_layout Plain Layout
14337 \change_inserted 5863208 1334489384
14343 must be of the form
14344 \begin_inset Quotes eld
14348 \begin_inset Flex Code
14351 \begin_layout Plain Layout
14353 \change_inserted 5863208 1334489392
14360 \begin_inset Quotes erd
14364 \begin_inset Flex Code
14367 \begin_layout Plain Layout
14369 \change_inserted 5863208 1334489384
14375 may be be any valid identifier of branch defined in user's document.
14376 The identifier may include spaces, but in that case the whole thing must
14377 be wrapped in quotes.
14378 The main purpose of this feature is to allow LaTeX wrapping around specific
14379 branches as user needs.
14384 \begin_layout Standard
14386 \begin_inset Flex Code
14389 \begin_layout Plain Layout
14395 definition can contain the following entries:
14398 \begin_layout Description
14400 \change_inserted -195340706 1333913893
14401 \begin_inset Flex Code
14404 \begin_layout Plain Layout
14410 Preamble for changing languages.
14412 \begin_inset space ~
14416 \begin_inset CommandInset ref
14418 reference "sub:I18n"
14425 \begin_layout Description
14426 \begin_inset Flex Code
14429 \begin_layout Plain Layout
14435 The color for the inset's background.
14436 The valid colors are defined in
14437 \begin_inset Flex Code
14440 \begin_layout Plain Layout
14449 \begin_layout Description
14450 \begin_inset Flex Code
14453 \begin_layout Plain Layout
14460 \begin_inset Flex Code
14463 \begin_layout Plain Layout
14472 \begin_inset Flex Code
14475 \begin_layout Plain Layout
14481 ] Whether to use the content of the inset as the label, when the inset is
14486 \begin_layout Description
14487 \begin_inset Flex Code
14490 \begin_layout Plain Layout
14497 \begin_inset Flex Code
14500 \begin_layout Plain Layout
14506 Copies all the features of an existing style into the current one.
14510 \begin_layout Description
14511 \begin_inset Flex Code
14514 \begin_layout Plain Layout
14521 \begin_inset Flex Code
14524 \begin_layout Plain Layout
14533 \begin_inset Flex Code
14536 \begin_layout Plain Layout
14542 ] Indicates whether the user may employ the Paragraph Settings dialog to
14543 customize the paragraph.
14546 \begin_layout Description
14547 \begin_inset Flex Code
14550 \begin_layout Plain Layout
14557 \begin_inset Flex Code
14560 \begin_layout Plain Layout
14567 \begin_inset Flex Code
14570 \begin_layout Plain Layout
14577 \begin_inset Flex Code
14580 \begin_layout Plain Layout
14586 , describing the rendering style used for the inset's frame and buttons.
14587 Footnotes generally use
14588 \begin_inset Flex Code
14591 \begin_layout Plain Layout
14597 , ERT insets generally
14598 \begin_inset Flex Code
14601 \begin_layout Plain Layout
14607 , and character styles
14608 \begin_inset Flex Code
14611 \begin_layout Plain Layout
14620 \begin_layout Description
14621 \begin_inset Flex Code
14624 \begin_layout Plain Layout
14631 \begin_inset Flex Code
14634 \begin_layout Plain Layout
14641 \begin_inset Flex Code
14644 \begin_layout Plain Layout
14653 \begin_inset Flex Code
14656 \begin_layout Plain Layout
14663 \begin_inset Flex Code
14666 \begin_layout Plain Layout
14673 Indicates whether the environment will stand on its own in LaTeX output
14674 or will appear inline with the surrounding text.
14675 If set to false, it is supposed that the LaTeX environment ignores white
14676 space (including one newline character) after the
14677 \begin_inset Flex Code
14680 \begin_layout Plain Layout
14693 \begin_inset Flex Code
14696 \begin_layout Plain Layout
14712 \begin_layout Description
14713 \begin_inset Flex Code
14716 \begin_layout Plain Layout
14722 Required at the end of the InsetLayout declarations.
14725 \begin_layout Description
14726 \begin_inset Flex Code
14729 \begin_layout Plain Layout
14735 The font used for both the text body
14741 \begin_inset space ~
14745 \begin_inset CommandInset ref
14747 reference "sub:Font-description"
14752 Note that defining this font automatically defines the
14753 \begin_inset Flex Code
14756 \begin_layout Plain Layout
14762 to the same value, so define this first and define
14763 \begin_inset Flex Code
14766 \begin_layout Plain Layout
14772 later if you want them to be different.
14775 \begin_layout Description
14776 \begin_inset Flex Code
14779 \begin_layout Plain Layout
14786 \begin_inset Quotes eld
14790 \begin_inset Quotes erd
14793 language, leading to Left-to-Right (latin) output, e.
14794 \begin_inset space \thinspace{}
14798 \begin_inset space \space{}
14801 in TeX code or URL.
14805 \begin_layout Description
14806 \begin_inset Flex Code
14809 \begin_layout Plain Layout
14816 \begin_inset Flex Code
14819 \begin_layout Plain Layout
14828 \begin_inset Flex Code
14831 \begin_layout Plain Layout
14837 ] Indicates whether the
14838 \begin_inset Flex Code
14841 \begin_layout Plain Layout
14847 should be used or, instead, the user can change the paragraph style used
14852 \begin_layout Description
14853 \begin_inset Flex Code
14856 \begin_layout Plain Layout
14863 \begin_inset Flex Code
14866 \begin_layout Plain Layout
14875 \begin_inset Flex Code
14878 \begin_layout Plain Layout
14884 ] Usually LyX doesn't allow you to insert more than one space between words,
14885 since a space is considered as the separation between two words, not a
14886 character or symbol of its own.
14887 This is a very fine thing but sometimes annoying, for example, when typing
14888 program code or plain LaTeX code.
14890 \begin_inset Flex Code
14893 \begin_layout Plain Layout
14900 Note that LyX will create protected blanks for the additional blanks when
14901 in another mode than LaTeX-mode.
14905 \begin_layout Description
14906 \begin_inset Flex Code
14909 \begin_layout Plain Layout
14915 These tags control XHTML output.
14917 \begin_inset CommandInset ref
14919 reference "sec:Tags-for-XHTML"
14926 \begin_layout Description
14927 \begin_inset Flex Code
14930 \begin_layout Plain Layout
14937 \begin_inset Flex Code
14940 \begin_layout Plain Layout
14949 \begin_inset Flex Code
14952 \begin_layout Plain Layout
14958 ] Whether to include the contents of this inset in the strings generated
14959 for the `Outline' pane.
14960 One would not, for example, want the content of a footnote in a section
14961 header to be included in the TOC displayed in the outline, but one would
14962 normally want the content of a character style displayed.
14963 Default is false: not to include.
14966 \begin_layout Description
14967 \begin_inset Flex Code
14970 \begin_layout Plain Layout
14977 \begin_inset Flex Code
14980 \begin_layout Plain Layout
14989 \begin_inset Flex Code
14992 \begin_layout Plain Layout
14998 ] Usually LyX does not allow you to leave a paragraph empty, since it would
14999 lead to empty LaTeX output.
15000 There are some cases where this could be desirable however: in a letter
15001 template, the required fields can be provided as empty fields, so that
15002 people do not forget them; in some special classes, a style can be used
15003 as some kind of break, which does not contain actual text.
15007 \begin_layout Description
15008 \begin_inset Flex Code
15011 \begin_layout Plain Layout
15017 The font used for the label.
15019 \begin_inset space ~
15023 \begin_inset CommandInset ref
15025 reference "sub:Font-description"
15030 Note that this definition can never appear before
15031 \begin_inset Flex Code
15034 \begin_layout Plain Layout
15040 , lest it be ineffective.
15043 \begin_layout Description
15044 \begin_inset Flex Code
15047 \begin_layout Plain Layout
15053 What will be displayed on the button or elsewhere as the inset label.
15055 \begin_inset Flex Code
15058 \begin_layout Plain Layout
15065 \begin_inset Flex Code
15068 \begin_layout Plain Layout
15074 ) modify this label on the fly.
15077 \begin_layout Description
15079 \change_inserted -195340706 1333913893
15080 \begin_inset Flex Code
15083 \begin_layout Plain Layout
15089 Language dependent preamble.
15091 \begin_inset space ~
15095 \begin_inset CommandInset ref
15097 reference "sub:I18n"
15104 \begin_layout Description
15105 \begin_inset Flex Code
15108 \begin_layout Plain Layout
15114 The name of the corresponding LaTeX stuff.
15115 Either the environment or command name.
15118 \begin_layout Description
15119 \begin_inset Flex Code
15122 \begin_layout Plain Layout
15128 The optional parameter for the corresponding
15129 \begin_inset Flex Code
15132 \begin_layout Plain Layout
15138 stuff, including possible bracket pairs like
15139 \begin_inset Flex Code
15142 \begin_layout Plain Layout
15149 This parameter cannot be changed from within LyX.
15152 \begin_layout Description
15153 \begin_inset Flex Code
15156 \begin_layout Plain Layout
15163 \begin_inset Flex Code
15166 \begin_layout Plain Layout
15171 , Command, Environment, Item_Environment,
15177 \begin_inset Flex Code
15180 \begin_layout Plain Layout
15181 List_Environment, Bib_Environment
15186 ] How the style should be translated into LaTeX.
15190 \begin_layout Plain Layout
15191 \begin_inset Flex Code
15194 \begin_layout Plain Layout
15200 is perhaps a bit misleading, since these rules apply to SGML classes, too.
15201 Visit the SGML class files for specific examples.
15210 \begin_layout Itemize
15211 \begin_inset Flex Code
15214 \begin_layout Plain Layout
15220 means nothing special.
15224 \begin_layout Itemize
15225 \begin_inset Flex Code
15228 \begin_layout Plain Layout
15235 \begin_inset Flex Code
15238 \begin_layout Plain Layout
15245 {\SpecialChar \ldots{}
15254 \begin_layout Itemize
15255 \begin_inset Flex Code
15258 \begin_layout Plain Layout
15265 \begin_inset Flex Code
15268 \begin_layout Plain Layout
15275 }\SpecialChar \ldots{}
15291 \begin_layout Itemize
15292 \begin_inset Flex Code
15295 \begin_layout Plain Layout
15302 \begin_inset Flex Code
15305 \begin_layout Plain Layout
15312 \begin_inset Flex Code
15315 \begin_layout Plain Layout
15323 is generated for each paragraph of this environment.
15327 \begin_layout Itemize
15328 \begin_inset Flex Code
15331 \begin_layout Plain Layout
15338 \begin_inset Flex Code
15341 \begin_layout Plain Layout
15348 \begin_inset Flex Code
15351 \begin_layout Plain Layout
15357 is passed as an argument to the environment.
15359 \begin_inset Flex Code
15362 \begin_layout Plain Layout
15368 can be defined in the
15369 \begin_inset Flex MenuItem
15372 \begin_layout Plain Layout
15377 \SpecialChar \menuseparator
15383 \begin_inset space ~
15395 \begin_layout Standard
15396 Putting the last few things together, the LaTeX output will be either:
15399 \begin_layout LyX-Code
15402 latexname[latexparam]{\SpecialChar \ldots{}
15406 \begin_layout Standard
15410 \begin_layout LyX-Code
15413 begin{latexname}[latexparam] \SpecialChar \ldots{}
15419 \begin_layout Standard
15420 depending upon the LaTeX type.
15424 \begin_layout Description
15425 \begin_inset Flex Code
15428 \begin_layout Plain Layout
15435 \begin_inset Flex Code
15438 \begin_layout Plain Layout
15445 \begin_inset Flex Code
15448 \begin_layout Plain Layout
15455 \begin_inset Flex Code
15458 \begin_layout Plain Layout
15465 \begin_inset Flex Code
15468 \begin_layout Plain Layout
15474 (indicating a dummy definition ending definitions of charstyles, etc).
15475 This entry is required in and is only meaningful for Flex insets.
15476 Among other things, it determines on which menu this inset will appear.
15478 \begin_inset Flex Code
15481 \begin_layout Plain Layout
15488 \begin_inset Flex Code
15491 \begin_layout Plain Layout
15498 \begin_inset Flex Code
15501 \begin_layout Plain Layout
15509 \begin_inset Flex Code
15512 \begin_layout Plain Layout
15518 can be set to true for charstyle insets, if you wish, by setting it
15523 \begin_inset Flex Code
15526 \begin_layout Plain Layout
15535 \begin_layout Description
15536 \begin_inset Flex Code
15539 \begin_layout Plain Layout
15546 \begin_inset Flex Code
15549 \begin_layout Plain Layout
15558 \begin_inset Flex Code
15561 \begin_layout Plain Layout
15567 ] Whether multiple paragraphs are permitted in this inset.
15569 \begin_inset Flex Code
15572 \begin_layout Plain Layout
15578 to the same value and
15579 \begin_inset Flex Code
15582 \begin_layout Plain Layout
15588 to the opposite value.
15589 These can be reset to other values, if they are used
15594 \begin_inset Flex Code
15597 \begin_layout Plain Layout
15607 \begin_layout Description
15608 \begin_inset Flex Code
15611 \begin_layout Plain Layout
15618 \begin_inset Flex Code
15621 \begin_layout Plain Layout
15630 \begin_inset Flex Code
15633 \begin_layout Plain Layout
15639 ] Whether fragile commands in this inset should be
15640 \begin_inset Flex Code
15643 \begin_layout Plain Layout
15656 whether the command should itself be protected.) Default is false.
15659 \begin_layout Description
15660 \begin_inset Flex Code
15663 \begin_layout Plain Layout
15670 \begin_inset Flex Code
15673 \begin_layout Plain Layout
15682 \begin_inset Flex Code
15685 \begin_layout Plain Layout
15691 ] Indicates that paragraphs will not be separated by an empty line in LaTeX
15692 output, but only by a line break; together with
15693 \begin_inset Flex Code
15696 \begin_layout Plain Layout
15702 , this allows to emulate a plain text editor (like the ERT inset).
15706 \begin_layout Description
15707 \begin_inset Flex Code
15710 \begin_layout Plain Layout
15717 \begin_inset Flex Code
15720 \begin_layout Plain Layout
15729 \begin_inset Flex Code
15732 \begin_layout Plain Layout
15738 ] Whether the contents of this paragraph should be output in raw form, meaning
15739 without special translations that LaTeX would require.
15742 \begin_layout Description
15743 \begin_inset Flex Code
15746 \begin_layout Plain Layout
15752 Information to be included in the LaTeX preamble when this style is used.
15753 Used to define macros, load packages, etc., required by this particular
15756 \begin_inset Quotes eld
15760 \begin_inset Flex Code
15763 \begin_layout Plain Layout
15770 \begin_inset Quotes erd
15776 \begin_layout Description
15777 \begin_inset Flex Code
15780 \begin_layout Plain Layout
15787 \begin_inset Flex Code
15790 \begin_layout Plain Layout
15796 ] The prefix to use when creating labels referring to insets of this type.
15797 This allows the use of formatted references.
15800 \begin_layout Description
15801 \begin_inset Flex Code
15804 \begin_layout Plain Layout
15811 \begin_inset Flex Code
15814 \begin_layout Plain Layout
15820 ] Whether the style requires the feature
15821 \begin_inset Flex Code
15824 \begin_layout Plain Layout
15831 See the description of
15832 \begin_inset Flex Code
15835 \begin_layout Plain Layout
15842 \begin_inset CommandInset ref
15843 LatexCommand pageref
15844 reference "des:FreeSpacing"
15848 ) for information on `features'.
15852 \begin_layout Description
15853 \begin_inset Flex Code
15856 \begin_layout Plain Layout
15863 \begin_inset Flex Code
15866 \begin_layout Plain Layout
15873 \begin_inset Flex Code
15876 \begin_layout Plain Layout
15884 ] Whether this inset should use the font of its surrounding environment
15886 Default is true: uses its own.
15889 \begin_layout Description
15890 \begin_inset Flex Code
15893 \begin_layout Plain Layout
15900 \begin_inset Flex Code
15903 \begin_layout Plain Layout
15910 \begin_inset Flex Code
15913 \begin_layout Plain Layout
15921 ] Spellcheck the contents of this inset.
15925 \begin_layout Subsection
15927 \begin_inset CommandInset label
15929 name "sub:Counters"
15936 \begin_layout Standard
15937 Since version 1.3.0 of LyX, it is both possible and necessary to define the
15939 \begin_inset Flex MenuItem
15942 \begin_layout Plain Layout
15949 \begin_inset Flex MenuItem
15952 \begin_layout Plain Layout
15958 , \SpecialChar \ldots{}
15959 ) in the text class itself.
15960 The standard counters are defined in the file
15961 \begin_inset Flex Code
15964 \begin_layout Plain Layout
15970 , so you may have to do no more than add
15973 \begin_layout LyX-Code
15974 Input stdcounters.inc
15977 \begin_layout Standard
15978 to your layout file to get them to work.
15979 But if you want to define custom counters, then you can do so.
15980 The counter declaration must begin with:
15983 \begin_layout LyX-Code
15984 Counter CounterName
15987 \begin_layout Standard
15989 \begin_inset Flex Code
15992 \begin_layout Plain Layout
15998 ' is replaced by the name of the counter.
15999 And it must end with
16000 \begin_inset Quotes eld
16004 \begin_inset Flex Code
16007 \begin_layout Plain Layout
16014 \begin_inset Quotes erd
16018 The following parameters can also be used:
16021 \begin_layout Description
16022 \begin_inset Flex Code
16025 \begin_layout Plain Layout
16032 \begin_inset Flex Code
16035 \begin_layout Plain Layout
16042 \begin_inset Quotes erd
16046 \begin_inset Quotes erd
16049 ] When defined, this string defines how the counter is displayed.
16050 Setting this value sets
16051 \begin_inset Flex Code
16054 \begin_layout Plain Layout
16055 LabelStringAppendix
16061 The following special constructs can be used in the string:
16065 \begin_layout Itemize
16066 \begin_inset Flex Code
16069 \begin_layout Plain Layout
16077 will be replaced by the expansion of the
16078 \begin_inset Flex Code
16081 \begin_layout Plain Layout
16088 \begin_inset Flex Code
16091 \begin_layout Plain Layout
16092 LabelStringAppendix
16098 \begin_inset Flex Code
16101 \begin_layout Plain Layout
16111 \begin_layout Itemize
16112 counter values can be expressed using LaTeX-like macros
16113 \begin_inset Flex Code
16116 \begin_layout Plain Layout
16133 \begin_inset Flex Code
16136 \begin_layout Plain Layout
16148 \begin_layout Plain Layout
16158 Actually, the situation is a bit more complicated: any
16177 other than those described below will produce arabic numerals.
16178 It would not be surprising to see this change in the future.
16184 \begin_inset Flex Code
16187 \begin_layout Plain Layout
16193 : 1, 2, 3,\SpecialChar \ldots{}
16195 \begin_inset Flex Code
16198 \begin_layout Plain Layout
16204 for lower-case letters: a, b, c, \SpecialChar \ldots{}
16206 \begin_inset Flex Code
16209 \begin_layout Plain Layout
16215 for upper-case letters: A, B, C, \SpecialChar \ldots{}
16217 \begin_inset Flex Code
16220 \begin_layout Plain Layout
16226 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
16228 \begin_inset Flex Code
16231 \begin_layout Plain Layout
16237 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
16239 \begin_inset Flex Code
16242 \begin_layout Plain Layout
16248 for hebrew numerals.
16252 \begin_layout Standard
16253 If LabelString is not defined, a default value is constructed as follows:
16254 if the counter has a master counter
16255 \begin_inset Flex Code
16258 \begin_layout Plain Layout
16265 \begin_inset Flex Code
16268 \begin_layout Plain Layout
16275 \begin_inset Flex Code
16278 \begin_layout Plain Layout
16288 is used; otherwise the string
16289 \begin_inset Flex Code
16292 \begin_layout Plain Layout
16303 \begin_layout Description
16304 \begin_inset Flex Code
16307 \begin_layout Plain Layout
16308 LabelStringAppendix
16314 \begin_inset Flex Code
16317 \begin_layout Plain Layout
16324 \begin_inset Quotes erd
16328 \begin_inset Quotes erd
16332 \begin_inset Flex Code
16335 \begin_layout Plain Layout
16341 , but for use in the Appendix.
16344 \begin_layout Description
16345 \begin_inset Flex Code
16348 \begin_layout Plain Layout
16355 \begin_inset Flex Code
16358 \begin_layout Plain Layout
16365 \begin_inset Quotes erd
16369 \begin_inset Quotes erd
16372 ] A format for use with formatted references to this counter.
16373 For example, one might want to have references to section numbers appear
16375 \begin_inset Quotes eld
16379 \begin_inset Quotes erd
16383 The string should contain
16384 \begin_inset Quotes eld
16388 \begin_inset Quotes erd
16392 This will be replaced by the counter number itself.
16393 So, for sections, it would be: Section ##.
16396 \begin_layout Description
16397 \begin_inset Flex Code
16400 \begin_layout Plain Layout
16407 \begin_inset Flex Code
16410 \begin_layout Plain Layout
16417 \begin_inset Quotes erd
16421 \begin_inset Quotes erd
16424 ] If this is set to the name of another counter, the present counter will
16425 be reset every time the other one is increased.
16427 \begin_inset Flex Code
16430 \begin_layout Plain Layout
16437 \begin_inset Flex Code
16440 \begin_layout Plain Layout
16449 \begin_layout Subsection
16451 \begin_inset CommandInset label
16453 name "sub:Font-description"
16460 \begin_layout Standard
16461 A font description looks like this:
16464 \begin_layout LyX-Code
16474 \begin_layout LyX-Code
16478 \begin_layout LyX-Code
16482 \begin_layout Standard
16483 The following commands are available:
16486 \begin_layout Description
16487 \begin_inset Flex Code
16490 \begin_layout Plain Layout
16497 \begin_inset Flex Code
16500 \begin_layout Plain Layout
16509 \begin_inset Flex Code
16512 \begin_layout Plain Layout
16519 \begin_inset Flex Code
16522 \begin_layout Plain Layout
16529 \begin_inset Flex Code
16532 \begin_layout Plain Layout
16539 \begin_inset Flex Code
16542 \begin_layout Plain Layout
16549 \begin_inset Flex Code
16552 \begin_layout Plain Layout
16559 \begin_inset Flex Code
16562 \begin_layout Plain Layout
16569 \begin_inset Flex Code
16572 \begin_layout Plain Layout
16579 \begin_inset Flex Code
16582 \begin_layout Plain Layout
16591 \begin_layout Description
16592 \begin_inset Flex Code
16595 \begin_layout Plain Layout
16602 \begin_inset Flex Code
16605 \begin_layout Plain Layout
16614 \begin_inset Flex Code
16617 \begin_layout Plain Layout
16624 \begin_inset Flex Code
16627 \begin_layout Plain Layout
16636 \begin_layout Description
16637 \begin_inset Flex Code
16640 \begin_layout Plain Layout
16647 \begin_inset Flex Code
16650 \begin_layout Plain Layout
16656 ] Valid arguments are:
16657 \begin_inset Flex Code
16660 \begin_layout Plain Layout
16667 \begin_inset Flex Code
16670 \begin_layout Plain Layout
16677 \begin_inset Flex Code
16680 \begin_layout Plain Layout
16687 \begin_inset Flex Code
16690 \begin_layout Plain Layout
16697 \begin_inset Flex Code
16700 \begin_layout Plain Layout
16707 \begin_inset Flex Code
16710 \begin_layout Plain Layout
16717 \begin_inset Flex Code
16720 \begin_layout Plain Layout
16727 \begin_inset Flex Code
16730 \begin_layout Plain Layout
16737 \begin_inset Flex Code
16740 \begin_layout Plain Layout
16747 \begin_inset Flex Code
16750 \begin_layout Plain Layout
16757 \begin_inset Flex Code
16760 \begin_layout Plain Layout
16767 \begin_inset Flex Code
16770 \begin_layout Plain Layout
16777 Each of these turns on or off the corresponding attribute.
16779 \begin_inset Flex Code
16782 \begin_layout Plain Layout
16788 turns on emphasis, and
16789 \begin_inset Flex Code
16792 \begin_layout Plain Layout
16800 \begin_inset Newline newline
16803 If the latter seems puzzling, remember that the font settings for the present
16804 context are generally inherited from the surrounding context.
16806 \begin_inset Flex Code
16809 \begin_layout Plain Layout
16815 would turn off the emphasis that was anyway in effect, say, in a theorem
16819 \begin_layout Description
16820 \begin_inset Flex Code
16823 \begin_layout Plain Layout
16830 \begin_inset Flex Code
16833 \begin_layout Plain Layout
16842 \begin_inset Flex Code
16845 \begin_layout Plain Layout
16854 \begin_layout Description
16855 \begin_inset Flex Code
16858 \begin_layout Plain Layout
16865 \begin_inset Flex Code
16868 \begin_layout Plain Layout
16877 \begin_inset Flex Code
16880 \begin_layout Plain Layout
16887 \begin_inset Flex Code
16890 \begin_layout Plain Layout
16897 \begin_inset Flex Code
16900 \begin_layout Plain Layout
16909 \begin_layout Description
16910 \begin_inset Flex Code
16913 \begin_layout Plain Layout
16920 \begin_inset Flex Code
16923 \begin_layout Plain Layout
16930 \begin_inset Flex Code
16933 \begin_layout Plain Layout
16940 \begin_inset Flex Code
16943 \begin_layout Plain Layout
16952 \begin_inset Flex Code
16955 \begin_layout Plain Layout
16962 \begin_inset Flex Code
16965 \begin_layout Plain Layout
16972 \begin_inset Flex Code
16975 \begin_layout Plain Layout
16982 \begin_inset Flex Code
16985 \begin_layout Plain Layout
16992 \begin_inset Flex Code
16995 \begin_layout Plain Layout
17004 \begin_layout Subsection
17005 \begin_inset CommandInset label
17007 name "sub:Citation-format-description"
17011 Citation format description
17014 \begin_layout Standard
17016 \begin_inset Flex Code
17019 \begin_layout Plain Layout
17025 blocks are used to describe how bibliographic information should be displayed,
17026 both within LyX itself (in the citation dialog and in tooltips, for example)
17027 and in XHTML output.
17028 Such a block might look like this:
17031 \begin_layout LyX-Code
17035 \begin_layout LyX-Code
17039 \begin_layout LyX-Code
17043 \begin_layout LyX-Code
17047 \begin_layout Standard
17048 The individual lines define how the bibliographic information associated
17049 with an article or book, respectively, is to be displayed, and such a definitio
17050 n can be given for any `entry type' that might be present in a BibTeX file.
17051 LyX defines a default format in the source code that will be used if no
17052 specific definition has been given.
17053 LyX predefines several formats in the file
17054 \begin_inset Flex Code
17057 \begin_layout Plain Layout
17063 , which is included in most of LyX's document classes.
17066 \begin_layout Standard
17067 The definitions use a simple language that allows BibTeX keys to be replaced
17069 Keys should be enclosed in
17070 \begin_inset Flex Code
17073 \begin_layout Plain Layout
17080 \begin_inset Flex Code
17083 \begin_layout Plain Layout
17090 So a simple definition might look like this:
17093 \begin_layout LyX-Code
17095 \begin_inset Quotes eld
17099 \begin_inset Quotes erd
17105 \begin_layout Standard
17106 This would print the author, followed by a comma, followed by the title,
17107 in quotes, followed by a period.
17110 \begin_layout Standard
17111 Of course, sometimes you may want to print a key only if it exists.
17112 This can be done by using a conditional construction, such as:
17113 \begin_inset Flex Code
17116 \begin_layout Plain Layout
17118 \begin_inset space ~
17128 \begin_inset Flex Code
17131 \begin_layout Plain Layout
17137 key exists, then print
17138 \begin_inset Quotes eld
17142 \begin_inset space ~
17146 \begin_inset Quotes erd
17149 followed by the volume key.
17150 It is also possible to have an else clause in the conditional, such as:
17152 \begin_inset Flex Code
17155 \begin_layout Plain Layout
17156 {%author%[[%author%]][[%editor%, ed.]]}
17163 \begin_inset Flex Code
17166 \begin_layout Plain Layout
17172 key is printed if it exists; otherwise, the editor key is printed, followed
17174 \begin_inset Quotes eld
17178 \begin_inset space ~
17182 \begin_inset Quotes erd
17185 Note that the key is again enclosed in
17186 \begin_inset Flex Code
17189 \begin_layout Plain Layout
17195 signs; the entire conditional is enclosed in braces; and the if and else
17196 clauses are enclosed in double brackets,
17197 \begin_inset Quotes eld
17201 \begin_inset Flex Code
17204 \begin_layout Plain Layout
17211 \begin_inset Quotes eld
17215 \begin_inset Quotes eld
17219 \begin_inset Flex Code
17222 \begin_layout Plain Layout
17229 \begin_inset Quotes erd
17233 There must be no space between any of these.
17236 \begin_layout Standard
17237 There is one other piece of syntax available in definitions, which looks
17239 \begin_inset Flex Code
17242 \begin_layout Plain Layout
17249 This defines a piece of formatting information that is to be used when
17251 \begin_inset Quotes eld
17255 \begin_inset Quotes erd
17259 Obviously, we do not want to output HTML tags when writing plain text,
17260 so they should be wrapped in
17261 \begin_inset Quotes eld
17265 \begin_inset Quotes erd
17269 \begin_inset Quotes eld
17273 \begin_inset Quotes erd
17279 \begin_layout Standard
17280 Two special sorts of definitions are also possible in a
17281 \begin_inset Flex Code
17284 \begin_layout Plain Layout
17291 An example of the first would be:
17294 \begin_layout LyX-Code
17296 \begin_inset Quotes eld
17300 \begin_inset Quotes erd
17306 \begin_layout Standard
17307 This is an abbreviation, or macro, and it can be used by treating it as
17309 \begin_inset Flex Code
17312 \begin_layout Plain Layout
17320 \begin_inset Flex Code
17323 \begin_layout Plain Layout
17329 exactly as it would treat its definition.
17330 So, let us issue the obvious
17338 \begin_layout LyX-Code
17342 \begin_layout Standard
17343 or anything like it.
17344 LyX shouldn't go into an infinite loop, but it may go into a long one before
17348 \begin_layout Standard
17349 The second sort of special definition might look like this:
17352 \begin_layout LyX-Code
17356 \begin_layout Standard
17357 This defines a translatable piece of text, which allows relevant parts of
17358 the bibliography to be translated.
17359 It can be included in a definition by treating it as a key:
17360 \begin_inset Flex Code
17363 \begin_layout Plain Layout
17370 Several of these are predefined in
17371 \begin_inset Flex Code
17374 \begin_layout Plain Layout
17381 Note that these are not macros, in the sense just defined.
17382 They will not be expanded.
17385 \begin_layout Standard
17386 So here then is an example that use all these features:
17389 \begin_layout LyX-Code
17390 !authoredit {%author%[[%author%, ]][[{%editor%[[%editor%, %_edtext%, ]]}]]}
17393 \begin_layout Standard
17394 This defines a macro that prints the author, followed by a comma, if the
17396 \begin_inset Flex Code
17399 \begin_layout Plain Layout
17405 key is defined, or else prints the name of the editor, followed by the
17407 \begin_inset Flex Code
17410 \begin_layout Plain Layout
17416 or its translation (it is by default
17417 \begin_inset Quotes eld
17421 \begin_inset Quotes erd
17425 \begin_inset Flex Code
17428 \begin_layout Plain Layout
17435 Note that this is in fact defined in
17436 \begin_inset Flex Code
17439 \begin_layout Plain Layout
17445 , so you can use it in your own definitions, or re-definitions, if you load
17449 \begin_layout Section
17450 \begin_inset CommandInset label
17452 name "sec:Tags-for-XHTML"
17456 Tags for XHTML output
17459 \begin_layout Standard
17460 As with LaTeX or DocBook, the format of LyX's XHTML output is also controlled
17461 by layout information.
17462 In general, LyX provides sensible defaults and, as mentioned earlier, it
17463 will even construct default CSS style rules from the other layout tags.
17464 For example, LyX will attempt to use the information provided in the
17465 \begin_inset Flex Code
17468 \begin_layout Plain Layout
17474 declaration for the Chapter style to write CSS that will appropriately
17475 format chapter headings.
17478 \begin_layout Standard
17479 In many cases, then, you may not have to do anything at all to get acceptable
17480 XHTML output for your own environments, custom insets, and so forth.
17481 But in some cases you will, and so LyX provides a number of layout tags
17482 that can be used to customize the XHTML and CSS that are generated.
17485 \begin_layout Standard
17486 Note that there are two tags,
17487 \begin_inset Flex Code
17490 \begin_layout Plain Layout
17497 \begin_inset Flex Code
17500 \begin_layout Plain Layout
17506 that may appear outside style and inset declarations.
17508 \begin_inset CommandInset ref
17510 reference "sub:General-text-class"
17514 for details on these.
17517 \begin_layout Subsection
17518 \begin_inset CommandInset label
17520 name "sub:Paragraph-Style-XHTML"
17527 \begin_layout Standard
17528 The sort of XHTML LyX outputs for a paragraph depends upon whether we are
17529 dealing with a normal paragraph, a command, or an environment, where this
17530 is itself determined by the contents of the corresponding
17531 \begin_inset Flex Code
17534 \begin_layout Plain Layout
17544 \begin_layout Standard
17545 For a command or normal paragraph, the output XHTML has the following form:
17548 \begin_layout LyX-Code
17550 \begin_inset Quotes erd
17554 \begin_inset Quotes erd
17560 \begin_layout LyX-Code
17562 \begin_inset Quotes erd
17566 \begin_inset Quotes erd
17572 \begin_layout LyX-Code
17573 Contents of the paragraph.
17576 \begin_layout LyX-Code
17580 \begin_layout Standard
17581 The label tags are of course omitted if the paragraph does not have a label.
17584 \begin_layout Standard
17585 For an environment that is not some sort of list, the XHTML takes this form:
17588 \begin_layout LyX-Code
17590 \begin_inset Quotes erd
17594 \begin_inset Quotes erd
17600 \begin_layout LyX-Code
17602 \begin_inset Quotes erd
17606 \begin_inset Quotes erd
17610 \begin_inset Quotes erd
17614 \begin_inset Quotes erd
17617 >Environment Label</labeltag>First paragraph.</itemtag>
17620 \begin_layout LyX-Code
17621 <itemtag>Second paragraph.</itemtag>
17624 \begin_layout LyX-Code
17628 \begin_layout Standard
17629 Note that the label is output only for the first paragraph, as it should
17630 be for a theorem, for example.
17634 \begin_layout Standard
17635 For a list, we have one of these forms:
17638 \begin_layout LyX-Code
17640 \begin_inset Quotes erd
17644 \begin_inset Quotes erd
17650 \begin_layout LyX-Code
17652 \begin_inset Quotes erd
17656 \begin_inset Quotes erd
17660 \begin_inset Quotes erd
17664 \begin_inset Quotes erd
17667 >List Label</labeltag>First item.</itemtag>
17670 \begin_layout LyX-Code
17672 \begin_inset Quotes erd
17676 \begin_inset Quotes erd
17680 \begin_inset Quotes erd
17684 \begin_inset Quotes erd
17687 >List Label</labeltag>Second item.</itemtag>
17690 \begin_layout LyX-Code
17694 \begin_layout LyX-Code
17698 \begin_layout LyX-Code
17700 \begin_inset Quotes erd
17704 \begin_inset Quotes erd
17710 \begin_layout LyX-Code
17712 \begin_inset Quotes erd
17716 \begin_inset Quotes erd
17719 >List Label</labeltag><itemtag attr=
17720 \begin_inset Quotes erd
17724 \begin_inset Quotes erd
17727 >First item.</itemtag>
17730 \begin_layout LyX-Code
17732 \begin_inset Quotes erd
17736 \begin_inset Quotes erd
17739 >List Label</labeltag><itemtag attr=
17740 \begin_inset Quotes erd
17744 \begin_inset Quotes erd
17747 >Second item.</itemtag>
17750 \begin_layout LyX-Code
17754 \begin_layout Standard
17755 Note the different orders of
17756 \begin_inset Flex Code
17759 \begin_layout Plain Layout
17766 \begin_inset Flex Code
17769 \begin_layout Plain Layout
17776 Which order we get depends upon the setting of
17777 \begin_inset Flex Code
17780 \begin_layout Plain Layout
17787 \begin_inset Flex Code
17790 \begin_layout Plain Layout
17796 is false (the default), you get the first of these, with the label within
17797 the item; if true, you get the second, with the label outside the item.
17800 \begin_layout Standard
17801 The specific tags and attributes output for each paragraph type can be controlle
17802 d by means of the layout tags we are about to describe.
17803 As mentioned earlier, however, LyX uses sensible defaults for many of these,
17804 so you often may not need to do very much to get good XHTML output.
17805 Think of the available tags as there so you can tweak things to your liking.
17808 \begin_layout Description
17809 \begin_inset Flex Code
17812 \begin_layout Plain Layout
17819 \begin_inset Flex Code
17822 \begin_layout Plain Layout
17828 ] Specifies attribute information to be output with the main tag.
17830 \begin_inset Quotes eld
17834 \begin_inset Flex Code
17837 \begin_layout Plain Layout
17844 \begin_inset Quotes erd
17848 By default, LyX will output
17849 \begin_inset Quotes eld
17853 \begin_inset Flex Code
17856 \begin_layout Plain Layout
17863 \begin_inset Quotes erd
17867 \begin_inset Flex Code
17870 \begin_layout Plain Layout
17876 is the LyX name of the layout, made lowercase, for example: chapter.
17881 contain any style information.
17883 \begin_inset Flex Code
17886 \begin_layout Plain Layout
17895 \begin_layout Description
17896 \begin_inset Flex Code
17899 \begin_layout Plain Layout
17906 \begin_inset Flex Code
17909 \begin_layout Plain Layout
17919 ] Whether to output the default CSS information LyX generates for this layout,
17920 even if additional information is explicitly provided via
17921 \begin_inset Flex Code
17924 \begin_layout Plain Layout
17932 \begin_inset Flex Code
17935 \begin_layout Plain Layout
17941 allows you to alter or augment the generated CSS, rather than to override
17944 \begin_inset Flex Code
17947 \begin_layout Plain Layout
17956 \begin_layout Description
17957 \begin_inset Flex Code
17960 \begin_layout Plain Layout
17967 \begin_inset Flex Code
17970 \begin_layout Plain Layout
17976 ] The tag to be used for individual paragraphs of environments, replacing
17978 \begin_inset Flex Code
17981 \begin_layout Plain Layout
17987 in the examples above.
17989 \begin_inset Flex Code
17992 \begin_layout Plain Layout
18001 \begin_layout Description
18002 \begin_inset Flex Code
18005 \begin_layout Plain Layout
18012 \begin_inset Flex Code
18015 \begin_layout Plain Layout
18021 ] Attributes for the item tag.
18023 \begin_inset Quotes eld
18027 \begin_inset Flex Code
18030 \begin_layout Plain Layout
18031 class=`layoutname_item'
18037 \begin_inset Quotes erd
18045 contain any style information.
18047 \begin_inset Flex Code
18050 \begin_layout Plain Layout
18059 \begin_layout Description
18060 \begin_inset Flex Code
18063 \begin_layout Plain Layout
18070 \begin_inset Flex Code
18073 \begin_layout Plain Layout
18079 ] The tag to be used for paragraph and item labels, replacing
18080 \begin_inset Flex Code
18083 \begin_layout Plain Layout
18089 in the examples above.
18091 \begin_inset Flex Code
18094 \begin_layout Plain Layout
18101 \begin_inset Flex Code
18104 \begin_layout Plain Layout
18111 \begin_inset Flex Code
18114 \begin_layout Plain Layout
18121 \begin_inset Flex Code
18124 \begin_layout Plain Layout
18125 Centered_Top_Environment
18130 , in which case it defaults to
18131 \begin_inset Flex Code
18134 \begin_layout Plain Layout
18143 \begin_layout Description
18144 \begin_inset Flex Code
18147 \begin_layout Plain Layout
18154 \begin_inset Flex Code
18157 \begin_layout Plain Layout
18163 ] Attributes for the label tag.
18165 \begin_inset Quotes eld
18169 \begin_inset Flex Code
18172 \begin_layout Plain Layout
18173 class=`layoutname_label'
18179 \begin_inset Quotes erd
18187 contain any style information.
18189 \begin_inset Flex Code
18192 \begin_layout Plain Layout
18201 \begin_layout Description
18202 \begin_inset Flex Code
18205 \begin_layout Plain Layout
18212 \begin_inset Flex Code
18215 \begin_layout Plain Layout
18225 ] Meaningful only for list-like environments, this tag controls whether
18226 the label tag is output before or inside the item tag.
18227 This is used, for example, in the description environment, where we want
18229 \begin_inset Flex Code
18232 \begin_layout Plain Layout
18233 <dt>\SpecialChar \ldots{}
18234 </dt><dd>\SpecialChar \ldots{}
18242 \begin_inset Flex Code
18245 \begin_layout Plain Layout
18251 : The label tag is output inside the item tag.
18254 \begin_layout Description
18255 \begin_inset Flex Code
18258 \begin_layout Plain Layout
18264 Information to be output in the
18265 \begin_inset Flex Code
18268 \begin_layout Plain Layout
18274 section when this style is used.
18275 This might, for example, be used to include a
18276 \begin_inset Flex Code
18279 \begin_layout Plain Layout
18286 \begin_inset Flex Code
18289 \begin_layout Plain Layout
18298 \begin_layout Description
18299 \begin_inset Flex Code
18302 \begin_layout Plain Layout
18308 CSS style information to be included when this style is used.
18309 Note that this will automatically be wrapped in a layout-generated
18310 \begin_inset Flex Code
18313 \begin_layout Plain Layout
18319 block, so only the CSS itself need be included.
18322 \begin_layout Description
18323 \begin_inset Flex Code
18326 \begin_layout Plain Layout
18333 \begin_inset Flex Code
18336 \begin_layout Plain Layout
18342 ] The tag to be used for the main label, replacing
18343 \begin_inset Flex Code
18346 \begin_layout Plain Layout
18352 in the examples above.
18354 \begin_inset Flex Code
18357 \begin_layout Plain Layout
18366 \begin_layout Description
18367 \begin_inset Flex Code
18370 \begin_layout Plain Layout
18377 \begin_inset Flex Code
18380 \begin_layout Plain Layout
18390 ] Marks this style as the one to be used to generate the
18391 \begin_inset Flex Code
18394 \begin_layout Plain Layout
18400 tag for the XHTML file.
18401 By default, it is false.
18403 \begin_inset Flex Code
18406 \begin_layout Plain Layout
18412 file sets it to true for the
18413 \begin_inset Flex Code
18416 \begin_layout Plain Layout
18426 \begin_layout Subsection
18430 \begin_layout Standard
18431 The XHTML output of insets can also be controlled by information in layout
18436 \begin_layout Plain Layout
18437 At present, this is true only for
18438 \begin_inset Quotes eld
18442 \begin_inset Quotes erd
18445 insets (insets you can type into) and is not true for
18446 \begin_inset Quotes eld
18450 \begin_inset Quotes erd
18453 insets (insets that are associated with dialog boxes).
18458 Here, too, LyX tries to provide sensible defaults, and it constructs default
18460 But everything can be customized.
18463 \begin_layout Standard
18464 The XHTML LyX outputs for an inset has the following form:
18467 \begin_layout LyX-Code
18469 \begin_inset Quotes erd
18473 \begin_inset Quotes erd
18479 \begin_layout LyX-Code
18480 <labeltag>Label</labeltag>
18483 \begin_layout LyX-Code
18485 \begin_inset Quotes erd
18489 \begin_inset Quotes erd
18492 >Contents of the inset.</innertag>
18495 \begin_layout LyX-Code
18499 \begin_layout Standard
18500 If the inset permits multiple paragraphs---that is, if
18501 \begin_inset Flex Code
18504 \begin_layout Plain Layout
18510 is true---then the contents of the inset will itself be output as paragraphs
18511 formatted according to the styles used for those paragraphs (standard,
18512 quote, and the like).
18513 The label tag is of course omitted if the paragraph does not have a label
18514 and, at present, is always
18515 \begin_inset Flex Code
18518 \begin_layout Plain Layout
18525 The inner tag is optional and, by default, does not appear.
18528 \begin_layout Standard
18529 The specific tags and attributes output for each inset can be controlled
18530 by means of the following layout tags.
18533 \begin_layout Description
18534 \begin_inset Flex Code
18537 \begin_layout Plain Layout
18544 \begin_inset Flex Code
18547 \begin_layout Plain Layout
18553 ] Specifies attribute information to be output with the main tag.
18555 \begin_inset Quotes eld
18559 \begin_inset Flex Code
18562 \begin_layout Plain Layout
18563 class=`myinset' onclick=`\SpecialChar \ldots{}
18570 \begin_inset Quotes erd
18574 By default, LyX will output
18575 \begin_inset Quotes eld
18579 \begin_inset Flex Code
18582 \begin_layout Plain Layout
18589 \begin_inset Quotes erd
18593 \begin_inset Flex Code
18596 \begin_layout Plain Layout
18602 is the LyX name of the inset, made lowercase and with non-alphanumeric
18603 characters converted to underscores, for example: footnote.
18606 \begin_layout Description
18607 \begin_inset Flex Code
18610 \begin_layout Plain Layout
18617 \begin_inset Flex Code
18620 \begin_layout Plain Layout
18630 ] Whether to output the default CSS information LyX generates for this layout,
18631 even if additional information is explicitly provided via
18632 \begin_inset Flex Code
18635 \begin_layout Plain Layout
18643 \begin_inset Flex Code
18646 \begin_layout Plain Layout
18652 allows you to alter or augment the generated CSS, rather than to override
18657 \begin_layout Description
18658 \begin_inset Flex Code
18661 \begin_layout Plain Layout
18668 \begin_inset Flex Code
18671 \begin_layout Plain Layout
18677 ] Attributes for the inner tag.
18679 \begin_inset Quotes eld
18683 \begin_inset Flex Code
18686 \begin_layout Plain Layout
18687 class=`insetname_inner'
18693 \begin_inset Quotes erd
18699 \begin_layout Description
18700 \begin_inset Flex Code
18703 \begin_layout Plain Layout
18710 \begin_inset Flex Code
18713 \begin_layout Plain Layout
18719 ] The inner tag, replacing
18720 \begin_inset Flex Code
18723 \begin_layout Plain Layout
18729 in the examples above.
18730 By default, there is none.
18733 \begin_layout Description
18734 \begin_inset Flex Code
18737 \begin_layout Plain Layout
18744 \begin_inset Flex Code
18747 \begin_layout Plain Layout
18755 ] Whether this inset represents a standalone block of text (such as a footnote)
18756 or instead represents material that is included in the surrounding text
18757 (such as a branch).
18761 \begin_layout Description
18762 \begin_inset Flex Code
18765 \begin_layout Plain Layout
18772 \begin_inset Flex Code
18775 \begin_layout Plain Layout
18781 ] A label for this inset, possibly including a reference to a counter.
18782 For example, for footnote, it might be:
18783 \begin_inset Flex Code
18786 \begin_layout Plain Layout
18795 This is optional, and there is no default.
18798 \begin_layout Description
18799 \begin_inset Flex Code
18802 \begin_layout Plain Layout
18808 Information to be output in the
18809 \begin_inset Flex Code
18812 \begin_layout Plain Layout
18818 section when this style is used.
18819 This might, for example, be used to include a
18820 \begin_inset Flex Code
18823 \begin_layout Plain Layout
18830 \begin_inset Flex Code
18833 \begin_layout Plain Layout
18842 \begin_layout Description
18843 \begin_inset Flex Code
18846 \begin_layout Plain Layout
18852 CSS style information to be included when this style is used.
18853 Note that this will automatically be wrapped in a layout-generated
18854 \begin_inset Flex Code
18857 \begin_layout Plain Layout
18863 block, so only the CSS itself need be included.
18866 \begin_layout Description
18867 \begin_inset Flex Code
18870 \begin_layout Plain Layout
18877 \begin_inset Flex Code
18880 \begin_layout Plain Layout
18886 ] The tag to be used for the main label, replacing
18887 \begin_inset Flex Code
18890 \begin_layout Plain Layout
18896 in the examples above.
18897 The default depends upon the setting of
18898 \begin_inset Flex Code
18901 \begin_layout Plain Layout
18908 \begin_inset Flex Code
18911 \begin_layout Plain Layout
18917 is true, the default is
18918 \begin_inset Flex Code
18921 \begin_layout Plain Layout
18927 ; if it is false, the default is
18928 \begin_inset Flex Code
18931 \begin_layout Plain Layout
18940 \begin_layout Subsection
18944 \begin_layout Standard
18945 The XHTML output for floats too can be controlled by layout information.
18946 The output has the following form:
18949 \begin_layout LyX-Code
18951 \begin_inset Quotes erd
18955 \begin_inset Quotes erd
18961 \begin_layout LyX-Code
18962 Contents of the float.
18965 \begin_layout LyX-Code
18969 \begin_layout Standard
18970 The caption, if there is one, is a separate inset and will be output as
18972 Its appearance can be controlled via the InsetLayout for caption insets.
18976 \begin_layout Description
18977 \begin_inset Flex Code
18980 \begin_layout Plain Layout
18987 \begin_inset Flex Code
18990 \begin_layout Plain Layout
18996 ] Specifies attribute information to be output with the main tag.
18998 \begin_inset Quotes eld
19002 \begin_inset Flex Code
19005 \begin_layout Plain Layout
19006 class=`myfloat' onclick=`\SpecialChar \ldots{}
19013 \begin_inset Quotes erd
19017 By default, LyX will output
19018 \begin_inset Quotes eld
19022 \begin_inset Flex Code
19025 \begin_layout Plain Layout
19026 class=`float float-floattype'
19032 \begin_inset Quotes erd
19036 \begin_inset Flex Code
19039 \begin_layout Plain Layout
19045 is LyX's name for this type of float, as determined by the float declaration
19047 \begin_inset CommandInset ref
19049 reference "sub:Floats"
19053 ), though made lowercase and with non-alphanumeric characters converted
19054 to underscores, for example: float-table.
19057 \begin_layout Description
19058 \begin_inset Flex Code
19061 \begin_layout Plain Layout
19067 CSS style information to be included when this float is used.
19068 Note that this will automatically be wrapped in a layout-generated
19069 \begin_inset Flex Code
19072 \begin_layout Plain Layout
19078 block, so only the CSS itself need be included.
19081 \begin_layout Description
19082 \begin_inset Flex Code
19085 \begin_layout Plain Layout
19092 \begin_inset Flex Code
19095 \begin_layout Plain Layout
19101 ] The tag to be used for this float, replacing
19102 \begin_inset Quotes eld
19106 \begin_inset Flex Code
19109 \begin_layout Plain Layout
19116 \begin_inset Quotes erd
19119 in the example above.
19121 \begin_inset Flex Code
19124 \begin_layout Plain Layout
19130 and will rarely need changing.
19133 \begin_layout Subsection
19134 Bibliography formatting
19137 \begin_layout Standard
19138 The bibliography can be formatted using
19139 \begin_inset Flex Code
19142 \begin_layout Plain Layout
19150 \begin_inset CommandInset ref
19152 reference "sub:Citation-format-description"
19159 \begin_layout Subsection
19163 \begin_layout Standard
19164 We have several times mentioned that LyX will generate default CSS style
19165 rules for both insets and paragraph styles, based upon the other layout
19166 information that is provided.
19167 In this section, we shall say a word about which layout information LyX
19171 \begin_layout Standard
19172 At present, LyX auto-generates CSS only for font information, making use
19174 \begin_inset Flex Code
19177 \begin_layout Plain Layout
19184 \begin_inset Flex Code
19187 \begin_layout Plain Layout
19194 \begin_inset Flex Code
19197 \begin_layout Plain Layout
19204 \begin_inset Flex Code
19207 \begin_layout Plain Layout
19214 \begin_inset Flex Code
19217 \begin_layout Plain Layout
19225 \begin_inset CommandInset ref
19227 reference "sub:Font-description"
19231 .) The translation is mostly straightforward and obvious.
19233 \begin_inset Quotes eld
19237 \begin_inset Flex Code
19240 \begin_layout Plain Layout
19247 \begin_inset Quotes erd
19251 \begin_inset Quotes eld
19255 \begin_inset Flex Code
19258 \begin_layout Plain Layout
19259 font-family: sans-serif;
19265 \begin_inset Quotes erd
19269 The correspondence of LyX sizes and CSS sizes is a little less obvious
19270 but nonetheless intuitive.
19272 \begin_inset Flex Code
19275 \begin_layout Plain Layout
19282 \begin_inset Flex URL
19285 \begin_layout Plain Layout
19295 \begin_layout Chapter
19296 Including External Material
19299 \begin_layout Standard
19300 \begin_inset Box Shadowbox
19310 height_special "totalheight"
19313 \begin_layout Plain Layout
19314 WARNING: This portion of the documentation has not been updated for some
19316 We certainly hope that it is still accurate, but there are no guarantees.
19324 \begin_layout Standard
19325 The use of material from sources external to LyX is covered in detail in
19331 This part of the manual covers what needs to happen behind the scenes for
19332 new sorts of material to be included.
19335 \begin_layout Section
19339 \begin_layout Standard
19340 The external material feature is based on the concept of a
19345 A template is a specification of how LyX should interface with a certain
19347 As bundled, LyX comes with predefined templates for Xfig figures, various
19348 raster format images, chess diagrams, and LilyPond music notation.
19349 You can check the actual list by using the menu
19350 \begin_inset Flex MenuItem
19353 \begin_layout Plain Layout
19354 Insert\SpecialChar \menuseparator
19355 File\SpecialChar \menuseparator
19362 Furthermore, it is possible to roll your own template to support a specific
19364 Later we'll describe in more detail what is involved, and hopefully you
19365 will submit all the templates you create so we can include them in a later
19369 \begin_layout Standard
19370 Another basic idea of the external material feature is to distinguish between
19371 the original file that serves as a base for final material and the produced
19372 file that is included in your exported or printed document.
19373 For example, consider the case of a figure produced with
19374 \begin_inset Flex Code
19377 \begin_layout Plain Layout
19384 The Xfig application itself works on an original file with the
19385 \begin_inset Flex Code
19388 \begin_layout Plain Layout
19395 Within Xfig, you create and change your figure, and when you are done,
19397 \begin_inset Flex Code
19400 \begin_layout Plain Layout
19407 When you want to include the figure in your document, you invoke
19408 \begin_inset Flex Code
19411 \begin_layout Plain Layout
19417 in order to create a PostScript file that can readily be included in your
19420 \begin_inset Flex Code
19423 \begin_layout Plain Layout
19429 file is the original file, and the PostScript file is the produced file.
19432 \begin_layout Standard
19433 This distinction is important in order to allow updating of the material
19434 while you are in the process of writing the document.
19435 Furthermore, it provides us with the flexibility that is needed to support
19436 multiple export formats.
19437 For instance, in the case of a plain text file, it is not exactly an award-winn
19438 ing idea to include the figure as raw PostScript.
19439 Instead, you would either prefer to just include a reference to the figure
19440 or try to invoke some graphics to ASCII converter to make the final result
19441 look similar to the real graphics.
19442 The external material management allows you to do this, because it is parametri
19443 zed on the different export formats that LyX supports.
19446 \begin_layout Standard
19447 Besides supporting the production of different products according to the
19448 exported format, it supports tight integration with editing and viewing
19450 In the case of an Xfig figure, you are able to invoke Xfig on the original
19451 file with a single click from within the external material dialog in LyX,
19452 and also preview the produced PostScript file with Ghostview with another
19454 No more fiddling around with the command line and/or file browsers to locate
19455 and manipulate the original or produced files.
19456 In this way, you are finally able to take full advantage of the many different
19457 applications that are relevant to use when you write your documents, and
19458 ultimately be more productive.
19461 \begin_layout Section
19462 The external template configuration file
19465 \begin_layout Standard
19466 It is relatively easy to add custom external template definitions to LyX.
19467 However, be aware that doing this in an careless manner most probably
19471 introduce an easily exploitable security hole.
19472 So before you do this, please read the discussion about security in section
19474 \begin_inset CommandInset ref
19476 reference "sec:Security-discussion"
19483 \begin_layout Standard
19484 Having said that, we encourage you to submit any interesting templates that
19489 \begin_layout Standard
19490 The external templates are defined in the
19491 \begin_inset Flex Code
19494 \begin_layout Plain Layout
19495 LyXDir/lib/external_templates
19501 You can place your own version in
19502 \begin_inset Flex Code
19505 \begin_layout Plain Layout
19506 UserDir/external_templates
19514 \begin_layout Standard
19515 A typical template looks like this:
19518 \begin_layout LyX-Code
19522 \begin_layout LyX-Code
19523 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
19526 \begin_layout LyX-Code
19530 \begin_layout LyX-Code
19534 \begin_layout LyX-Code
19538 \begin_layout LyX-Code
19542 \begin_layout LyX-Code
19546 \begin_layout LyX-Code
19547 AutomaticProduction true
19550 \begin_layout LyX-Code
19554 \begin_layout LyX-Code
19558 \begin_layout LyX-Code
19562 \begin_layout LyX-Code
19563 TransformCommand Rotate RotationLatexCommand
19566 \begin_layout LyX-Code
19567 TransformCommand Resize ResizeLatexCommand
19570 \begin_layout LyX-Code
19571 Product "$$RotateFront$$ResizeFront
19574 \begin_layout LyX-Code
19579 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
19582 \begin_layout LyX-Code
19583 $$ResizeBack$$RotateBack"
19586 \begin_layout LyX-Code
19590 \begin_layout LyX-Code
19591 UpdateResult "$$AbsPath$$Basename.pstex_t"
19594 \begin_layout LyX-Code
19595 Requirement "graphicx"
19598 \begin_layout LyX-Code
19599 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
19602 \begin_layout LyX-Code
19603 ReferencedFile latex "$$AbsPath$$Basename.eps"
19606 \begin_layout LyX-Code
19607 ReferencedFile dvi "$$AbsPath$$Basename.eps"
19610 \begin_layout LyX-Code
19614 \begin_layout LyX-Code
19618 \begin_layout LyX-Code
19619 TransformCommand Rotate RotationLatexCommand
19622 \begin_layout LyX-Code
19623 TransformCommand Resize ResizeLatexCommand
19626 \begin_layout LyX-Code
19627 Product "$$RotateFront$$ResizeFront
19630 \begin_layout LyX-Code
19635 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
19638 \begin_layout LyX-Code
19639 $$ResizeBack$$RotateBack"
19642 \begin_layout LyX-Code
19643 UpdateFormat pdftex
19646 \begin_layout LyX-Code
19647 UpdateResult "$$AbsPath$$Basename.pdftex_t"
19650 \begin_layout LyX-Code
19651 Requirement "graphicx"
19654 \begin_layout LyX-Code
19655 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
19658 \begin_layout LyX-Code
19659 ReferencedFile latex "$$AbsPath$$Basename.pdf"
19662 \begin_layout LyX-Code
19666 \begin_layout LyX-Code
19670 \begin_layout LyX-Code
19671 Product "$$Contents(
19673 "$$AbsPath$$Basename.asc
19678 \begin_layout LyX-Code
19679 UpdateFormat asciixfig
19682 \begin_layout LyX-Code
19683 UpdateResult "$$AbsPath$$Basename.asc"
19686 \begin_layout LyX-Code
19690 \begin_layout LyX-Code
19694 \begin_layout LyX-Code
19695 Product "<graphic fileref=
19697 "$$AbsOrRelPathMaster$$Basename.eps
19702 \begin_layout LyX-Code
19706 \begin_layout LyX-Code
19710 \begin_layout LyX-Code
19711 UpdateResult "$$AbsPath$$Basename.eps"
19714 \begin_layout LyX-Code
19715 ReferencedFile docbook "$$AbsPath$$Basename.eps"
19718 \begin_layout LyX-Code
19719 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
19722 \begin_layout LyX-Code
19726 \begin_layout LyX-Code
19727 Product "[XFig: $$FName]"
19730 \begin_layout LyX-Code
19734 \begin_layout LyX-Code
19738 \begin_layout Standard
19739 As you can see, the template is enclosed in
19740 \begin_inset Flex Code
19743 \begin_layout Plain Layout
19749 \SpecialChar \ldots{}
19751 \begin_inset Flex Code
19754 \begin_layout Plain Layout
19761 It contains a header specifying some general settings and, for each supported
19762 primary document file format, a section
19763 \begin_inset Flex Code
19766 \begin_layout Plain Layout
19772 \SpecialChar \ldots{}
19774 \begin_inset Flex Code
19777 \begin_layout Plain Layout
19786 \begin_layout Subsection
19787 The template header
19790 \begin_layout Description
19791 \begin_inset Flex Code
19794 \begin_layout Plain Layout
19795 AutomaticProduction
19796 \begin_inset space ~
19804 Whether the file represented by the template must be generated by LyX.
19805 This command must occur exactly once.
19808 \begin_layout Description
19809 \begin_inset Flex Code
19812 \begin_layout Plain Layout
19814 \begin_inset space ~
19822 A glob pattern that is used in the file dialog to filter out the desired
19824 If there is more than one possible file extension (e.
19825 \begin_inset space \thinspace{}
19829 \begin_inset space \space{}
19833 \begin_inset Flex Code
19836 \begin_layout Plain Layout
19843 \begin_inset Flex Code
19846 \begin_layout Plain Layout
19852 ), use something like
19853 \begin_inset Flex Code
19856 \begin_layout Plain Layout
19863 This command must occur exactly once.
19866 \begin_layout Description
19867 \begin_inset Flex Code
19870 \begin_layout Plain Layout
19872 \begin_inset space ~
19880 The text that is displayed on the button.
19881 This command must occur exactly once.
19884 \begin_layout Description
19885 \begin_inset Flex Code
19888 \begin_layout Plain Layout
19890 \begin_inset space ~
19894 \begin_inset space ~
19902 The help text that is used in the External dialog.
19903 Provide enough information to explain to the user just what the template
19904 can provide him with.
19905 This command must occur exactly once.
19908 \begin_layout Description
19909 \begin_inset Flex Code
19912 \begin_layout Plain Layout
19914 \begin_inset space ~
19922 The file format of the original file.
19923 This must be the name of a format that is known to LyX (see section
19924 \begin_inset space ~
19928 \begin_inset CommandInset ref
19930 reference "sec:Formats"
19936 \begin_inset Quotes eld
19940 \begin_inset Flex Code
19943 \begin_layout Plain Layout
19950 \begin_inset Quotes erd
19953 if the template can handle original files of more than one format.
19954 LyX will attempt to interrogate the file itself in order to deduce its
19955 format in this case.
19956 This command must occur exactly once.
19959 \begin_layout Description
19960 \begin_inset Flex Code
19963 \begin_layout Plain Layout
19965 \begin_inset space ~
19973 A unique name for the template.
19974 It must not contain substitution macros (see below).
19977 \begin_layout Description
19978 \begin_inset Flex Code
19981 \begin_layout Plain Layout
19983 \begin_inset space ~
19986 Rotate|Resize|Clip|Extra
19991 This command specifies which transformations are supported by this template.
19992 It may occur zero or more times.
19993 This command enables the corresponding tabs in the external dialog.
19995 \begin_inset Flex Code
19998 \begin_layout Plain Layout
20004 command must have either a corresponding
20005 \begin_inset Flex Code
20008 \begin_layout Plain Layout
20015 \begin_inset Flex Code
20018 \begin_layout Plain Layout
20025 \begin_inset Flex Code
20028 \begin_layout Plain Layout
20035 Otherwise the transformation will not be supported by that format.
20038 \begin_layout Subsection
20042 \begin_layout Description
20043 \begin_inset Flex Code
20046 \begin_layout Plain Layout
20048 \begin_inset space ~
20051 LaTeX|PDFLaTeX|PlainText|DocBook
20056 The primary document file format that this format definition is for.
20057 Not every template has a sensible representation in all document file formats.
20058 Please define nevertheless a
20059 \begin_inset Flex Code
20062 \begin_layout Plain Layout
20068 section for all templates.
20069 Use a dummy text when no representation is available.
20070 Then you can at least see a reference to the external material in the exported
20074 \begin_layout Description
20075 \begin_inset Flex Code
20078 \begin_layout Plain Layout
20080 \begin_inset space ~
20084 \begin_inset space ~
20092 This command defines an additional macro
20093 \begin_inset Flex Code
20096 \begin_layout Plain Layout
20102 for substitution in
20103 \begin_inset Flex Code
20106 \begin_layout Plain Layout
20114 \begin_inset Flex Code
20117 \begin_layout Plain Layout
20123 itself may contain substitution macros.
20124 The advantage over using
20125 \begin_inset Flex Code
20128 \begin_layout Plain Layout
20135 \begin_inset Flex Code
20138 \begin_layout Plain Layout
20144 is that the substituted value of
20145 \begin_inset Flex Code
20148 \begin_layout Plain Layout
20154 is sanitized so that it is a valid optional argument in the document format.
20155 This command may occur zero or more times.
20158 \begin_layout Description
20159 \begin_inset Flex Code
20162 \begin_layout Plain Layout
20164 \begin_inset space ~
20172 The text that is inserted in the exported document.
20173 This is actually the most important command and can be quite complex.
20174 This command must occur exactly once.
20177 \begin_layout Description
20178 \begin_inset Flex Code
20181 \begin_layout Plain Layout
20183 \begin_inset space ~
20191 This command specifies a preamble snippet that will be included in the
20193 It has to be defined using
20194 \begin_inset Flex Code
20197 \begin_layout Plain Layout
20203 \SpecialChar \ldots{}
20205 \begin_inset Flex Code
20208 \begin_layout Plain Layout
20215 This command may occur zero or more times.
20218 \begin_layout Description
20219 \begin_inset Flex Code
20222 \begin_layout Plain Layout
20224 \begin_inset space ~
20228 \begin_inset space ~
20236 This command denotes files that are created by the conversion process and
20237 are needed for a particular export format.
20238 If the filename is relative, it is interpreted relative to the master document.
20239 This command may be given zero or more times.
20242 \begin_layout Description
20243 \begin_inset Flex Code
20246 \begin_layout Plain Layout
20248 \begin_inset space ~
20256 The name of a required LaTeX package.
20257 The package is included via
20258 \begin_inset Flex Code
20261 \begin_layout Plain Layout
20269 in the LaTeX preamble.
20270 This command may occur zero or more times.
20273 \begin_layout Description
20274 \begin_inset Flex Code
20277 \begin_layout Plain Layout
20279 \begin_inset space ~
20283 \begin_inset space ~
20286 RotationLatexCommand
20291 This command specifies that the built in LaTeX command should be used for
20293 This command may occur once or not at all.
20296 \begin_layout Description
20297 \begin_inset Flex Code
20300 \begin_layout Plain Layout
20302 \begin_inset space ~
20306 \begin_inset space ~
20314 This command specifies that the built in LaTeX command should be used for
20316 This command may occur once or not at all.
20319 \begin_layout Description
20320 \begin_inset Flex Code
20323 \begin_layout Plain Layout
20325 \begin_inset space ~
20329 \begin_inset space ~
20332 RotationLatexOption
20337 This command specifies that rotation is done via an optional argument.
20338 This command may occur once or not at all.
20341 \begin_layout Description
20342 \begin_inset Flex Code
20345 \begin_layout Plain Layout
20347 \begin_inset space ~
20351 \begin_inset space ~
20359 This command specifies that resizing is done via an optional argument.
20360 This command may occur once or not at all.
20363 \begin_layout Description
20364 \begin_inset Flex Code
20367 \begin_layout Plain Layout
20369 \begin_inset space ~
20373 \begin_inset space ~
20381 This command specifies that clipping is done via an optional argument.
20382 This command may occur once or not at all.
20385 \begin_layout Description
20386 \begin_inset Flex Code
20389 \begin_layout Plain Layout
20391 \begin_inset space ~
20395 \begin_inset space ~
20403 This command specifies that an extra optional argument is used.
20404 This command may occur once or not at all.
20407 \begin_layout Description
20408 \begin_inset Flex Code
20411 \begin_layout Plain Layout
20413 \begin_inset space ~
20421 The file format of the converted file.
20422 This must be the name of a format that is known to LyX (see the
20423 \begin_inset Flex MenuItem
20426 \begin_layout Plain Layout
20431 ools\SpecialChar \menuseparator
20436 references\SpecialChar \menuseparator
20437 File Handling\SpecialChar \menuseparator
20444 This command must occur exactly once.
20447 \begin_layout Description
20448 \begin_inset Flex Code
20451 \begin_layout Plain Layout
20453 \begin_inset space ~
20461 The file name of the converted file.
20462 The file name must be absolute.
20463 This command must occur exactly once.
20466 \begin_layout Subsection
20467 Preamble definitions
20470 \begin_layout Standard
20471 The external template configuration file may contain additional preamble
20472 definitions enclosed by
20473 \begin_inset Flex Code
20476 \begin_layout Plain Layout
20482 \SpecialChar \ldots{}
20484 \begin_inset Flex Code
20487 \begin_layout Plain Layout
20494 They can be used by the templates in the
20495 \begin_inset Flex Code
20498 \begin_layout Plain Layout
20507 \begin_layout Section
20508 The substitution mechanism
20511 \begin_layout Standard
20512 When the external material facility invokes an external program, it is done
20513 on the basis of a command defined in the template configuration file.
20514 These commands can contain various macros that are expanded before execution.
20515 Execution always take place in the directory of the containing document.
20518 \begin_layout Standard
20519 Also, whenever external material is to be displayed, the name will be produced
20520 by the substitution mechanism, and most other commands in the template
20521 definition support substitution as well.
20524 \begin_layout Standard
20525 The available macros are the following:
20528 \begin_layout Description
20529 \begin_inset Flex Code
20532 \begin_layout Plain Layout
20533 $$AbsOrRelPathMaster
20538 The file path, absolute or relative to the master LyX document.
20541 \begin_layout Description
20542 \begin_inset Flex Code
20545 \begin_layout Plain Layout
20546 $$AbsOrRelPathParent
20551 The file path, absolute or relative to the LyX document.
20554 \begin_layout Description
20555 \begin_inset Flex Code
20558 \begin_layout Plain Layout
20564 The absolute file path.
20567 \begin_layout Description
20568 \begin_inset Flex Code
20571 \begin_layout Plain Layout
20577 The filename without path and without the extension.
20580 \begin_layout Description
20581 \begin_inset Flex Code
20584 \begin_layout Plain Layout
20586 \begin_inset Quotes eld
20590 \begin_inset Quotes erd
20598 This macro will expand to the contents of the file with the name
20599 \begin_inset Flex Code
20602 \begin_layout Plain Layout
20611 \begin_layout Description
20612 \begin_inset Flex Code
20615 \begin_layout Plain Layout
20621 The file extension (including the dot).
20624 \begin_layout Description
20625 \begin_inset Flex Code
20628 \begin_layout Plain Layout
20634 The filename of the file specified in the external material dialog.
20635 This is either an absolute name, or it is relative to the LyX document.
20638 \begin_layout Description
20639 \begin_inset Flex Code
20642 \begin_layout Plain Layout
20649 \begin_inset Flex Code
20652 \begin_layout Plain Layout
20658 (absolute name or relative to the LyX document).
20661 \begin_layout Description
20662 \begin_inset Flex Code
20665 \begin_layout Plain Layout
20671 The file path, relative to the master LyX document.
20674 \begin_layout Description
20675 \begin_inset Flex Code
20678 \begin_layout Plain Layout
20684 The file path, relative to the LyX document.
20687 \begin_layout Description
20688 \begin_inset Flex Code
20691 \begin_layout Plain Layout
20697 This macro will expand to the absolute path of the system directory.
20698 This is typically used to point to the various helper scripts that are
20702 \begin_layout Description
20703 \begin_inset Flex Code
20706 \begin_layout Plain Layout
20712 A name and full path to a temporary file which will be automatically deleted
20713 whenever the containing document is closed, or the external material insertion
20717 \begin_layout Standard
20718 All path macros contain a trailing directory separator, so you can construct
20720 \begin_inset space \thinspace{}
20724 \begin_inset space \space{}
20727 the absolute filename with
20728 \begin_inset Flex Code
20731 \begin_layout Plain Layout
20732 $$AbsPath$$Basename$$Extension
20740 \begin_layout Standard
20741 The macros above are substituted in all commands unless otherwise noted.
20743 \begin_inset Flex Code
20746 \begin_layout Plain Layout
20752 supports additionally the following substitutions if they are enabled by
20754 \begin_inset Flex Code
20757 \begin_layout Plain Layout
20764 \begin_inset Flex Code
20767 \begin_layout Plain Layout
20776 \begin_layout Description
20777 \begin_inset Flex Code
20780 \begin_layout Plain Layout
20786 The front part of the resize command.
20789 \begin_layout Description
20790 \begin_inset Flex Code
20793 \begin_layout Plain Layout
20799 The back part of the resize command.
20802 \begin_layout Description
20803 \begin_inset Flex Code
20806 \begin_layout Plain Layout
20812 The front part of the rotation command.
20815 \begin_layout Description
20816 \begin_inset Flex Code
20819 \begin_layout Plain Layout
20825 The back part of the rotation command.
20828 \begin_layout Standard
20829 The value string of the
20830 \begin_inset Flex Code
20833 \begin_layout Plain Layout
20839 command supports additionally the following substitutions if they are enabled
20841 \begin_inset Flex Code
20844 \begin_layout Plain Layout
20851 \begin_inset Flex Code
20854 \begin_layout Plain Layout
20863 \begin_layout Description
20864 \begin_inset Flex Code
20867 \begin_layout Plain Layout
20876 \begin_layout Description
20877 \begin_inset Flex Code
20880 \begin_layout Plain Layout
20889 \begin_layout Description
20890 \begin_inset Flex Code
20893 \begin_layout Plain Layout
20902 \begin_layout Description
20903 \begin_inset Flex Code
20906 \begin_layout Plain Layout
20912 The rotation option.
20915 \begin_layout Standard
20916 You may ask why there are so many path macros.
20917 There are mainly two reasons:
20920 \begin_layout Enumerate
20921 Relative and absolute file names should remain relative or absolute, respectivel
20923 Users may have reasons to prefer either form.
20924 Relative names are useful for portable documents that should work on different
20925 machines, for example.
20926 Absolute names may be required by some programs.
20929 \begin_layout Enumerate
20930 LaTeX treats relative file names differently than LyX and other programs
20931 in nested included files.
20932 For LyX, a relative file name is always relative to the document that contains
20934 For LaTeX, it is always relative to the master document.
20935 These two definitions are identical if you have only one document, but
20936 differ if you have a master document that includes part documents.
20937 That means that relative filenames must be transformed when presented to
20939 Fortunately LyX does this automatically for you if you choose the right
20943 \begin_layout Standard
20944 So which path macro should be used in new template definitions? The rule
20948 \begin_layout Itemize
20950 \begin_inset Flex Code
20953 \begin_layout Plain Layout
20959 if an absolute path is required.
20962 \begin_layout Itemize
20964 \begin_inset Flex Code
20967 \begin_layout Plain Layout
20968 $$AbsOrRelPathMaster
20973 if the substituted string is some kind of LaTeX input.
20976 \begin_layout Itemize
20978 \begin_inset Flex Code
20981 \begin_layout Plain Layout
20982 $$AbsOrRelPathParent
20987 in order to preserve the user's choice.
20990 \begin_layout Standard
20991 There are special cases where this rule does not work and e.
20992 \begin_inset space \thinspace{}
20996 \begin_inset space \space{}
20999 relative names are needed, but normally it will work just fine.
21000 One example for such a case is the command
21001 \begin_inset Flex Code
21004 \begin_layout Plain Layout
21005 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
21010 in the XFig template above: We can't use the absolute name because the
21012 \begin_inset Flex Code
21015 \begin_layout Plain Layout
21021 files needs the relative name in order to rewrite the file content.
21024 \begin_layout Section
21025 Security discussion
21026 \begin_inset CommandInset label
21028 name "sec:Security-discussion"
21035 \begin_layout Standard
21036 The external material feature interfaces with a lot of external programs
21037 and does so automatically, so we have to consider the security implications
21039 In particular, since you have the option of including your own filenames
21040 and/or parameter strings and those are expanded into a command, it seems
21041 that it would be possible to create a malicious document which executes
21042 arbitrary commands when a user views or prints the document.
21043 This is something we definitely want to avoid.
21046 \begin_layout Standard
21047 However, since the external program commands are specified in the template
21048 configuration file only, there are no security issues if LyX is properly
21049 configured with safe templates only.
21050 This is so because the external programs are invoked with the
21051 \begin_inset Flex Code
21054 \begin_layout Plain Layout
21060 -system call rather than the
21061 \begin_inset Flex Code
21064 \begin_layout Plain Layout
21070 system-call, so it's not possible to execute arbitrary commands from the
21071 filename or parameter section via the shell.
21074 \begin_layout Standard
21075 This also implies that you are restricted in what command strings you can
21076 use in the external material templates.
21077 In particular, pipes and redirection are not readily available.
21078 This has to be so if LyX should remain safe.
21079 If you want to use some of the shell features, you should write a safe
21080 script to do this in a controlled manner, and then invoke the script from
21081 the command string.
21085 \begin_layout Standard
21086 It is possible to design a template that interacts directly with the shell,
21087 but since this would allow a malicious user to execute arbitrary commands
21088 by writing clever filenames and/or parameters, we generally recommend that
21089 you only use safe scripts that work with the
21090 \begin_inset Flex Code
21093 \begin_layout Plain Layout
21099 system call in a controlled manner.
21100 Of course, for use in a controlled environment, it can be tempting to just
21101 fall back to use ordinary shell scripts.
21102 If you do so, be aware that you
21106 provide an easily exploitable security hole in your system.
21107 Of course it stands to reason that such unsafe templates will never be
21108 included in the standard LyX distribution, although we do encourage people
21109 to submit new templates in the open source tradition.
21110 But LyX as shipped from the official distribution channels will never have
21114 \begin_layout Standard
21115 Including external material provides a lot of power, and you have to be
21116 careful not to introduce security hazards with this power.
21117 A subtle error in a single line in an innocent looking script can open
21118 the door to huge security problems.
21119 So if you do not fully understand the issues, we recommend that you consult
21120 a knowledgeable security professional or the LyX development team if you
21121 have any questions about whether a given template is safe or not.
21122 And do this before you use it in an uncontrolled environment.