1 #LyX 2.0.0svn created this file. For more info see http://www.lyx.org/
7 % DO NOT ALTER THIS PREAMBLE!!!
9 % This preamble is designed to ensure that this document prints
10 % out as advertised. If you mess with this preamble,
11 % parts of this document may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 % redefine the \LyX macro for PDF bookmarks
35 \def\LyX{\texorpdfstring{%
36 L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
39 % used for multi-column text
42 \options fleqn,bibliography=totoc,index=totoc,BCOR7.5mm,titlepage,captions=tableheading
43 \use_default_options false
47 \maintain_unincluded_children false
50 InsetLayout CharStyle:MenuItem
59 \newcommand*{\menuitem}[1]{{\sffamily #1}}
62 # In case we need to do with sans...
63 #InsetLayout CharStyle:Code
68 #\renewcommand{\code}[1]{{\sffamily #1}}
77 \font_typewriter default
78 \font_default_family default
79 \use_non_tex_fonts false
86 \default_output_format default
88 \bibtex_command default
89 \index_command default
93 \pdf_title "LyX Configuration Manual"
94 \pdf_author "LyX Team"
95 \pdf_subject "LyX-documentation Customization"
96 \pdf_keywords "LyX, documentation, customization"
98 \pdf_bookmarksnumbered true
99 \pdf_bookmarksopen true
100 \pdf_bookmarksopenlevel 1
101 \pdf_breaklinks false
105 \pdf_pdfusetitle false
106 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
116 \paperorientation portrait
130 \paragraph_separation indent
131 \paragraph_indentation default
132 \quotes_language english
135 \paperpagestyle headings
136 \tracking_changes true
137 \output_changes false
140 \author 34634807 "Jean-Pierre"
146 Customizing LyX: Features for the Advanced User
154 \begin_layout Plain Layout
156 If you have comments or error corrections, please send them to the LyX Documenta
158 \begin_inset CommandInset href
160 target "lyx-docs@lists.lyx.org"
167 \begin_inset Quotes eld
171 \begin_inset Quotes erd
174 in the subject header, and please cc the current maintainer of this file,
175 Richard Heck <rgheck@comcast.net>.
181 \begin_inset Newline newline
185 \begin_inset Newline newline
191 \begin_layout Standard
192 \begin_inset CommandInset toc
193 LatexCommand tableofcontents
200 \begin_layout Standard
201 \begin_inset Note Note
204 \begin_layout Plain Layout
205 Please use change tracking when modifying this document.
206 This makes it easier for our translators to recognize things that have
207 been changed, and it helps the maintainer keep up-to-date with what's been
216 \begin_layout Chapter
220 \begin_layout Standard
221 This manual covers the customization features present in LyX.
222 In it, we discuss issues like keyboard shortcuts, screen previewing options,
223 printer options, sending commands to LyX via the LyX Server, internationalizati
224 on, installing new LaTeX classes and LyX layouts, etc.
225 We can't possibly hope to touch on everything you can change—our developers
226 add new features faster than we can document them—but we will explain the
227 most common customizations and hopefully point you in the right direction
228 for some of the more obscure ones.
231 \begin_layout Standard
232 \begin_inset Branch OutDated
235 \begin_layout Standard
236 Information from previous versions of this document that now seems to be
237 outdated is contained in the OutDated branch of this document.
238 By default, this information will not appear in the LaTeX output.
246 \begin_layout Chapter
247 LyX configuration files
250 \begin_layout Standard
251 This chapter aims to help you to find your way through the LyX configuration
253 Before continuing to read this chapter, you should find out where your
254 LyX library and user directories are by using
255 \begin_inset Flex MenuItem
258 \begin_layout Plain Layout
259 Help\SpecialChar \menuseparator
270 The library directory is the place where LyX places its system-wide configurati
271 on files; the user directory is where you can place your modified versions.
272 We will call the former
273 \begin_inset Flex Code
276 \begin_layout Plain Layout
283 \begin_inset Flex MenuItem
286 \begin_layout Plain Layout
292 in the remainder of this document.
296 \begin_layout Section
298 \begin_inset Flex Code
301 \begin_layout Plain Layout
310 \begin_layout Standard
311 \begin_inset Flex Code
314 \begin_layout Plain Layout
320 and its sub-directories contain a number of files and that can be used
321 to customize LyX's behavior.
322 You can change many of these files from within LyX itself through the
323 \begin_inset Flex MenuItem
326 \begin_layout Plain Layout
327 Tools\SpecialChar \menuseparator
334 Most customization that you will want to do in LyX is possible through
336 However, many other inner aspects of LyX can be customized by modifying
338 \begin_inset Flex Code
341 \begin_layout Plain Layout
348 These files fall in different categories, described in the following subsection
352 \begin_layout Subsection
353 Automatically generated files
356 \begin_layout Standard
357 The files, which are to be found in
358 \begin_inset Flex MenuItem
361 \begin_layout Plain Layout
367 , are generated when you configure LyX.
368 They contain various default values that are guessed by inspection.
369 In general, it is not a good idea to modify them, since they might be overwritt
373 \begin_layout Labeling
374 \labelwidthstring 00.00.0000
375 \begin_inset Flex Code
378 \begin_layout Plain Layout
384 contains defaults for various commands.
387 \begin_layout Labeling
388 \labelwidthstring 00.00.0000
389 \begin_inset Flex Code
392 \begin_layout Plain Layout
398 contains the list of packages that have been recognized by LyX.
399 It is currently unused by the LyX program itself, but the information extracted
400 , and more, is made available with
401 \begin_inset Flex MenuItem
404 \begin_layout Plain Layout
405 Help\SpecialChar \menuseparator
418 \begin_layout Labeling
419 \labelwidthstring 00.00.0000
420 \begin_inset Flex Code
423 \begin_layout Plain Layout
429 the list of text classes that have been found in your
430 \begin_inset Flex Code
433 \begin_layout Plain Layout
439 directories, along with the associated LaTeX document class and their descripti
443 \begin_layout Labeling
444 \labelwidthstring 00.00.0000
445 \begin_inset Flex Code
448 \begin_layout Plain Layout
454 the list of layout modules found in your
455 \begin_inset Flex Code
458 \begin_layout Plain Layout
467 \begin_layout Labeling
468 \labelwidthstring 00.00.0000
469 \begin_inset Flex Code
472 \begin_layout Plain Layout
478 lists of various sorts of LaTeX-related files found on your system
481 \begin_layout Labeling
482 \labelwidthstring 00.00.0000
483 \begin_inset Flex Code
486 \begin_layout Plain Layout
492 is automatically generated during configuration from the file
493 \begin_inset Flex Code
496 \begin_layout Plain Layout
503 It contains information on your LaTeX configuration.
506 \begin_layout Subsection
510 \begin_layout Standard
511 These directories are duplicated between
512 \begin_inset Flex Code
515 \begin_layout Plain Layout
522 \begin_inset Flex Code
525 \begin_layout Plain Layout
532 If a particular files exists in both places, the one in
533 \begin_inset Flex Code
536 \begin_layout Plain Layout
545 \begin_layout Labeling
546 \labelwidthstring 00.00.0000
547 \begin_inset Flex Code
550 \begin_layout Plain Layout
556 this directory contains files with the extension
557 \begin_inset Flex Code
560 \begin_layout Plain Layout
566 that define the keybindings used in LyX.
567 If there exists an internationalized version of the bind file named
568 \begin_inset Flex Code
571 \begin_layout Plain Layout
577 , that will be used first.
580 \begin_layout Labeling
581 \labelwidthstring 00.00.0000
582 \begin_inset Flex Code
585 \begin_layout Plain Layout
591 contains graphics files that can be included in documents.
595 \begin_layout Labeling
596 \labelwidthstring 00.00.0000
597 \begin_inset Flex Code
600 \begin_layout Plain Layout
606 contains LyX documentation files (including the one you are currently reading).
608 \begin_inset Flex Code
611 \begin_layout Plain Layout
617 deserves special attention, as noted above.
618 The internationalized help docs are in subdirectories
619 \begin_inset Flex Code
622 \begin_layout Plain Layout
629 \begin_inset Quotes eld
633 \begin_inset Quotes erd
636 is the ISO language code.
642 \begin_inset CommandInset ref
644 reference "cha:Internationalizing-LyX"
651 \begin_layout Labeling
652 \labelwidthstring 00.00.0000
653 \begin_inset Flex Code
656 \begin_layout Plain Layout
662 contains example files that explain how to use some features.
663 In the file browser, press the
664 \begin_inset Flex MenuItem
667 \begin_layout Plain Layout
676 \begin_layout Labeling
677 \labelwidthstring 00.00.0000
678 \begin_inset Flex Code
681 \begin_layout Plain Layout
687 contains image files that are used by the
688 \begin_inset Flex MenuItem
691 \begin_layout Plain Layout
698 In addition, it also contains the individual icons used in the toolbar
699 and the banners that can be shown when LyX is launched.
702 \begin_layout Labeling
703 \labelwidthstring 00.00.0000
704 \begin_inset Flex Code
707 \begin_layout Plain Layout
713 contains keyboard keymapping files.
719 \begin_inset CommandInset ref
721 reference "sec:International-Keymap-Stuff"
728 \begin_layout Labeling
729 \labelwidthstring 00.00.0000
730 \begin_inset Flex Code
733 \begin_layout Plain Layout
739 contains the text class and module files described in Chapter
744 \begin_inset CommandInset ref
746 reference "cha:Installing-New-Document"
753 \begin_layout Labeling
754 \labelwidthstring 00.00.0000
755 \begin_inset Flex Code
758 \begin_layout Plain Layout
765 \begin_inset Flex Code
768 \begin_layout Plain Layout
774 Python scripts used to convert between LyX versions.
775 These can be run from the command line if, say, you want to batch-convert
779 \begin_layout Labeling
780 \labelwidthstring 00.00.0000
781 \begin_inset Flex Code
784 \begin_layout Plain Layout
790 contains some files that demonstrate the capabilities of the
791 \begin_inset Flex MenuItem
794 \begin_layout Plain Layout
805 Also contains some scripts used by LyX itself.
808 \begin_layout Labeling
809 \labelwidthstring 00.00.0000
810 \begin_inset Flex Code
813 \begin_layout Plain Layout
819 contains the standard LyX template files described in Chapter
824 \begin_inset CommandInset ref
826 reference "sub:Creating-Templates"
833 \begin_layout Labeling
834 \labelwidthstring 00.00.0000
835 \begin_inset Flex Code
838 \begin_layout Plain Layout
844 contains files with the extension
845 \begin_inset Flex Code
848 \begin_layout Plain Layout
854 that define the user interface to LyX.
855 That is, the files define which items appear in which menus and the items
856 appearing on the toolbar.
859 \begin_layout Subsection
860 Files you don't want to modify
863 \begin_layout Standard
864 These files are used internally by LyX and you generally do not need to
865 modify them unless you are a developer.
868 \begin_layout Labeling
869 \labelwidthstring 00.00.0000
870 \begin_inset Flex Code
873 \begin_layout Plain Layout
879 this file contains the list of LyX developers.
880 The contents are displayed with the menu entry
881 \begin_inset Flex MenuItem
884 \begin_layout Plain Layout
885 Help\SpecialChar \menuseparator
898 \begin_layout Labeling
899 \labelwidthstring 00.00.0000
900 \begin_inset Flex Code
903 \begin_layout Plain Layout
909 this is a LaTeX script used during the configuration process.
913 \begin_layout Labeling
914 \labelwidthstring 00.00.0000
915 \begin_inset Flex Code
918 \begin_layout Plain Layout
924 this is the script that is used to re-configure LyX.
925 It creates configuration files in the directory it was run from.
928 \begin_layout Subsection
929 Other files needing a line or two...
932 \begin_layout Labeling
933 \labelwidthstring 00.00.0000
934 \begin_inset Flex Code
937 \begin_layout Plain Layout
943 this contains tables describing how different character encodings can be
947 \begin_layout Labeling
948 \labelwidthstring 00.00.0000
949 \begin_inset Flex Code
952 \begin_layout Plain Layout
958 this file contains the templates available to the new
959 \begin_inset Flex MenuItem
962 \begin_layout Plain Layout
975 \begin_layout Labeling
976 \labelwidthstring 00.00.0000
977 \begin_inset Flex Code
980 \begin_layout Plain Layout
986 this file contains a list of all the languages currently supported by LyX.
989 \begin_layout Section
990 Your local configuration directory
993 \begin_layout Standard
994 Even if you are using LyX as an unprivileged user, you might want to change
995 LyX configuration for your own use.
997 \begin_inset Flex Code
1000 \begin_layout Plain Layout
1006 directory contains all your personal configuration files.
1007 This is the directory described as
1008 \begin_inset Quotes eld
1012 \begin_inset Quotes erd
1016 \begin_inset Flex MenuItem
1019 \begin_layout Plain Layout
1020 Help\SpecialChar \menuseparator
1022 \begin_inset space ~
1031 This directory is used as a mirror of
1032 \begin_inset Flex Code
1035 \begin_layout Plain Layout
1041 , which means that every file in
1042 \begin_inset Flex Code
1045 \begin_layout Plain Layout
1051 is a replacement for the corresponding file in
1052 \begin_inset Flex Code
1055 \begin_layout Plain Layout
1062 Any configuration file described in the above sections can be placed either
1063 in the system-wide directory, in which case it will affect all users, or
1064 in your local directory for your own use.
1067 \begin_layout Standard
1068 To make things clearer, let's provide a few examples:
1071 \begin_layout Itemize
1072 The preferences set in the
1073 \begin_inset Flex MenuItem
1076 \begin_layout Plain Layout
1077 Tools\SpecialChar \menuseparator
1083 dialog are saved to a file
1084 \begin_inset Flex Code
1087 \begin_layout Plain Layout
1094 \begin_inset Flex Code
1097 \begin_layout Plain Layout
1106 \begin_layout Itemize
1107 When you reconfigure using
1108 \begin_inset Flex MenuItem
1111 \begin_layout Plain Layout
1112 Tools\SpecialChar \menuseparator
1119 \begin_inset Flex Code
1122 \begin_layout Plain Layout
1128 script, and the resulting files are written in your local configuration
1130 This means that any additional text class file that you might have added
1132 \begin_inset Flex Code
1135 \begin_layout Plain Layout
1141 will be added to the list of classes in the
1142 \begin_inset Flex MenuItem
1145 \begin_layout Plain Layout
1146 Document\SpecialChar \menuseparator
1155 \begin_layout Itemize
1156 If you get some updated documentation from LyX ftp site and cannot install
1157 it because you do not have sysadmin rights on your system, you can just
1159 \begin_inset Flex Code
1162 \begin_layout Plain Layout
1168 and the items in the
1169 \begin_inset Flex MenuItem
1172 \begin_layout Plain Layout
1178 menu will open them!
1181 \begin_layout Section
1182 Running LyX with multiple configurations
1185 \begin_layout Standard
1186 The configuration freedom of the local configuration directory may not suffice
1187 if you want to have more than one configuration at your disposal.
1188 For example, you may want to be use different key bindings or printer settings
1190 You can achieve this by having several such directories.
1191 You then specify which directory to use at run-time.
1194 \begin_layout Standard
1195 Invoking LyX with the command line switch
1196 \begin_inset Flex Code
1199 \begin_layout Plain Layout
1209 instructs the program to read the configuration from that directory, and
1210 not from the default directory.
1211 (You can determine the default directory by running LyX without the
1212 \begin_inset Flex Code
1215 \begin_layout Plain Layout
1221 switch.) If the specified directory does not exist, LyX offers to create
1222 it for you, just like it does for the default directory on the first time
1223 you run the program.
1224 You can modify the configuration options in this additional user directory
1225 exactly as you would for the default directory.
1226 These directories are completely independent (but read on).
1227 Note that setting the environment variable
1228 \begin_inset Flex Code
1231 \begin_layout Plain Layout
1237 to some value has exactly the same effect.
1240 \begin_layout Standard
1241 Having several configurations also requires more maintenance: if you want
1242 to add a new layout to
1243 \begin_inset Flex Code
1246 \begin_layout Plain Layout
1252 which you want available from all your configurations, you must add it
1253 to each directory separately.
1254 You can avoid this with the following trick: after LyX creates the additional
1255 directory, most of the subdirectories (see above) are empty.
1256 If you want the new configuration to mirror an existing one, replace the
1257 empty subdirectory with a symbolic link to the matching subdirectory in
1258 the existing configuration.
1260 \begin_inset Flex Code
1263 \begin_layout Plain Layout
1269 subdirectory, however, since it contains a file written by the configuration
1270 script (also accessible through
1271 \begin_inset Flex MenuItem
1274 \begin_layout Plain Layout
1275 Tools\SpecialChar \menuseparator
1281 ) which is configuration-specific.
1284 \begin_layout Chapter
1285 The Preferences dialog
1288 \begin_layout Standard
1289 All options of the preferences dialog are described in the Appendix
1291 The Preferences Dialog
1298 For some options you might find here more details.
1301 \begin_layout Section
1303 \begin_inset CommandInset label
1312 \begin_layout Standard
1313 The first step is to define your file formats if they are not already defined.
1315 \begin_inset Flex MenuItem
1318 \begin_layout Plain Layout
1319 Tools\SpecialChar \menuseparator
1327 \begin_inset Flex MenuItem
1330 \begin_layout Plain Layout
1331 File Handling\SpecialChar \menuseparator
1338 \begin_inset Flex MenuItem
1341 \begin_layout Plain Layout
1342 New\SpecialChar \ldots{}
1348 button to define your new format.
1350 \begin_inset Flex MenuItem
1353 \begin_layout Plain Layout
1359 field contains the name used to identify the format in the GUI.
1361 \begin_inset Flex MenuItem
1364 \begin_layout Plain Layout
1370 is used to identify the format internally.
1371 You will also need to enter a file extension.
1372 These are all required.
1374 \begin_inset Flex MenuItem
1377 \begin_layout Plain Layout
1383 field is used to provide a keyboard shortcut on the menus.
1384 (For example, pressing
1385 \begin_inset Flex MenuItem
1388 \begin_layout Plain Layout
1395 \begin_inset Flex MenuItem
1398 \begin_layout Plain Layout
1399 View\SpecialChar \menuseparator
1400 View (Other Formats)\SpecialChar \menuseparator
1409 \begin_layout Standard
1411 \begin_inset Flex MenuItem
1414 \begin_layout Plain Layout
1421 \begin_inset Flex MenuItem
1424 \begin_layout Plain Layout
1431 For example, you might want to use
1432 \begin_inset Flex MenuItem
1435 \begin_layout Plain Layout
1441 to view PostScript files.
1442 You can enter the command needed to start the program in the corresponding
1444 In defining this command, you can use the four variables listed in the
1446 The viewer is launched when you view an image in LyX or use the
1447 \begin_inset Flex MenuItem
1450 \begin_layout Plain Layout
1457 The editor is for example launched when you right-click on an image and
1459 \begin_inset Flex MenuItem
1462 \begin_layout Plain Layout
1468 in the appearing context menu.
1471 \begin_layout Standard
1473 \begin_inset Flex MenuItem
1476 \begin_layout Plain Layout
1482 option tells LyX that a format is suitable for document export.
1483 If this is set and if a suitable conversion route exists (see sec.
1484 \begin_inset space \thinspace{}
1488 \begin_inset CommandInset ref
1490 reference "sec:Converters"
1494 ), the format will appear in the
1495 \begin_inset Flex MenuItem
1498 \begin_layout Plain Layout
1499 File\SpecialChar \menuseparator
1506 The format will also appear in the
1507 \begin_inset Flex MenuItem
1510 \begin_layout Plain Layout
1516 menu if a viewer is specified for the format.
1517 Pure image formats, such as
1518 \begin_inset Flex Code
1521 \begin_layout Plain Layout
1527 , should not use this option.
1528 Formats that can both represent vector graphics and documents like
1529 \begin_inset Flex Code
1532 \begin_layout Plain Layout
1541 \begin_layout Standard
1543 \begin_inset Flex MenuItem
1546 \begin_layout Plain Layout
1547 Vector graphics format
1552 tells LyX that a format can contain vector graphics.
1553 This information is used to determine the target format of included graphics
1555 \begin_inset Flex MenuItem
1558 \begin_layout Plain Layout
1565 Included graphics may need to be converted to either
1566 \begin_inset Flex MenuItem
1569 \begin_layout Plain Layout
1576 \begin_inset Flex MenuItem
1579 \begin_layout Plain Layout
1586 \begin_inset Flex MenuItem
1589 \begin_layout Plain Layout
1596 \begin_inset Flex MenuItem
1599 \begin_layout Plain Layout
1605 cannot handle other image formats.
1606 If an included graphic is not already in
1607 \begin_inset Flex MenuItem
1610 \begin_layout Plain Layout
1617 \begin_inset Flex MenuItem
1620 \begin_layout Plain Layout
1627 \begin_inset Flex MenuItem
1630 \begin_layout Plain Layout
1636 format, it is converted to
1637 \begin_inset Flex MenuItem
1640 \begin_layout Plain Layout
1646 if the vector format option is set, and otherwise to
1647 \begin_inset Flex MenuItem
1650 \begin_layout Plain Layout
1659 \begin_layout Section
1663 \begin_layout Standard
1664 Since all conversions from one format to another take place in LyX's temporary
1665 directory, it is sometimes necessary to modify a file before copying it
1666 to the temporary directory in order that the conversion may be performed.
1670 \begin_layout Plain Layout
1671 For example, the file may refer to other files—images, for example—using
1672 relative file names, and these may become invalid when the file is copied
1673 to the temporary directory.
1678 This is done by a Copier: It copies a file to (or from) the temporary directory
1679 and may modify it in the process.
1682 \begin_layout Standard
1683 The definitions of the copiers may use four variables:
1686 \begin_layout Labeling
1687 \labelwidthstring 00.00.0000
1688 \begin_inset Flex Code
1691 \begin_layout Plain Layout
1697 The LyX system directory (e.
1698 \begin_inset space \thinspace{}
1702 \begin_inset space \space{}
1706 \begin_inset Flex MenuItem
1709 \begin_layout Plain Layout
1718 \begin_layout Labeling
1719 \labelwidthstring 00.00.0000
1720 \begin_inset Flex Code
1723 \begin_layout Plain Layout
1732 \begin_layout Labeling
1733 \labelwidthstring 00.00.0000
1734 \begin_inset Flex Code
1737 \begin_layout Plain Layout
1746 \begin_layout Labeling
1747 \labelwidthstring 00.00.0000
1748 \begin_inset Flex Code
1751 \begin_layout Plain Layout
1760 \begin_layout Standard
1761 The latter should be the filename as it would be used in a LaTeX's
1768 It is relevant only when exporting files suitable for such inclusion.
1771 \begin_layout Standard
1772 Copiers can be used to do almost anything with output files.
1773 For example, suppose you want generated pdf files to be copied to a special
1775 \begin_inset Flex Code
1778 \begin_layout Plain Layout
1785 Then you could write a shell script such as this one:
1788 \begin_layout Standard
1789 \begin_inset listings
1793 \begin_layout Plain Layout
1798 \begin_layout Plain Layout
1803 \begin_layout Plain Layout
1805 TOFILE=`basename $2`
1808 \begin_layout Plain Layout
1810 cp $FROMFILE /home/you/pdf/$TOFILE
1815 Save it in your local LyX directory—say,
1816 \begin_inset Flex Code
1819 \begin_layout Plain Layout
1820 /home/you/.lyx/scripts/pdfcopier.sh
1825 —and make it executable, if you need to do so on your platform.
1827 \begin_inset Flex MenuItem
1830 \begin_layout Plain Layout
1831 Tools\SpecialChar \menuseparator
1837 dialog, select under
1838 \begin_inset Flex MenuItem
1841 \begin_layout Plain Layout
1842 File Handling\SpecialChar \menuseparator
1849 \begin_inset Flex MenuItem
1852 \begin_layout Plain Layout
1858 format—or one of the other pdf formats—and enter
1859 \begin_inset Flex Code
1862 \begin_layout Plain Layout
1863 pdfcopier.sh $$i $$o
1869 \begin_inset Flex MenuItem
1872 \begin_layout Plain Layout
1882 \begin_layout Standard
1883 Copiers are used by LyX in various of its own conversions.
1884 For example, if appropriate programs are found, LyX will automatically
1885 install copiers for the
1886 \begin_inset Flex MenuItem
1889 \begin_layout Plain Layout
1896 \begin_inset Flex MenuItem
1899 \begin_layout Plain Layout
1901 \begin_inset space ~
1910 When these formats are exported, the copier sees that not just the main
1911 HTML file but various associated files (style files, images, etc.) are also
1913 All these files are written to a subdirectory of the directory in which
1914 the original LyX file was found.
1918 \begin_layout Plain Layout
1919 This copier can be customized.
1921 \begin_inset Quotes eld
1925 \begin_inset Quotes erd
1928 argument takes a comma-separated list of extensions to be copied; if it
1929 is omitted, all files will be copied.
1931 \begin_inset Quotes eld
1935 \begin_inset Quotes erd
1938 argument determines the extension added to the generated directory.
1940 \begin_inset Quotes eld
1944 \begin_inset Flex MenuItem
1947 \begin_layout Plain Layout
1954 \begin_inset Quotes erd
1957 , so HTML generated from
1958 \begin_inset Flex MenuItem
1961 \begin_layout Plain Layout
1962 /path/to/filename.lyx
1968 \begin_inset Flex MenuItem
1971 \begin_layout Plain Layout
1972 /path/to/filename.html.LyXconv
1986 \begin_layout Section
1988 \begin_inset CommandInset label
1990 name "sec:Converters"
1997 \begin_layout Standard
1998 You can define your own Converters to convert files between different formats.
2000 \begin_inset Flex MenuItem
2003 \begin_layout Plain Layout
2004 Tools\SpecialChar \menuseparator
2005 Preferences\SpecialChar \menuseparator
2006 File Handling\SpecialChar \menuseparator
2015 \begin_layout Standard
2016 To define a new converter, select the
2017 \begin_inset Flex MenuItem
2020 \begin_layout Plain Layout
2022 \begin_inset space ~
2031 \begin_inset Flex MenuItem
2034 \begin_layout Plain Layout
2036 \begin_inset space ~
2044 from the drop-down lists, enter the command needed for the conversion,
2046 \begin_inset Flex MenuItem
2049 \begin_layout Plain Layout
2056 Several variables can be used in the definition of converters:
2059 \begin_layout Labeling
2060 \labelwidthstring 00.00.0000
2061 \begin_inset Flex Code
2064 \begin_layout Plain Layout
2070 The LyX system directory
2073 \begin_layout Labeling
2074 \labelwidthstring 00.00.0000
2075 \begin_inset Flex Code
2078 \begin_layout Plain Layout
2087 \begin_layout Labeling
2088 \labelwidthstring 00.00.0000
2089 \begin_inset Flex Code
2092 \begin_layout Plain Layout
2101 \begin_layout Labeling
2102 \labelwidthstring 00.00.0000
2103 \begin_inset Flex Code
2106 \begin_layout Plain Layout
2112 The base filename of the input file (i.
2113 \begin_inset space \thinspace{}
2116 g., without the extension)
2119 \begin_layout Labeling
2120 \labelwidthstring 00.00.0000
2121 \begin_inset Flex Code
2124 \begin_layout Plain Layout
2130 The path to the input file
2133 \begin_layout Labeling
2134 \labelwidthstring 00.00.0000
2135 \begin_inset Flex Code
2138 \begin_layout Plain Layout
2144 The path to the original input file (this is different from $$p when a
2145 chain of converters is called)
2148 \begin_layout Labeling
2149 \labelwidthstring 00.00.0000
2150 \begin_inset Flex Code
2153 \begin_layout Plain Layout
2159 The iconv name for the encoding of the document.
2162 \begin_layout Standard
2164 \begin_inset Flex MenuItem
2167 \begin_layout Plain Layout
2169 \begin_inset space ~
2177 field you can enter the following flags, separated by commas:
2180 \begin_layout Labeling
2181 \labelwidthstring 00.00.0000
2182 \begin_inset Flex Code
2185 \begin_layout Plain Layout
2191 This converter runs some form of LaTeX.
2192 This will make LyX's LaTeX error logs available.
2195 \begin_layout Labeling
2196 \labelwidthstring 00.00.0000
2197 \begin_inset Flex Code
2200 \begin_layout Plain Layout
2207 \begin_inset Flex MenuItem
2210 \begin_layout Plain Layout
2216 file for the conversion.
2219 \begin_layout Labeling
2220 \labelwidthstring 00.00.0000
2221 \begin_inset Flex Code
2224 \begin_layout Plain Layout
2233 \begin_layout Standard
2234 The following three flags are not really flags at all because they take
2236 \begin_inset Flex MenuItem
2239 \begin_layout Plain Layout
2241 \begin_inset space ~
2245 \begin_inset space ~
2256 \begin_layout Labeling
2257 \labelwidthstring 00.00.0000
2258 \begin_inset Flex Code
2261 \begin_layout Plain Layout
2267 If set, the converter's standard error will be redirected to a file
2268 \begin_inset Flex Code
2271 \begin_layout Plain Layout
2277 , and the script given as argument will be run as:
2278 \begin_inset Flex Code
2281 \begin_layout Plain Layout
2282 script < infile.out > infile.log
2288 The argument may contain
2289 \begin_inset Flex Code
2292 \begin_layout Plain Layout
2301 \begin_layout Labeling
2302 \labelwidthstring 00.00.0000
2303 \begin_inset Flex Code
2306 \begin_layout Plain Layout
2312 The name of the directory in which the converter will dump the generated
2314 LyX will not create this directory, and it does not copy anything into
2315 it, though it will copy this directory to the destination.
2316 The argument may contain
2317 \begin_inset Flex Code
2320 \begin_layout Plain Layout
2326 , which will be replaced by the base name of the input and output files,
2327 respectively, when the directory is copied.
2328 \begin_inset Newline newline
2331 Note that resultdir and usetempdir make no sense together.
2332 The latter will be ignored if the former is given.
2335 \begin_layout Labeling
2336 \labelwidthstring 00.00.0000
2337 \begin_inset Flex Code
2340 \begin_layout Plain Layout
2346 Determines the output file name and may, contain
2347 \begin_inset Flex Code
2350 \begin_layout Plain Layout
2357 Sensible only with resultdir and optional even then; if not given, it defaults
2361 \begin_layout Standard
2362 None of these last three are presently used in any of the converters that
2363 are installed with LyX.
2367 \begin_layout Standard
2368 You do not have to define converters for all formats between which you want
2370 For example, you will note that there is no `LyX to PostScript' converter,
2371 but LyX will export PostScript.
2372 It does so by first creating a LaTeX file (no converter needs to be defined
2373 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2374 and finally converting the resulting DVI file to PostScript.
2375 LyX finds such `chains' of converters automatically, and it will always
2376 choose the shortest possible chain.
2377 You can, though, still define multiple conversion methods between file
2379 For example, the standard LyX configuration provides three ways to convert
2380 LaTeX to PDF: Directly, using
2381 \begin_inset Flex MenuItem
2384 \begin_layout Plain Layout
2390 ; via (DVI and) PostScript, using
2391 \begin_inset Flex MenuItem
2394 \begin_layout Plain Layout
2401 \begin_inset Flex MenuItem
2404 \begin_layout Plain Layout
2411 To define such alternate chains, you must define multiple target `file
2412 formats', as described in section
2413 \begin_inset CommandInset ref
2415 reference "sec:Formats"
2420 For example, in the standard configuration, the formats named
2421 \begin_inset Flex MenuItem
2424 \begin_layout Plain Layout
2431 \begin_inset Flex MenuItem
2434 \begin_layout Plain Layout
2441 \begin_inset Flex MenuItem
2444 \begin_layout Plain Layout
2450 are defined, all of which share the extension
2451 \begin_inset Flex MenuItem
2454 \begin_layout Plain Layout
2460 , and which correspond to the conversion methods just mentioned.
2463 \begin_layout Chapter
2464 Internationalizing LyX
2465 \begin_inset CommandInset label
2467 name "cha:Internationalizing-LyX"
2474 \begin_layout Standard
2475 LyX supports using a translated interface.
2476 Last time we checked, LyX provided text in thirty languages.
2477 The language of choice is called your
2482 (For further reading on locale settings, see also the documentation for
2483 locale that comes with your operating system.
2484 For Linux, the manual page for
2485 \begin_inset Flex Code
2488 \begin_layout Plain Layout
2494 could be a good place to start).
2497 \begin_layout Standard
2498 Notice that these translations will work, but do contain a few flaws.
2499 In particular, all dialogs have been designed with the English text in
2500 mind, which means that some of the translated text will be too large to
2501 fit within the space allocated.
2502 This is only a display problem and will not cause any harm.
2503 Also, you will find that some of the translations do not define shortcut
2504 keys for everything.
2505 Sometimes, there are simply not enough free letters to do it.
2506 Other times, the translator just hasn't got around to doing it yet.
2507 Our localization team, which you may wish to join,
2511 \begin_layout Plain Layout
2512 If you are a fluent speaker of a language other than English, joining these
2513 teams is a great way to give back to the LyX community!
2518 will of course try to fix these shortcomings in future versions of LyX.
2521 \begin_layout Section
2525 \begin_layout Subsection
2526 Translating the graphical user interface (text messages).
2529 \begin_layout Standard
2531 \begin_inset Flex Code
2534 \begin_layout Plain Layout
2540 library to handle the internationalization of the interface.
2541 To have LyX speak your favorite language in all menus and dialogs, you
2543 \begin_inset Flex Code
2546 \begin_layout Plain Layout
2552 -file for that language.
2553 When this is available, you'll have to generate a
2554 \begin_inset Flex Code
2557 \begin_layout Plain Layout
2563 -file from it and install the
2564 \begin_inset Flex Code
2567 \begin_layout Plain Layout
2574 The process of doing all of this is explained in the documentation for
2576 \begin_inset Flex Code
2579 \begin_layout Plain Layout
2586 It is possible to do this just for yourself, but if you're going to do
2587 it, you might as well share the results of your labors with the rest of
2589 Send a message to the LyX developers' list for more information about how
2593 \begin_layout Standard
2594 In short, this is what you should do (xx denotes the language code):
2597 \begin_layout Itemize
2598 Check out the LyX source code.
2600 \begin_inset CommandInset href
2602 name "information on the web"
2603 target "http://www.lyx.org/HowToUseSVN"
2610 \begin_layout Itemize
2612 \begin_inset Flex Code
2615 \begin_layout Plain Layout
2621 to the folder of the
2622 \begin_inset Flex Code
2625 \begin_layout Plain Layout
2633 \begin_inset Flex Code
2636 \begin_layout Plain Layout
2644 \begin_inset Flex Code
2647 \begin_layout Plain Layout
2653 doesn't exist anywhere, it can be remade with the console command
2654 \begin_inset Flex Code
2657 \begin_layout Plain Layout
2663 in that directory, or you can use an existing po-file for some other language
2667 \begin_layout Itemize
2669 \begin_inset Flex Code
2672 \begin_layout Plain Layout
2682 \begin_layout Plain Layout
2683 This is just a text file, so it can be edited in any text editor.
2684 But there are also specialized programs that support such editing, such
2689 (for all platforms) or
2698 contains a `mode' for editing
2699 \begin_inset Flex Code
2702 \begin_layout Plain Layout
2713 For some menu- and widget-labels, there are also shortcut keys that should
2715 Those keys are marked after a `|', and should be translated according to
2716 the words and phrases of the language.
2717 You should also fill also out the information at the beginning of the new
2719 \begin_inset Flex Code
2722 \begin_layout Plain Layout
2728 -file with your email-address, etc., so people know where to reach you with
2729 suggestions and entertaining flames.
2732 \begin_layout Standard
2733 If you are just doing this on your own, then:
2736 \begin_layout Itemize
2738 \begin_inset Flex Code
2741 \begin_layout Plain Layout
2748 This can be done with
2749 \begin_inset Flex Code
2752 \begin_layout Plain Layout
2753 msgfmt -o xx.mo < xx.po
2761 \begin_layout Itemize
2763 \begin_inset Flex Code
2766 \begin_layout Plain Layout
2772 -file to your locale-tree, at the correct directory for application messages
2777 xx, and under the name
2778 \begin_inset Flex Code
2781 \begin_layout Plain Layout
2788 \begin_inset space \thinspace{}
2792 \begin_inset space \space{}
2796 \begin_inset Flex Code
2799 \begin_layout Plain Layout
2800 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2810 \begin_layout Standard
2811 As said, however, it would be best if the new
2812 \begin_inset Flex Code
2815 \begin_layout Plain Layout
2821 -file could be added to the LyX distribution, so others can use it.
2822 Adding it involves making additional changes to LyX.
2823 So send an email to the developers' mailing list if you're interested in
2827 \begin_layout Subsubsection
2831 \begin_layout Standard
2832 Sometimes it turns out that one English message needs to be translated into
2833 different messages in the target language.
2834 One example is the message
2835 \begin_inset Flex Code
2838 \begin_layout Plain Layout
2844 which has the German translation
2852 , depending upon exactly what the English
2853 \begin_inset Quotes eld
2857 \begin_inset Quotes erd
2862 \begin_inset Flex Code
2865 \begin_layout Plain Layout
2871 does not handle such ambiguous translations.
2872 Therefore you have to add some context information to the message: Instead
2874 \begin_inset Flex Code
2877 \begin_layout Plain Layout
2884 \begin_inset Flex Code
2887 \begin_layout Plain Layout
2888 To[[as in 'From format x to format y']]
2894 \begin_inset Flex Code
2897 \begin_layout Plain Layout
2898 To[[as in 'From page x to page y']].
2903 Now the two occurrences of
2904 \begin_inset Flex Code
2907 \begin_layout Plain Layout
2914 \begin_inset Flex Code
2917 \begin_layout Plain Layout
2923 and can be translated correctly to
2934 \begin_layout Standard
2935 Of course the context information needs to be stripped off the original
2936 message when no translation is used.
2937 Therefore you have to put it in double square brackets at the end of the
2938 message (see the example above).
2939 The translation mechanism of LyX ensures that everything in double square
2940 brackets at the end of messages is removed before displaying the message.
2943 \begin_layout Subsection
2944 Translating the documentation.
2947 \begin_layout Standard
2948 The online documentation (in the
2949 \begin_inset Flex MenuItem
2952 \begin_layout Plain Layout
2958 -menu) can (and should!) be translated.
2959 If there are translated versions of the documentation available
2963 \begin_layout Plain Layout
2964 As of March 2008, at least some of the documents have been translated into
2965 fourteen languages, with the Tutorial available in a few more.
2970 and the locale is set accordingly, these will be used automagically by
2972 LyX looks for translated versions as
2973 \begin_inset Flex Code
2976 \begin_layout Plain Layout
2977 LyXDir/doc/xx/DocName.lyx
2983 \begin_inset Flex Code
2986 \begin_layout Plain Layout
2992 is the code for the language currently in use.
2993 If there are no translated documents, the default English versions will
2995 Note that the translated versions must have the same filenames (
2996 \begin_inset Flex Code
2999 \begin_layout Plain Layout
3005 above) as the original.
3006 If you feel up to translating the documentation (an excellent way to proof-read
3007 the original documentation by the way!), there are a few things you should
3011 \begin_layout Itemize
3012 Check out the documentation translation web page at
3013 \begin_inset CommandInset href
3015 name "http://www.lyx.org/Translation"
3016 target "http://www.lyx.org/Translation"
3021 That way, you can find out which (if any) documents have already been translate
3022 d into your language.
3023 You can also find out who (if anyone) is organizing the effort to translate
3024 the documentation into your language.
3025 If no one is organizing the effort, please let us know that you're interested.
3028 \begin_layout Standard
3029 Once you get to actually translating, here's a few hints for you that may
3033 \begin_layout Itemize
3034 Join the documentation team! There is information on how to do that in
3035 \begin_inset Flex Code
3038 \begin_layout Plain Layout
3045 \begin_inset Flex MenuItem
3048 \begin_layout Plain Layout
3049 Help\SpecialChar \menuseparator
3055 ), which by the way is the first document you should translate.
3058 \begin_layout Itemize
3059 Learn the typographic conventions for the language you are translating to.
3060 Typography is an ancient art and over the centuries, a great variety of
3061 conventions have developed throughout different parts of the world.
3062 Also study the professional terminology amongst typographers in your country.
3063 Inventing your own terminology will only confuse the users.
3066 (Warning! Typography is addictive!)
3069 \begin_layout Itemize
3070 Make a copy of the document.
3071 This will be your working copy.
3072 You can use this as your personal translated help-file by placing it in
3074 \begin_inset Flex Code
3077 \begin_layout Plain Layout
3086 \begin_layout Itemize
3087 Sometimes the original document (from the LyX-team) will be updated.
3088 Use the source viewer at
3089 \begin_inset CommandInset href
3091 name "http://www.lyx.org/trac/timeline"
3092 target "http://www.lyx.org/trac/timeline"
3096 to see what has been changed.
3097 That way you can easily see which parts of the translated document need
3101 \begin_layout Standard
3102 If you ever find an error in the original document, fix it and notify the
3103 rest of the documentation team of the changes! (You didn't forget to join
3104 the documentation team, did you?)
3107 \begin_layout Standard
3108 \begin_inset Branch OutDated
3111 \begin_layout Section
3112 International Keyboard Support
3115 \begin_layout Standard
3118 [Editor's Note: The following section is by
3126 It needs to be fixed to conform to the new Documentation Style sheet and
3127 to make use of the new v1.0 features.
3128 The whole thing also needs to be merged with the section following it.-jw
3129 It may also be badly out of date.-rh (2008)]
3132 \begin_layout Subsection
3133 Defining Own Keymaps: Keymap File Format
3136 \begin_layout Standard
3137 Let's look at a keyboard definition file a little closer.
3138 It is a plain text file defining
3141 \begin_layout Itemize
3142 key-to-key or key-to-string translations
3145 \begin_layout Itemize
3149 \begin_layout Itemize
3150 dead keys exceptions
3153 \begin_layout Standard
3154 To define key-to-key or key-to-string translation, use this command:
3157 \begin_layout Quotation
3158 \begin_inset Flex Code
3161 \begin_layout Plain Layout
3170 \begin_inset Flex Code
3173 \begin_layout Plain Layout
3182 \begin_layout Standard
3184 \begin_inset Flex Code
3187 \begin_layout Plain Layout
3193 is the key to be translated and
3194 \begin_inset Flex Code
3197 \begin_layout Plain Layout
3203 is the string to be inserted into the document.
3204 To define dead keys, use:
3207 \begin_layout Quotation
3208 \begin_inset Flex Code
3211 \begin_layout Plain Layout
3220 \begin_inset Flex Code
3223 \begin_layout Plain Layout
3232 \begin_layout Standard
3234 \begin_inset Flex Code
3237 \begin_layout Plain Layout
3243 is a keyboard key and
3244 \begin_inset Flex Code
3247 \begin_layout Plain Layout
3254 The following dead keys are supported (shortcut name is in parentheses):
3257 \begin_layout Quotation
3261 \begin_inset space \hfill{}
3267 \begin_layout Quotation
3269 \begin_inset space \hfill{}
3275 \begin_layout Quotation
3277 \begin_inset space \hfill{}
3283 \begin_layout Quotation
3285 \begin_inset space \hfill{}
3291 \begin_layout Quotation
3293 \begin_inset space \hfill{}
3299 \begin_layout Quotation
3301 \begin_inset space \hfill{}
3308 \begin_layout Plain Layout
3320 \begin_layout Quotation
3322 \begin_inset space \hfill{}
3328 \begin_layout Quotation
3330 \begin_inset space \hfill{}
3337 \begin_layout Plain Layout
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{}
3395 \begin_layout Plain Layout
3407 \begin_layout Quotation
3409 \begin_inset space \hfill{}
3415 \begin_layout Quotation
3416 hungarian umlaut (hug)
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 Standard
3453 Since in many international keyboards there are exceptions to what some
3454 dead keys should do, you can define them using
3457 \begin_layout Quotation
3458 \begin_inset Flex Code
3461 \begin_layout Plain Layout
3469 deadkey key outstring
3472 \begin_layout Standard
3473 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3477 \begin_layout Quotation
3478 \begin_inset Flex Code
3481 \begin_layout Plain Layout
3494 \begin_layout Standard
3495 to make it work correctly.
3496 Also, you have to define as exceptions dead keys over i and j, to remove
3497 the dot from them before inserting an accent mark.
3498 I will change this when the time comes, but so far I haven't had time.
3501 \begin_layout Standard
3502 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3505 \begin_inset Flex Code
3508 \begin_layout Plain Layout
3514 have different meaning.
3516 \begin_inset Flex Code
3519 \begin_layout Plain Layout
3525 marks comments, quotes start and end LaTeX-style commands.
3526 To enter quote, you'll need to use
3527 \begin_inset Flex Code
3530 \begin_layout Plain Layout
3539 \begin_inset Flex Code
3542 \begin_layout Plain Layout
3549 \begin_inset Flex Code
3552 \begin_layout Plain Layout
3563 \begin_layout Standard
3564 If you make a keyboard description file that works for your language, please
3565 mail it to me, so I can include it in the next keymap distribution.
3568 \begin_layout Standard
3569 More keywords will be supported in keymap configuration file in future,
3573 \begin_layout Itemize
3574 \begin_inset Flex Code
3577 \begin_layout Plain Layout
3588 \begin_inset space \hfill{}
3592 \begin_inset Flex Code
3595 \begin_layout Plain Layout
3604 \begin_layout Itemize
3605 \begin_inset Flex Code
3608 \begin_layout Plain Layout
3619 \begin_inset space \hfill{}
3623 \begin_inset Flex Code
3626 \begin_layout Plain Layout
3632 an external keymap translation program
3635 \begin_layout Standard
3636 Also, it should look into
3637 \begin_inset Flex Code
3640 \begin_layout Plain Layout
3646 file for defaults, too (for example, a
3647 \begin_inset Flex Code
3650 \begin_layout Plain Layout
3658 option to include default keyboard).
3666 \begin_layout Section
3667 International Keymap Stuff
3668 \begin_inset CommandInset label
3670 name "sec:International-Keymap-Stuff"
3677 \begin_layout Standard
3678 \begin_inset Note Note
3681 \begin_layout Plain Layout
3682 In doing the revisions on this document in March 2008, I did not look over
3683 this stuff, as I do not understand it.
3684 It would be good if someone else could do so.
3693 \begin_layout Standard
3694 The next two sections describe the
3695 \begin_inset Flex Code
3698 \begin_layout Plain Layout
3707 \begin_inset Flex Code
3710 \begin_layout Plain Layout
3718 file syntax in detail.
3719 These sections should help you design your own key map if the ones provided
3720 do not meet your needs.
3723 \begin_layout Subsection
3727 \begin_layout Standard
3731 \begin_inset Flex Code
3734 \begin_layout Plain Layout
3740 file maps keystrokes to characters or strings.
3741 As the name suggests, it sets a keyboard mapping.
3743 \begin_inset Flex Code
3746 \begin_layout Plain Layout
3757 \begin_inset Flex Code
3760 \begin_layout Plain Layout
3775 \begin_inset Flex Code
3778 \begin_layout Plain Layout
3791 \begin_inset Flex Code
3794 \begin_layout Plain Layout
3803 \begin_inset Flex Code
3806 \begin_layout Plain Layout
3814 are described in this section.
3817 \begin_layout Labeling
3818 \labelwidthstring 00.00.0000
3819 \begin_inset Flex Code
3822 \begin_layout Plain Layout
3830 Map a character to a string
3833 \begin_layout LyX-Code
3848 \begin_layout Standard
3881 the double-quote (")
3898 must be escaped with a preceding backslash (
3909 \begin_layout Standard
3911 \begin_inset Flex MenuItem
3914 \begin_layout Plain Layout
3922 statement to cause the symbol
3923 \begin_inset Flex MenuItem
3926 \begin_layout Plain Layout
3934 to be output for the keystroke
3935 \begin_inset Flex MenuItem
3938 \begin_layout Plain Layout
3949 \begin_layout LyX-Code
3955 \begin_layout Labeling
3956 \labelwidthstring 00.00.0000
3957 \begin_inset Flex Code
3960 \begin_layout Plain Layout
3968 Specify an accent character
3971 \begin_layout LyX-Code
3980 \begin_layout Standard
3981 This will make the cha
4019 This is the dead key
4023 \begin_layout Plain Layout
4030 refers to a key that does not produce a character by itself, but when followed
4031 with another key, produces the desired accent character.
4032 For example, a German characte
4034 r with an umlaut like
4044 can be produced in this manner.
4053 \begin_layout Standard
4066 and then another key not in
4083 followed by the other, not allowed key, as output.
4087 \begin_inset Flex MenuItem
4090 \begin_layout Plain Layout
4098 cancels a dead key, so if
4109 \begin_inset Flex MenuItem
4112 \begin_layout Plain Layout
4121 , the cursor will not go one position backwards but will instead cancel
4137 might have had on the next keystroke.
4141 \begin_layout Standard
4142 The following example specifies that the character ' is to be an acute accent,
4143 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4146 \begin_layout LyX-Code
4149 kmod ' acute aeiouAEIOU
4152 \begin_layout Labeling
4153 \labelwidthstring 00.00.0000
4154 \begin_inset Flex Code
4157 \begin_layout Plain Layout
4163 Specify an exception to the accent character
4166 \begin_layout LyX-Code
4175 \begin_layout Standard
4176 This defines an exce
4217 have been assigned a keystroke with a previous
4220 \begin_inset Flex Code
4223 \begin_layout Plain Layout
4247 must not belong in the
4294 If such a declaration does not exist in
4302 \begin_inset Flex Code
4305 \begin_layout Plain Layout
4339 \begin_inset Flex Code
4342 \begin_layout Plain Layout
4356 \begin_layout Standard
4357 The following command produces causes äi to be produced when you enter acute-i
4361 \begin_layout LyX-Code
4375 \begin_layout Labeling
4376 \labelwidthstring 00.00.0000
4377 \begin_inset Flex Code
4380 \begin_layout Plain Layout
4386 Combine two accent characters
4389 \begin_layout LyX-Code
4395 accent1 accent2 allowed
4398 \begin_layout Standard
4399 This one is getting pretty esoteric.
4400 It allows you to combine the effect
4456 \begin_inset Flex Code
4459 \begin_layout Plain Layout
4487 \begin_layout Standard
4488 Consider this example from the
4489 \begin_inset Flex Code
4492 \begin_layout Plain Layout
4503 \begin_layout LyX-Code
4506 kmod ; acute aeioyvhAEIOYVH
4510 kcomb acute umlaut iyIY
4513 \begin_layout Standard
4514 This allows you to press
4515 \begin_inset Flex MenuItem
4518 \begin_layout Plain Layout
4526 and get the effect of
4527 \begin_inset Flex Code
4530 \begin_layout Plain Layout
4549 in this case cancels the last dead key, so if you press
4550 \begin_inset Flex MenuItem
4553 \begin_layout Plain Layout
4562 \begin_inset Flex Code
4565 \begin_layout Plain Layout
4578 \begin_layout Subsection
4582 \begin_layout Standard
4584 \begin_inset Flex Code
4587 \begin_layout Plain Layout
4595 mapping is performed, a
4596 \begin_inset Flex Code
4599 \begin_layout Plain Layout
4609 file maps the strings that the symbols generate to characters in the current
4611 The LyX distribution currently includes at least the
4612 \begin_inset Flex Code
4615 \begin_layout Plain Layout
4624 \begin_inset Flex Code
4627 \begin_layout Plain Layout
4638 \begin_layout Standard
4640 \begin_inset Flex Code
4643 \begin_layout Plain Layout
4651 file is a sequence of declarations of the form
4654 \begin_layout LyX-Code
4667 \begin_layout Standard
4668 For example, in order to map
4669 \begin_inset Flex MenuItem
4672 \begin_layout Plain Layout
4682 to the corresponding character in the iso-8859-1 set (233), the following
4686 \begin_layout LyX-Code
4694 \begin_layout Standard
4696 \begin_inset Flex Code
4699 \begin_layout Plain Layout
4708 \begin_inset Flex Code
4711 \begin_layout Plain Layout
4729 the same character can apply to more than one string.
4731 \begin_inset Flex Code
4734 \begin_layout Plain Layout
4745 \begin_layout LyX-Code
4757 \begin_inset Newline newline
4773 \begin_layout Standard
4774 If LyX cannot find a mapping for the string produced by the keystroke or
4775 a deadkey sequence, it will check if it looks like an accented char and
4776 try to draw an accent over the character on screen.
4779 \begin_layout Subsection
4783 \begin_layout Standard
4784 There is a second way to add support for international characters through
4785 so-called dead-keys.
4786 A dead-key works in combination with a letter to produce an accented character.
4787 Here, we'll explain how to create a really simple dead-key to illustrate
4791 \begin_layout Standard
4792 Suppose you happen to need the circumflex character,
4793 \begin_inset Quotes eld
4797 \begin_inset Quotes erd
4802 \begin_inset Flex MenuItem
4805 \begin_layout Plain Layout
4812 \begin_inset space ~
4816 \begin_inset Flex MenuItem
4819 \begin_layout Plain Layout
4825 ] to the LyX command
4826 \begin_inset Flex Code
4829 \begin_layout Plain Layout
4836 \begin_inset Flex Code
4839 \begin_layout Plain Layout
4846 Now, whenever you type the
4847 \begin_inset Flex MenuItem
4850 \begin_layout Plain Layout
4856 -key followed by a letter, that letter will have a circumflex accent on
4858 For example, the sequence
4859 \begin_inset Quotes eld
4863 \begin_inset Flex MenuItem
4866 \begin_layout Plain Layout
4873 \begin_inset Quotes erd
4876 produces the letter:
4877 \begin_inset Quotes eld
4881 \begin_inset Quotes erd
4885 If you tried to type
4886 \begin_inset Quotes eld
4890 \begin_inset Flex MenuItem
4893 \begin_layout Plain Layout
4900 \begin_inset Quotes erd
4903 , however, LyX will complain with a beep, since a
4904 \begin_inset Quotes eld
4908 \begin_inset Flex MenuItem
4911 \begin_layout Plain Layout
4918 \begin_inset Quotes erd
4921 never takes a circumflex accent.
4923 \begin_inset Flex MenuItem
4926 \begin_layout Plain Layout
4932 after a dead-key produces the bare-accent.
4933 Please note this last point! If you bind a key to a dead-key, you'll need
4934 to rebind the character on that key to yet another key.
4936 \begin_inset Flex MenuItem
4939 \begin_layout Plain Layout
4945 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
4948 \begin_layout Standard
4949 One common way to bind dead-keys is to use
4950 \begin_inset Flex MenuItem
4953 \begin_layout Plain Layout
4960 \begin_inset Flex MenuItem
4963 \begin_layout Plain Layout
4970 \begin_inset Flex MenuItem
4973 \begin_layout Plain Layout
4979 in combination with an accent, like
4980 \begin_inset Quotes eld
4984 \begin_inset Flex MenuItem
4987 \begin_layout Plain Layout
4994 \begin_inset Quotes erd
4998 \begin_inset Quotes eld
5002 \begin_inset Flex MenuItem
5005 \begin_layout Plain Layout
5012 \begin_inset Quotes erd
5016 \begin_inset Quotes eld
5020 \begin_inset Flex MenuItem
5023 \begin_layout Plain Layout
5030 \begin_inset Quotes erd
5034 Another way involves using
5035 \begin_inset Flex Code
5038 \begin_layout Plain Layout
5045 \begin_inset Flex Code
5048 \begin_layout Plain Layout
5054 to set up the special
5055 \begin_inset Flex Code
5058 \begin_layout Plain Layout
5066 \begin_inset Flex Code
5069 \begin_layout Plain Layout
5075 acts in some ways just like
5076 \begin_inset Flex MenuItem
5079 \begin_layout Plain Layout
5085 and permits you to bind keys to accented characters.
5086 You can also turn keys into dead-keys by binding them to something like
5088 \begin_inset Flex Code
5091 \begin_layout Plain Layout
5097 and then binding this symbolic key to the corresponding LyX command.
5101 \begin_layout Plain Layout
5106 : This is exactly what I do in my
5107 \begin_inset Flex Code
5110 \begin_layout Plain Layout
5117 \begin_inset Flex Code
5120 \begin_layout Plain Layout
5128 \begin_inset Flex MenuItem
5131 \begin_layout Plain Layout
5133 \begin_inset space ~
5142 \begin_inset Flex Code
5145 \begin_layout Plain Layout
5151 and a bunch of these
5152 \begin_inset Quotes eld
5156 \begin_inset Flex Code
5159 \begin_layout Plain Layout
5166 \begin_inset Quotes erd
5169 symbolic keys bound such things as
5170 \begin_inset Flex MenuItem
5173 \begin_layout Plain Layout
5175 \begin_inset space ~
5184 \begin_inset Flex MenuItem
5187 \begin_layout Plain Layout
5189 \begin_inset space ~
5198 This is how I produce my accented characters.
5203 You can make just about anything into the
5204 \begin_inset Flex Code
5207 \begin_layout Plain Layout
5214 \begin_inset Flex MenuItem
5217 \begin_layout Plain Layout
5223 keys, a spare function key, etc.
5224 As for the LyX commands that produce accents, check the entry for
5225 \begin_inset Flex Code
5228 \begin_layout Plain Layout
5239 You'll find the complete list there.
5242 \begin_layout Subsection
5243 Saving your Language Configuration
5246 \begin_layout Standard
5247 You can edit your preferences so that your desired language environment
5248 is automatically configured when LyX starts up, via the
5249 \begin_inset Flex MenuItem
5252 \begin_layout Plain Layout
5253 Edit\SpecialChar \menuseparator
5262 \begin_layout Chapter
5263 Installing New Document Classes, Layouts, and Templates
5264 \begin_inset CommandInset label
5266 name "cha:Installing-New-Document"
5271 \begin_inset Argument
5274 \begin_layout Plain Layout
5275 Installing New Document Classes
5283 \begin_layout Standard
5284 In this chapter, we describe the procedures for creating and installing
5285 new LyX layout and template files, as well as offer a refresher on correctly
5286 installing new LaTeX document classes.
5290 \begin_layout Standard
5291 First, let us a say a few words about how one ought to think about the relation
5292 between LyX and LaTeX.
5293 The thing to understand is that, in a certain sense, LyX doesn't know anything
5295 Indeed, from LyX's point of view, LaTeX is just one of several
5296 \begin_inset Quotes eld
5300 \begin_inset Quotes erd
5303 in which it is capable of producing output.
5304 Other such formats are DocBook, plaintext, and XHTML.
5305 LaTeX is, of course, a particularly important format, but very little of
5306 the information LyX has about LaTeX is actually contained in the program
5311 \begin_layout Plain Layout
5312 Some commands are sufficiently complex that they are
5313 \begin_inset Quotes eld
5317 \begin_inset Quotes erd
5321 But the developers generally regard this as a Bad Thing.
5326 Rather, that information, even for the standard classes like
5327 \begin_inset Flex Code
5330 \begin_layout Plain Layout
5336 , is contained in `layout files'.
5337 Similarly, LyX itself does not know much about DocBook or XHTML.
5338 What it knows is contained in layout files.
5341 \begin_layout Standard
5342 You can think of the layout file for a given document class as a translation
5343 manual between LyX constructs---paragraphs with their corresponding styles,
5344 certain sorts of insets, etc---and the corresponding LaTeX, DocBook, or
5346 Almost everything LyX knows about
5347 \begin_inset Flex Code
5350 \begin_layout Plain Layout
5356 , for example, is contained in the file
5357 \begin_inset Flex Code
5360 \begin_layout Plain Layout
5366 and in various other files it includes.
5367 For this reason, anyone intending to write layout files should plan to
5368 study the existing files.
5369 A good place to start is with
5370 \begin_inset Flex Code
5373 \begin_layout Plain Layout
5379 , which is included in
5380 \begin_inset Flex Code
5383 \begin_layout Plain Layout
5390 \begin_inset Flex Code
5393 \begin_layout Plain Layout
5399 , and many of the other layout files for document classes.
5400 This file is where sections and the like are defined:
5401 \begin_inset Flex Code
5404 \begin_layout Plain Layout
5410 tells LyX how paragraphs that are marked with the Section, Subsection,
5411 etc, styles can be translated into corresponding LaTeX, DocBook, and XHTML
5414 \begin_inset Flex Code
5417 \begin_layout Plain Layout
5423 file basically just includes several of these
5424 \begin_inset Flex Code
5427 \begin_layout Plain Layout
5436 \begin_layout Standard
5437 Defining the LyX--LaTeX correspondence is not the only thing layout files
5439 Their other job is to define how the LyX constructs themselves will appear
5441 The fact that layout files have these two jobs is often a source of confusion,
5442 because they are completely separate.
5443 Telling LyX how to translate a certain paragraph style into LaTeX does
5444 not tell LyX how to display it; conversely, telling LyX how to display
5445 a certain paragraph style does not tell LyX how to translate it into LaTeX
5446 (let alone tell LaTeX how to display it).
5447 So, in general, when you define a new LyX construct, you must always do
5448 two quite separate things: (i)
5449 \begin_inset space ~
5452 tell LyX how to translate it into LaTeX and (ii)
5453 \begin_inset space ~
5456 tell LyX how to display it.
5459 \begin_layout Standard
5460 Much the same is true, of course, as regards LyX's other backend formats,
5461 though XHTML is in some ways different, because in that case LyX
5465 able, to some extent, to use information about how it should display a
5466 paragraph on the screen to output information (in the form of CSS) about
5467 how the paragraph should be displayed in a browser.
5468 Even in this case, however, the distinction between what LyX does internally
5469 and how things are rendered externally remains in force, and the two can
5470 be controlled separately.
5472 \begin_inset CommandInset ref
5474 reference "sec:Tags-for-XHTML"
5481 \begin_layout Section
5482 Installing new LaTeX files
5485 \begin_layout Standard
5486 Some installations may not include a LaTeX package or class file that you
5487 would like to use within LyX.
5488 For example, you might need FoilTeX, a package for preparing slides for
5489 overhead projectors.
5490 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5491 a user interface for installing such packages.
5492 For example, with MiKTeX, you start the program
5493 \begin_inset Quotes eld
5497 \begin_inset space ~
5501 \begin_inset Quotes erd
5504 to get a list of available packages.
5505 To install one of them, right click on it or use the corresponding toolbar
5509 \begin_layout Standard
5510 If your LaTeX distribution does not provide such a `package manager', or
5511 if the package is not available from your distribution, then follow these
5512 steps to install it manually:
5515 \begin_layout Enumerate
5516 Get the package from
5517 \begin_inset CommandInset href
5520 target "http://www.ctan.org/"
5527 \begin_layout Enumerate
5528 If the package contains a file with the ending
5529 \begin_inset Quotes eld
5533 \begin_inset Flex Code
5536 \begin_layout Plain Layout
5543 \begin_inset Quotes erd
5546 (is the case for FoilTeX) then open a console, change to the folder of
5547 this file and execute the command
5548 \begin_inset Flex Code
5551 \begin_layout Plain Layout
5558 You have now unpacked the package and have all files to install it.
5559 Most LaTeX-packages are not packed and you can skip this step.
5562 \begin_layout Enumerate
5563 Now you need to decide if the package should be available for all users
5568 \begin_layout Enumerate
5569 On *nix systems (Linux, OSX, etc.), if you want the new package to be available
5570 for all users on your system, then install it in your `local' TeX tree,
5571 otherwise install it in your own `user' TeX tree.
5572 Where these trees should be created, if they do not already exist, depends
5574 To find this out, look in the file
5575 \begin_inset Flex Code
5578 \begin_layout Plain Layout
5588 \begin_layout Plain Layout
5589 This is usually in the directory
5590 \begin_inset Flex Code
5593 \begin_layout Plain Layout
5599 , though you can execute the command
5600 \begin_inset Flex Code
5603 \begin_layout Plain Layout
5614 The location of the `local' TeX tree is defined by the
5615 \begin_inset Flex Code
5618 \begin_layout Plain Layout
5624 variable; this is usually somewhere like
5625 \begin_inset Flex Code
5628 \begin_layout Plain Layout
5629 /usr/local/share/texmf
5635 The location of the `user' TeX tree is defined by
5636 \begin_inset Flex Code
5639 \begin_layout Plain Layout
5646 \begin_inset Flex Code
5649 \begin_layout Plain Layout
5656 (If these variables are not predefined, you have to define them.) You'll
5657 probably need root permissions to create or modify the `local' tree, but
5658 not for your `user' tree.
5659 \begin_inset Newline newline
5662 In general, it is recommended to install in the user tree because your user
5663 will not be modified or even overwritten when you upgrade your system.
5664 It will typically also be backed up together with everything else when
5665 you backup your home directory (which, of course, you do on a regular basis).
5668 \begin_layout Enumerate
5669 On Windows, if you want the new package to be available for all users on
5670 your system, change to the folder where LaTeX is installed and then change
5672 \begin_inset Flex Code
5675 \begin_layout Plain Layout
5686 (For MiKTeX, this would be by default the folder
5687 \begin_inset Flex Code
5690 \begin_layout Plain Layout
5708 \begin_layout Plain Layout
5709 Note that this will be the correct path only on English installations.
5710 On a German one, it would be
5711 \begin_inset Flex Code
5714 \begin_layout Plain Layout
5728 , and similarly for other languages.
5733 Create there a new folder
5734 \begin_inset Flex Code
5737 \begin_layout Plain Layout
5743 and copy all files of the package into it.
5745 \begin_inset Newline newline
5748 If the package should only available for you or you don't have admin permissions
5749 , do the same, but in the local LaTeX folder.
5751 \begin_inset space \thinspace{}
5755 \begin_inset space ~
5758 2.8 under Windows XP, this would be the folder:
5759 \begin_inset Newline newline
5765 \begin_inset Flex Code
5768 \begin_layout Plain Layout
5771 Documents and Settings
5783 \begin_inset Newline newline
5789 \begin_inset Phantom HPhantom
5792 \begin_layout Plain Layout
5803 \begin_inset Flex Code
5806 \begin_layout Plain Layout
5819 \begin_inset Newline newline
5822 On Vista, it would be:
5823 \begin_inset Newline newline
5827 \begin_inset Flex Code
5830 \begin_layout Plain Layout
5856 \begin_layout Enumerate
5857 Now one only need to tell LaTeX that there are new files.
5858 This depends on the used LaTeX-Distribution:
5862 \begin_layout Enumerate
5863 For TeXLive execute the command
5864 \begin_inset Flex Code
5867 \begin_layout Plain Layout
5874 If you installed the package for all users, then you will probably need
5875 to have root permissions for that.
5878 \begin_layout Enumerate
5879 For MiKTeX, if you have installed the package for all users, start the program
5881 \begin_inset Quotes eld
5885 \begin_inset space ~
5889 \begin_inset Quotes erd
5892 and press the button marked
5893 \begin_inset Quotes eld
5897 \begin_inset Quotes erd
5901 Otherwise start the program
5902 \begin_inset Quotes eld
5906 \begin_inset Quotes erd
5913 \begin_layout Enumerate
5914 Finally, you need to tell LyX that there are new packages available.
5915 So, in LyX, use the menu
5916 \begin_inset Flex MenuItem
5919 \begin_layout Plain Layout
5922 \SpecialChar \menuseparator
5928 and then restart LyX.
5931 \begin_layout Standard
5932 Now the package is installed.
5933 In our example, the document class
5934 \begin_inset Flex Code
5937 \begin_layout Plain Layout
5939 \begin_inset space ~
5946 \begin_layout Plain Layout
5958 will now be available under
5959 \begin_inset Flex MenuItem
5962 \begin_layout Plain Layout
5963 Document\SpecialChar \menuseparator
5964 Settings\SpecialChar \menuseparator
5974 \begin_layout Standard
5975 If you would like to use a LaTeX document class that is not even listed
5977 \begin_inset Flex MenuItem
5980 \begin_layout Plain Layout
5981 Document\SpecialChar \menuseparator
5982 Settings\SpecialChar \menuseparator
5988 , then you need to create a `layout' file for it.
5989 That is the topic of the next section.
5992 \begin_layout Section
5993 Types of layout files
5996 \begin_layout Standard
5997 This section describes the various sorts of LyX files that contain layout
5999 These files describe various paragraph and character styles, determining
6000 how LyX should display them and how they should be translated into LaTeX,
6001 DocBook, XHTML, or whatever output format is being used.
6005 \begin_layout Standard
6006 We shall try to provide a thorough description of the process of writing
6008 However, there are so many different types of documents supported even
6009 by just LaTeX that we can't hope to cover every different possibility or
6010 problem you might encounter.
6011 The LyX users' list is frequented by people with lots of experience with
6012 layout design who are willing to share what they've learned, so please
6013 feel free to ask questions there.
6016 \begin_layout Standard
6017 As you prepare to write a new layout, it is extremely helpful to look at
6018 the layouts distributed with LyX.
6019 If you write a LyX layout for a LaTeX document class that might also be
6020 used by others, or write a module that might be useful to others, then
6021 you should consider posting your layout to the
6022 \begin_inset CommandInset href
6024 name "layout section on the LyX wiki"
6025 target "http://wiki.lyx.org/Layouts/Layouts"
6029 or even to the LyX developers' list, so that it might be included in LyX
6034 \begin_layout Plain Layout
6035 Note that LyX is licensed under the General Public License, so any material
6036 that is contributed to LyX must be similarly licensed.
6044 \begin_layout Subsection
6046 \begin_inset CommandInset label
6048 name "sub:Layout-modules"
6055 \begin_layout Standard
6056 We have spoken to this point about `layout files'.
6057 But there are different sorts of files that contain layout information.
6058 Layout files, strictly so called, have the
6059 \begin_inset Flex Code
6062 \begin_layout Plain Layout
6068 extension and provide LyX with information about document classes.
6069 As of LyX 1.6, however, layout information can also be contained in layout
6075 \begin_inset Flex Code
6078 \begin_layout Plain Layout
6085 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6086 some modules—such as the
6087 \begin_inset Flex Code
6090 \begin_layout Plain Layout
6096 module—specifically provide support for one package.
6097 In a sense, layout modules are similar to included
6101 \begin_layout Plain Layout
6102 These can have any extension, but by convention have the
6103 \begin_inset Flex Code
6106 \begin_layout Plain Layout
6118 \begin_inset Flex Code
6121 \begin_layout Plain Layout
6127 —in that modules are not specific to a given document class but may be used
6128 with many different classes.
6129 The difference is that using an included file with
6130 \begin_inset Flex Code
6133 \begin_layout Plain Layout
6139 requires editing that file.
6140 Modules, by contrast, are selected in the
6141 \begin_inset Flex MenuItem
6144 \begin_layout Plain Layout
6145 Document\SpecialChar \menuseparator
6154 \begin_layout Standard
6155 Building modules is the easiest way to get started with layout editing,
6156 since it can be as simple as adding a single new paragraph style or flex
6158 But modules may, in principle, contain anything a layout file can contain.
6161 \begin_layout Standard
6162 After creating a new module and copying it to the
6163 \begin_inset Flex Code
6166 \begin_layout Plain Layout
6172 folder, you will need to reconfigure and then restart LyX for the module
6173 to appear in the menu.
6174 However, changes you make to the module will be seen immediately, if you
6176 \begin_inset Flex MenuItem
6179 \begin_layout Plain Layout
6180 Document\SpecialChar \menuseparator
6186 , highlight something, and then hit
6187 \begin_inset Quotes eld
6191 \begin_inset Quotes erd
6197 It is strongly recommended that you save your work before doing this
6202 it is strongly recommended that you not attempt to edit modules while simultaneo
6203 usly working on actual documents
6206 Though of course the developers strive to keep LyX stable in such situations,
6207 syntax errors and the like in your module file could cause strange behavior.
6210 \begin_layout Subsection
6212 \begin_inset Flex MenuItem
6215 \begin_layout Plain Layout
6224 \begin_layout Standard
6225 There are two situations you are likely to encounter when wanting to support
6226 a new LaTeX document class, involving style (
6227 \begin_inset Flex Code
6230 \begin_layout Plain Layout
6236 ) files and LaTeX2e class (
6237 \begin_inset Flex Code
6240 \begin_layout Plain Layout
6247 Supporting a style file is usually fairly easy.
6248 Supporting a new class file is a bit harder.
6249 We'll discuss the former in this section and the latter in the next.
6250 Similar remarks apply, of course, if you want to support a new DocBook
6254 \begin_layout Standard
6255 The easier case is the one in which your new document class is provided
6256 as a style file that is to be used in conjunction with an already supported
6258 For the sake of the example, we'll assume that the style file is called
6260 \begin_inset Flex MenuItem
6263 \begin_layout Plain Layout
6269 and that it is meant to be used with
6270 \begin_inset Flex MenuItem
6273 \begin_layout Plain Layout
6279 , which is a standard class.
6283 \begin_layout Standard
6284 Start by copying the existing class's layout file into your local directory:
6288 \begin_layout Plain Layout
6289 Of course, which directory is your local directory will vary by platform,
6290 and LyX allows you to specify your local directory on startup, too, using
6292 \begin_inset Flex Code
6295 \begin_layout Plain Layout
6309 \begin_layout LyX-Code
6310 cp report.layout ~/.lyx/layouts/myclass.layout
6313 \begin_layout Standard
6315 \begin_inset Flex Code
6318 \begin_layout Plain Layout
6324 and change the line:
6327 \begin_layout LyX-Code
6330 DeclareLaTeXClass{report}
6333 \begin_layout Standard
6337 \begin_layout LyX-Code
6340 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6343 \begin_layout Standard
6347 \begin_layout LyX-Code
6349 \begin_inset Newline newline
6355 \begin_inset Newline newline
6361 \begin_layout Standard
6362 near the top of the file.
6365 \begin_layout Standard
6366 Start LyX and select
6367 \begin_inset Flex MenuItem
6370 \begin_layout Plain Layout
6371 Tools\SpecialChar \menuseparator
6378 Then restart LyX and try creating a new document.
6380 \begin_inset Flex MenuItem
6383 \begin_layout Plain Layout
6389 " as a document class option in the
6390 \begin_inset Flex MenuItem
6393 \begin_layout Plain Layout
6394 Document\SpecialChar \menuseparator
6401 It is likely that some of the sectioning commands and such in your new
6402 class will work differently from how they worked in the base class—
6403 \begin_inset Flex Code
6406 \begin_layout Plain Layout
6412 in this example—so you can fiddle around with the settings for the different
6413 sections if you wish.
6414 The layout information for sections is contained in
6415 \begin_inset Flex Code
6418 \begin_layout Plain Layout
6424 , but you do not need to copy and change this file.
6425 Instead, you can simply add your changes to your layout file, after the
6427 \begin_inset Flex Code
6430 \begin_layout Plain Layout
6436 , which itself includes
6437 \begin_inset Flex Code
6440 \begin_layout Plain Layout
6447 For example, you might add these lines:
6450 \begin_layout LyX-Code
6454 \begin_layout LyX-Code
6458 \begin_layout LyX-Code
6462 \begin_layout LyX-Code
6466 \begin_layout LyX-Code
6470 \begin_layout Standard
6471 to change the font for chapter headings to sans-serif.
6472 This will override (or, in this case, add to) the existing declaration
6473 for the Chapter style.
6477 \begin_layout Standard
6478 Your new package may also provide commands or environments not present in
6480 In this case, you will want to add these to the layout file.
6482 \begin_inset CommandInset ref
6484 reference "sec:TextClass"
6488 for information on how to do so.
6491 \begin_layout Standard
6493 \begin_inset Flex MenuItem
6496 \begin_layout Plain Layout
6502 can be used with several different document classes, and even if it cannot,
6503 you might find it easiest just to write a module that you can load with
6505 The simplest possible such module would be:
6508 \begin_layout LyX-Code
6511 DeclareLyXModule{My Package}
6514 \begin_layout LyX-Code
6518 \begin_layout LyX-Code
6519 #Support for mypkg.sty.
6522 \begin_layout LyX-Code
6524 \begin_inset Newline newline
6530 \begin_layout LyX-Code
6532 \begin_inset Newline newline
6538 \begin_layout LyX-Code
6540 \begin_inset Newline newline
6546 \begin_inset Newline newline
6552 \begin_layout Standard
6553 A more complex module might modify the behavior of some existing constructs
6554 or define some new ones.
6556 \begin_inset CommandInset ref
6558 reference "sec:TextClass"
6565 \begin_layout Subsection
6567 \begin_inset Flex MenuItem
6570 \begin_layout Plain Layout
6579 \begin_layout Standard
6580 There are two possibilities here.
6581 One is that the class file is itself based upon an existing document class.
6582 For example, many thesis classes are based upon
6583 \begin_inset Flex MenuItem
6586 \begin_layout Plain Layout
6593 To see whether yours is, look for a line like
6596 \begin_layout LyX-Code
6602 \begin_layout Standard
6604 If so, then you may proceed largely as in the previous section, though
6606 \begin_inset Flex Code
6609 \begin_layout Plain Layout
6615 line will be different.
6616 If your new class is
6617 \begin_inset Flex Code
6620 \begin_layout Plain Layout
6626 and it is based upon
6627 \begin_inset Flex Code
6630 \begin_layout Plain Layout
6636 , then the line should read:
6640 \begin_layout Plain Layout
6641 And it will be easiest if you save the file to
6642 \begin_inset Flex Code
6645 \begin_layout Plain Layout
6651 : LyX assumes that the document class has the same name as the layout file.
6660 \begin_layout LyX-Code
6663 DeclareLaTeXClass[thesis,book]{thesis}
6666 \begin_layout Standard
6667 If, on the other hand, the new class is not based upon an existing class,
6668 you will probably have to
6669 \begin_inset Quotes eld
6673 \begin_inset Quotes erd
6677 We strongly suggest copying an existing layout file which uses a similar
6678 LaTeX class and then modifying it, if you can do so.
6679 At least use an existing file as a starting point so you can find out what
6680 items you need to worry about.
6681 Again, the specifics are covered below.
6684 \begin_layout Subsection
6686 \begin_inset CommandInset label
6688 name "sub:Creating-Templates"
6695 \begin_layout Standard
6696 Once you have written a layout file for a new document class, you might
6697 want to consider writing a
6702 A template acts as a kind of tutorial for your layout, showing how it might
6703 be used, though containing dummy content.
6704 You can of course look at the various templates included with LyX for ideas.
6707 \begin_layout Standard
6708 Templates are created just like usual documents: using LyX.
6709 The only difference is that usual documents contain all possible settings,
6710 including the font scheme and the paper size.
6711 Usually a user doesn't want a template to overwrite his preferred settings
6712 for such parameters.
6713 For that reason, the designer of a template should remove the corresponding
6715 \begin_inset Flex Code
6718 \begin_layout Plain Layout
6727 \begin_inset Flex Code
6730 \begin_layout Plain Layout
6738 from the template LyX file.
6739 This can be done with any simple text-editor, for example
6740 \begin_inset Flex Code
6743 \begin_layout Plain Layout
6750 \begin_inset Flex Code
6753 \begin_layout Plain Layout
6763 \begin_layout Standard
6764 Put the edited template files you create in
6765 \begin_inset Flex Code
6768 \begin_layout Plain Layout
6774 , copy the ones you use from the global template directory in
6775 \begin_inset Flex Code
6778 \begin_layout Plain Layout
6784 to the same place, and redefine the template path in the
6785 \begin_inset Flex MenuItem
6788 \begin_layout Plain Layout
6789 Tools\SpecialChar \menuseparator
6790 Preferences\SpecialChar \menuseparator
6799 \begin_layout Standard
6800 Note, by the way, that there is a template which has a particular meaning:
6802 \begin_inset Flex Code
6805 \begin_layout Plain Layout
6812 This template is loaded every time you create a new document with
6813 \begin_inset Flex MenuItem
6816 \begin_layout Plain Layout
6817 File\SpecialChar \menuseparator
6823 in order to provide useful defaults.
6824 To create this template from inside LyX, all you have to do is to open
6825 a document with the correct settings, and use the
6826 \begin_inset Flex MenuItem
6829 \begin_layout Plain Layout
6830 Save as Document Defaults
6838 \begin_layout Subsection
6839 Upgrading old layout files
6842 \begin_layout Standard
6843 The format of layout files changes with each LyX release, so old layout
6844 files need to be converted to the new format.
6845 This process has been automated since LyX 1.4: If LyX reads a layout file
6846 in an older format, it automatically calls the script
6847 \begin_inset Flex Code
6850 \begin_layout Plain Layout
6856 to convert it to a temporary file in current format.
6857 The original file is left untouched.
6858 If you use the layout file often, then, you may want to convert it permanently,
6859 so that LyX does not have to do so itself every time.
6860 To do this, you can call the converter manually:
6863 \begin_layout LyX-Code
6864 mv myclass.layout myclass.old
6867 \begin_layout LyX-Code
6868 python LyXDir/scripts/layout2layout.py myclass.old myclass.layout
6871 \begin_layout Standard
6873 \begin_inset Flex Code
6876 \begin_layout Plain Layout
6882 with the name of your LyX system directory, of course.
6885 \begin_layout Standard
6886 Note that manual conversion does not affect included files, so these will
6887 have to be converted separately.
6890 \begin_layout Section
6891 \begin_inset CommandInset label
6893 name "sec:TextClass"
6897 The layout file format
6900 \begin_layout Standard
6901 When it's finally time to get your hands dirty and create or edit your own
6902 layout file, the following sections describe what you're up against.
6903 Our advice is to go slowly, save and test often, listen to soothing music,
6904 and enjoy one or two of your favorite adult beverages; more if you are
6905 getting particularly stuck.
6906 It's really not that hard, except that the multitude of options can become
6907 overwhelming if you try to do too much in one sitting.
6908 Go have another adult beverage, just for good measure.
6911 \begin_layout Standard
6912 Note that all the tags used in layout files are case-insensitive.
6914 \begin_inset Flex Code
6917 \begin_layout Plain Layout
6924 \begin_inset Flex Code
6927 \begin_layout Plain Layout
6934 \begin_inset Flex Code
6937 \begin_layout Plain Layout
6943 are really the same tag.
6944 The possible values are printed in brackets after the feature's name.
6945 The default value if a feature isn't specified inside a text class-description
6947 \begin_inset Flex Code
6950 \begin_layout Plain Layout
6959 If the argument has a data type like
6960 \begin_inset Quotes eld
6964 \begin_inset Quotes erd
6968 \begin_inset Quotes eld
6972 \begin_inset Quotes erd
6975 , the default is shown like this:
6976 \begin_inset Flex Code
6979 \begin_layout Plain Layout
6990 \begin_layout Subsection
6991 The document class declaration
6994 \begin_layout Standard
6995 Lines in a layout file which begin with
6996 \begin_inset Flex Code
6999 \begin_layout Plain Layout
7006 There is one exception to this rule.
7008 \begin_inset Flex Code
7011 \begin_layout Plain Layout
7017 files should begin with a line like:
7020 \begin_layout LyX-Code
7023 #% Do not delete the line below; configure depends on this
7026 \begin_layout LyX-Code
7031 DeclareLaTeXClass{article}
7034 \begin_layout Standard
7035 The second line is used when you (re)configure LyX.
7036 The layout file is read by the LaTeX script
7037 \begin_inset Flex Code
7040 \begin_layout Plain Layout
7046 , in a special mode where
7047 \begin_inset Flex Code
7050 \begin_layout Plain Layout
7057 The first line is just a LaTeX comment, and the second one contains the
7058 declaration of the text class.
7059 If these lines appear in a file named
7060 \begin_inset Flex Code
7063 \begin_layout Plain Layout
7069 , then they define a text class of name
7070 \begin_inset Flex Code
7073 \begin_layout Plain Layout
7079 (the name of the layout file) which uses the LaTeX document class
7080 \begin_inset Flex Code
7083 \begin_layout Plain Layout
7089 (the default is to use the same name as the layout).
7091 \begin_inset Quotes eld
7095 \begin_inset Quotes erd
7098 that appears above is used as a description of the text class in the
7099 \begin_inset Flex MenuItem
7102 \begin_layout Plain Layout
7103 Document\SpecialChar \menuseparator
7112 \begin_layout Standard
7113 Let's assume that you wrote your own text class that uses the
7114 \begin_inset Flex Code
7117 \begin_layout Plain Layout
7123 document class, but where you changed the appearance of the section headings.
7124 If you put it in a file
7125 \begin_inset Flex Code
7128 \begin_layout Plain Layout
7134 , the header of this file should be:
7137 \begin_layout LyX-Code
7140 #% Do not delete the line below; configure depends on this
7143 \begin_layout LyX-Code
7148 DeclareLaTeXClass[article]{article (with my own headings)}
7151 \begin_layout Standard
7152 This declares a text class
7153 \begin_inset Flex Code
7156 \begin_layout Plain Layout
7162 , associated with the LaTeX document class
7163 \begin_inset Flex Code
7166 \begin_layout Plain Layout
7173 \begin_inset Quotes eld
7176 article (with my own headings)
7177 \begin_inset Quotes erd
7181 If your text class depends on several packages, you can declare it as:
7184 \begin_layout LyX-Code
7187 #% Do not delete the line below; configure depends on this
7190 \begin_layout LyX-Code
7195 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
7198 \begin_layout Standard
7199 This indicates that your text class uses the
7200 \begin_inset Flex Code
7203 \begin_layout Plain Layout
7210 Finally, it is also possible to declare classes for DocBook code.
7211 Typical declarations will look like:
7214 \begin_layout LyX-Code
7217 #% Do not delete the line below; configure depends on this
7220 \begin_layout LyX-Code
7225 DeclareDocBookClass[article]{SGML (DocBook article)}
7228 \begin_layout Standard
7229 Note that these declarations can also be given an optional parameter declaring
7230 the name of the document class (but not a list).
7233 \begin_layout Standard
7234 So, to be as explicit as possible, the form of the layout declaration is:
7237 \begin_layout LyX-Code
7242 DeclareLaTeXClass[class,package.sty]{layout description}
7245 \begin_layout Standard
7246 The class need only be specified if the name of the LaTeX class file and
7247 the name of the layout file are different or if there are packages to load.
7248 If the name of the class file is not specified, then LyX will simply assume
7249 that it is the same as the name of the layout file.
7252 \begin_layout Standard
7253 When the text class has been modified to your taste, all you have to do
7254 is to copy it either to
7255 \begin_inset Flex Code
7258 \begin_layout Plain Layout
7265 \begin_inset Flex Code
7268 \begin_layout Plain Layout
7275 \begin_inset Flex MenuItem
7278 \begin_layout Plain Layout
7279 Tools\SpecialChar \menuseparator
7285 , exit LyX and restart.
7286 Then your new text class should be available along with the others.
7289 \begin_layout Standard
7290 Once the layout file is installed, you can edit it and see your changes
7291 without having to reconfigure or to restart LyX.
7296 \begin_layout Plain Layout
7297 In versions of LyX prior to 1.6, this was not true.
7298 As a result, editing layout files was very time consuming, since you had
7299 constantly to restart LyX to see changes.
7304 You can force a reload of the current layout by using the LyX function
7306 \begin_inset Flex MenuItem
7309 \begin_layout Plain Layout
7316 There is no default binding for this function—though, of course, you can
7317 bind it to a key yourself.
7318 But you will normally use this function simply by entering it in the mini-buffe
7323 \begin_layout Standard
7329 \begin_inset Flex MenuItem
7332 \begin_layout Plain Layout
7338 is very much an `advanced feature'.
7343 recommended that you save your work before using this function.
7348 recommended that you not attempt to edit layout information while simultaneousl
7349 y working on a document that you care about.
7350 Use a test document.
7351 Syntax errors and the like in your layout file could cause peculiar behavior.
7352 In particular, such errors could cause LyX to regard the current layout
7353 as invalid and to attempt to switch to some other layout.
7357 \begin_layout Plain Layout
7358 Really bad syntax errors may even caused LyX to exit.
7359 This is because certain sorts of errors may make LyX unable to read
7369 The LyX team strives to keep LyX stable in such situations, but safe is
7374 \begin_layout Plain Layout
7375 While we're giving advice: make regular backups.
7376 And be nice to your mother.
7384 \begin_layout Subsection
7385 The Module declaration
7388 \begin_layout Standard
7389 A module must begin with a line like the following:
7392 \begin_layout LyX-Code
7395 DeclareLyXModule[endnotes.sty]{Endnotes}
7398 \begin_layout Standard
7399 The mandatory argument, in curly brackets, is the name of the module, as
7401 \begin_inset Flex MenuItem
7404 \begin_layout Plain Layout
7405 Document\SpecialChar \menuseparator
7407 \change_inserted 34634807 1296981553
7408 \SpecialChar \menuseparator
7417 The argument in square brackets is optional: It declares any LaTeX packages
7418 on which the module depends.
7419 Please note that only packages about which LyX knows should be listed in
7420 the square brackets.
7424 \begin_layout Plain Layout
7425 The list of such packages is documented only in the source code.
7430 LyX will not check for arbitrary packages.
7431 It is also possible to use the form
7432 \begin_inset Flex MenuItem
7435 \begin_layout Plain Layout
7441 as an optional argument, which declares that the module can only be used
7442 when there exists a conversion chain between the formats `
7443 \begin_inset Flex Code
7446 \begin_layout Plain Layout
7453 \begin_inset Flex Code
7456 \begin_layout Plain Layout
7465 \begin_layout Standard
7466 The module declaration should then be followed by lines like the following
7467 \change_inserted 34634807 1296981696
7472 \begin_layout Plain Layout
7474 \change_inserted 34634807 1296981696
7475 Preferably in English if the module should be published with LyX.
7476 This description will appear in the list of messages to be translated and
7477 will be thus translated with the next interface update.
7487 \begin_layout LyX-Code
7491 \begin_layout LyX-Code
7492 #Adds an endnote command, in addition to footnotes.
7496 \begin_layout LyX-Code
7497 #You will need to add
7499 theendnotes in TeX code where you
7502 \begin_layout LyX-Code
7503 #want the endnotes to appear.
7507 \begin_layout LyX-Code
7511 \begin_layout LyX-Code
7512 #Requires: somemodule | othermodule
7515 \begin_layout LyX-Code
7516 #Excludes: badmodule
7519 \begin_layout Standard
7520 The description is used in
7521 \begin_inset Flex MenuItem
7524 \begin_layout Plain Layout
7525 Document\SpecialChar \menuseparator
7527 \change_inserted 34634807 1296981581
7528 \SpecialChar \menuseparator
7536 to provide the user with information about what the module does.
7538 \begin_inset Flex Code
7541 \begin_layout Plain Layout
7547 line is used to identify other modules with which this one must be used;
7549 \begin_inset Flex Code
7552 \begin_layout Plain Layout
7558 line is used to identify modules with which this one may not be used.
7559 Both are optional, and, as shown, multiple modules should be separated
7560 with the pipe symbol: |.
7561 Note that the required modules are treated disjunctively:
7565 of the required modules must be used.
7570 excluded module may be used.
7571 Note that modules are identified here by their
7576 \begin_inset Flex Code
7579 \begin_layout Plain Layout
7587 \begin_inset Flex Code
7590 \begin_layout Plain Layout
7597 \begin_inset Flex Code
7600 \begin_layout Plain Layout
7609 \begin_layout Subsection
7611 \change_inserted 34634807 1296981875
7613 \change_deleted 34634807 1296981874
7617 \change_inserted 34634807 1296981882
7623 \begin_layout Standard
7624 The first non-comment line of any layout file, included file, or module
7629 contain the file format number:
7632 \begin_layout Description
7633 \begin_inset Flex Code
7636 \begin_layout Plain Layout
7643 \begin_inset Flex Code
7646 \begin_layout Plain Layout
7652 ] The format of the layout file.
7655 \begin_layout Standard
7656 This tag was introduced with LyX 1.4.0.
7657 Layout files from LyX 1.3.x and earlier don't have an explicit file format
7658 and are considered to be of format 1.
7659 The format for the present version of LyX is format 21.
7660 But each version of LyX is capable of reading earlier versions' layout
7661 files, just as they are capable of reading files produced by earlier versions
7663 There is, however, no provision for converting to earlier formats.
7664 So LyX 1.6.x will not read layout files in format 21 but only files in format
7668 \begin_layout Subsection
7669 \begin_inset CommandInset label
7671 name "sub:General-text-class"
7675 General text class parameters
7678 \begin_layout Standard
7679 These are general parameters that govern the behavior of an entire document
7685 mean that they must appear in
7686 \begin_inset Flex Code
7689 \begin_layout Plain Layout
7695 files rather than in modules.
7696 A module can contain any layout tag.)
7699 \begin_layout Description
7700 \begin_inset Flex Code
7703 \begin_layout Plain Layout
7709 Adds information that will be output in the
7710 \begin_inset Flex Code
7713 \begin_layout Plain Layout
7719 block when this document class is output to XHTML.
7720 Typically, this would be used to output CSS style information, but it can
7721 be used for anything that can appear in
7722 \begin_inset Flex Code
7725 \begin_layout Plain Layout
7733 \begin_inset Quotes eld
7737 \begin_inset Flex Code
7740 \begin_layout Plain Layout
7747 \begin_inset Quotes erd
7753 \begin_layout Description
7754 \begin_inset Flex Code
7757 \begin_layout Plain Layout
7763 Adds information to the document preamble.
7765 \begin_inset Quotes eld
7769 \begin_inset Flex Code
7772 \begin_layout Plain Layout
7779 \begin_inset Quotes erd
7785 \begin_layout Description
7786 \begin_inset Flex Code
7789 \begin_layout Plain Layout
7795 Defines formats for use in the display of bibliographic information.
7797 \begin_inset CommandInset ref
7799 reference "sub:Citation-format-description"
7805 \begin_inset Quotes eld
7809 \begin_inset Flex Code
7812 \begin_layout Plain Layout
7819 \begin_inset Quotes erd
7825 \begin_layout Description
7826 \begin_inset Flex Code
7829 \begin_layout Plain Layout
7835 Describes various global options supported by the document class.
7837 \begin_inset space ~
7841 \begin_inset CommandInset ref
7843 reference "sub:ClassOptions"
7849 \begin_inset Quotes eld
7853 \begin_inset Flex Code
7856 \begin_layout Plain Layout
7863 \begin_inset Quotes erd
7869 \begin_layout Description
7870 \begin_inset Flex Code
7873 \begin_layout Plain Layout
7880 \begin_inset Flex Code
7883 \begin_layout Plain Layout
7892 \begin_inset Flex Code
7895 \begin_layout Plain Layout
7901 ] Whether the class should
7905 to having one or two columns.
7906 Can be changed in the
7907 \begin_inset Flex MenuItem
7910 \begin_layout Plain Layout
7911 Document\SpecialChar \menuseparator
7920 \begin_layout Description
7921 \begin_inset Flex Code
7924 \begin_layout Plain Layout
7931 \begin_inset Flex Code
7934 \begin_layout Plain Layout
7940 ] This sequence defines the properties for a counter.
7941 If the counter does not yet exist, it is created; if it does exist, it
7944 \begin_inset Quotes eld
7948 \begin_inset Flex Code
7951 \begin_layout Plain Layout
7958 \begin_inset Quotes erd
7962 \begin_inset Newline newline
7966 \begin_inset space ~
7970 \begin_inset CommandInset ref
7972 reference "sub:Counters"
7976 for details on counters.
7979 \begin_layout Description
7980 \begin_inset Flex Code
7983 \begin_layout Plain Layout
7989 Sets the default font used to display the document.
7991 \begin_inset space ~
7995 \begin_inset CommandInset ref
7997 reference "sub:Font-description"
8001 for how to declare fonts.
8003 \begin_inset Quotes eld
8007 \begin_inset Flex Code
8010 \begin_layout Plain Layout
8017 \begin_inset Quotes erd
8023 \begin_layout Description
8024 \begin_inset Flex Code
8027 \begin_layout Plain Layout
8034 \begin_inset Flex Code
8037 \begin_layout Plain Layout
8043 Specifies a module to be included by default with this document class.
8044 The module should be specified by filename without the
8045 \begin_inset Flex Code
8048 \begin_layout Plain Layout
8055 The user can still remove the module, but it will be active at the outset.
8056 (This applies only when new files are created, or when this class is chosen
8057 for an existing document.)
8060 \begin_layout Description
8061 \begin_inset Flex Code
8064 \begin_layout Plain Layout
8071 \begin_inset Flex Code
8074 \begin_layout Plain Layout
8080 ] This is the style that will be assigned to new paragraphs, usually
8081 \begin_inset Flex MenuItem
8084 \begin_layout Plain Layout
8091 This will default to the first defined style if not given, but you are
8092 encouraged to use this directive.
8095 \begin_layout Description
8096 \begin_inset Flex Code
8099 \begin_layout Plain Layout
8106 \begin_inset Flex Code
8109 \begin_layout Plain Layout
8115 ] This tag indicates that the module in question—which should be specified
8116 by filename without the
8117 \begin_inset Flex Code
8120 \begin_layout Plain Layout
8126 extension—cannot be used with this document class.
8127 This might be used in a journal-specific layout file to prevent, say, the
8129 \begin_inset Flex Code
8132 \begin_layout Plain Layout
8138 module that numbers theorems by section.
8143 be used in a module.
8144 Modules have their own way of excluding other modules (see
8145 \begin_inset CommandInset ref
8147 reference "sub:Layout-modules"
8154 \begin_layout Description
8155 \begin_inset Flex Code
8158 \begin_layout Plain Layout
8164 Defines a new float.
8166 \begin_inset space ~
8170 \begin_inset CommandInset ref
8172 reference "sub:Floats"
8178 \begin_inset Quotes eld
8182 \begin_inset Flex Code
8185 \begin_layout Plain Layout
8192 \begin_inset Quotes erd
8198 \begin_layout Description
8199 \begin_inset Flex Code
8202 \begin_layout Plain Layout
8208 Sets the information that will be output in the
8209 \begin_inset Flex Code
8212 \begin_layout Plain Layout
8218 block when this document class is output to XHTML.
8219 Note that this will completely override any prior
8220 \begin_inset Flex Code
8223 \begin_layout Plain Layout
8230 \begin_inset Flex Code
8233 \begin_layout Plain Layout
8241 \begin_inset Flex Code
8244 \begin_layout Plain Layout
8250 if you just want to add material to the preamble.) Must end with
8251 \begin_inset Quotes eld
8255 \begin_inset Flex Code
8258 \begin_layout Plain Layout
8265 \begin_inset Quotes erd
8271 \begin_layout Description
8272 \begin_inset Flex Code
8275 \begin_layout Plain Layout
8282 \begin_inset Flex Code
8285 \begin_layout Plain Layout
8291 ] The layout to use for the table of contents, bibliography, and so forth,
8292 when the document is output to HTML.
8293 For articles, this should normally be Section; for books, Chapter.
8294 If it is not given, then LyX will attempt to figure out which layout to
8298 \begin_layout Description
8299 \begin_inset Flex Code
8302 \begin_layout Plain Layout
8309 \begin_inset Flex Code
8312 \begin_layout Plain Layout
8318 ] Modifies the properties of the given counter.
8319 If the counter does not exist, the section is ignored.
8321 \begin_inset Quotes eld
8325 \begin_inset Flex Code
8328 \begin_layout Plain Layout
8335 \begin_inset Quotes erd
8339 \begin_inset Newline newline
8343 \begin_inset space ~
8347 \begin_inset CommandInset ref
8349 reference "sub:Counters"
8353 for details on counters.
8356 \begin_layout Description
8357 \begin_inset Flex Code
8360 \begin_layout Plain Layout
8367 \begin_inset Flex Code
8370 \begin_layout Plain Layout
8376 ] Modifies the properties of the given paragraph style.
8377 If the style does not exist, the section is ignored.
8379 \begin_inset Quotes eld
8383 \begin_inset Flex Code
8386 \begin_layout Plain Layout
8393 \begin_inset Quotes erd
8399 \begin_layout Description
8400 \begin_inset Flex Code
8403 \begin_layout Plain Layout
8409 As its name implies, this command allows you to include another layout
8410 definition file within yours to avoid duplicating commands.
8411 Common examples are the standard layout files, for example,
8412 \begin_inset Flex Code
8415 \begin_layout Plain Layout
8421 , which contains most of the basic layouts.
8424 \begin_layout Description
8425 \begin_inset Flex Code
8428 \begin_layout Plain Layout
8434 This section (re-)defines the layout of an inset.
8435 It can be applied to an existing inset or to a new, user-defined inset,
8436 e.g., a new character style.
8438 \begin_inset Quotes eld
8442 \begin_inset Flex Code
8445 \begin_layout Plain Layout
8452 \begin_inset Quotes erd
8456 \begin_inset Newline newline
8460 \begin_inset space ~
8464 \begin_inset CommandInset ref
8466 reference "sub:Flex-insets-and"
8470 for more information.
8474 \begin_layout Description
8475 \begin_inset Flex Code
8478 \begin_layout Plain Layout
8485 \begin_inset Flex Code
8488 \begin_layout Plain Layout
8494 ] A string that indicates the width of the left margin on the screen, for
8496 \begin_inset Quotes eld
8500 \begin_inset Quotes erd
8504 (Note that this is not a `length', like
8505 \begin_inset Quotes eld
8509 \begin_inset Quotes erd
8515 \begin_layout Description
8516 \begin_inset Flex Code
8519 \begin_layout Plain Layout
8526 \begin_inset Flex Code
8529 \begin_layout Plain Layout
8535 ] This command deletes an existing counter, usually one defined in an included
8539 \begin_layout Description
8540 \begin_inset Flex Code
8543 \begin_layout Plain Layout
8549 This command deletes an existing float.
8550 This is particularly useful when you want to suppress a float that has
8551 been defined in an input file.
8554 \begin_layout Description
8555 \begin_inset Flex Code
8558 \begin_layout Plain Layout
8564 This command deletes an existing style.
8565 This is particularly useful when you want to suppress a style that has
8566 be defined in an input file.
8569 \begin_layout Description
8570 \begin_inset Flex Code
8573 \begin_layout Plain Layout
8579 A string indicating the file format (as defined in the Preferences dialog)
8580 produced by this class.
8581 It is mainly useful when
8582 \begin_inset Flex Code
8585 \begin_layout Plain Layout
8591 is `literate' and one wants to define a new type of literate document.
8592 This string is reset to `docbook', `latex', or `literate' when the correspondin
8594 \begin_inset Flex Code
8597 \begin_layout Plain Layout
8603 parameter is encountered.
8606 \begin_layout Description
8607 \begin_inset Flex Code
8610 \begin_layout Plain Layout
8616 A string indicating what sort of output documents using this class will
8618 At present, the options are: `docbook', `latex', and `literate'.
8621 \begin_layout Description
8622 \begin_inset Flex Code
8625 \begin_layout Plain Layout
8632 \begin_inset Flex Code
8635 \begin_layout Plain Layout
8644 \begin_inset Flex Code
8647 \begin_layout Plain Layout
8654 \begin_inset Flex Code
8657 \begin_layout Plain Layout
8663 ] The default pagestyle.
8664 Can be changed in the
8665 \begin_inset Flex MenuItem
8668 \begin_layout Plain Layout
8669 Document\SpecialChar \menuseparator
8678 \begin_layout Description
8679 \begin_inset Flex Code
8682 \begin_layout Plain Layout
8688 Sets the preamble for the LaTeX document.
8689 Note that this will completely override any prior
8690 \begin_inset Flex Code
8693 \begin_layout Plain Layout
8700 \begin_inset Flex Code
8703 \begin_layout Plain Layout
8711 \begin_inset Flex Code
8714 \begin_layout Plain Layout
8720 if you just want to add material to the preamble.) Must end with
8721 \begin_inset Quotes eld
8725 \begin_inset Flex Code
8728 \begin_layout Plain Layout
8735 \begin_inset Quotes erd
8741 \begin_layout Description
8742 \begin_inset Flex Code
8745 \begin_layout Plain Layout
8752 \begin_inset Flex Code
8755 \begin_layout Plain Layout
8762 \begin_inset Flex Code
8765 \begin_layout Plain Layout
8774 \begin_inset Flex Code
8777 \begin_layout Plain Layout
8783 ] Whether the class already provides the feature
8784 \begin_inset Flex Code
8787 \begin_layout Plain Layout
8794 A feature is in general the name of a package (
8795 \begin_inset Flex Code
8798 \begin_layout Plain Layout
8805 \begin_inset Flex Code
8808 \begin_layout Plain Layout
8814 , \SpecialChar \ldots{}
8816 \begin_inset Flex Code
8819 \begin_layout Plain Layout
8826 \begin_inset Flex Code
8829 \begin_layout Plain Layout
8835 ,\SpecialChar \ldots{}
8836 ); the complete list of supported features is unfortunately not documented
8837 outside the LyX source code—but see
8838 \begin_inset Flex Code
8841 \begin_layout Plain Layout
8847 if you're interested.
8849 \begin_inset Flex MenuItem
8852 \begin_layout Plain Layout
8853 Help\SpecialChar \menuseparator
8859 also gives an overview of the supported packages.
8862 \begin_layout Description
8863 \begin_inset Flex Code
8866 \begin_layout Plain Layout
8873 \begin_inset Flex Code
8876 \begin_layout Plain Layout
8882 ] Indicates that this layout provides the functionality of the module mentioned,
8883 which should be specified by the filename without the
8884 \begin_inset Flex Code
8887 \begin_layout Plain Layout
8894 This will typically be used if the layout includes the module directly,
8895 rather than using the
8896 \begin_inset Flex Code
8899 \begin_layout Plain Layout
8905 tag to indicate that it ought to be used.
8906 It could also be used in a module that provided an alternate implementation
8907 of the same functionality.
8910 \begin_layout Description
8911 \begin_inset Flex Code
8914 \begin_layout Plain Layout
8921 \begin_inset Flex Code
8924 \begin_layout Plain Layout
8930 ] Whether the class requires the feature
8931 \begin_inset Flex Code
8934 \begin_layout Plain Layout
8941 Multiple features must be separated by commas.
8942 Note that you can only request supported features.
8944 \begin_inset Flex Code
8947 \begin_layout Plain Layout
8953 for a list of these.)
8956 \begin_layout Description
8957 \begin_inset Flex Code
8960 \begin_layout Plain Layout
8966 A string that indicates the width of the right margin on the screen, for
8968 \begin_inset Quotes eld
8972 \begin_inset Quotes erd
8978 \begin_layout Description
8979 \begin_inset Flex Code
8982 \begin_layout Plain Layout
8988 Sets which divisions get numbered.
8990 \begin_inset Flex Code
8993 \begin_layout Plain Layout
9002 \begin_layout Description
9003 \begin_inset Flex Code
9006 \begin_layout Plain Layout
9013 \begin_inset Flex Code
9016 \begin_layout Plain Layout
9025 \begin_inset Flex Code
9028 \begin_layout Plain Layout
9034 ] Whether the class-default should be printing on one or both sides of the
9036 Can be changed in the
9037 \begin_inset Flex MenuItem
9040 \begin_layout Plain Layout
9041 Document\SpecialChar \menuseparator
9050 \begin_layout Description
9051 \begin_inset Flex Code
9054 \begin_layout Plain Layout
9060 This sequence defines a paragraph style.
9061 If the style does not yet exist, it is created; if it does exist, its parameter
9064 \begin_inset Quotes eld
9068 \begin_inset Flex Code
9071 \begin_layout Plain Layout
9078 \begin_inset Quotes erd
9082 \begin_inset Newline newline
9086 \begin_inset space ~
9090 \begin_inset CommandInset ref
9092 reference "sub:Paragraph-Styles"
9096 for details on paragraph styles.
9099 \begin_layout Description
9100 \begin_inset Flex Code
9103 \begin_layout Plain Layout
9110 \begin_inset Flex Code
9113 \begin_layout Plain Layout
9119 ] The name of the command or environment to be used with
9120 \begin_inset Flex Code
9123 \begin_layout Plain Layout
9132 \begin_layout Description
9133 \begin_inset Flex Code
9136 \begin_layout Plain Layout
9143 \begin_inset Flex Code
9146 \begin_layout Plain Layout
9155 \begin_inset Flex Code
9158 \begin_layout Plain Layout
9164 ] Indicates what kind of markup is used to define the title of a document.
9166 \begin_inset Flex Code
9169 \begin_layout Plain Layout
9175 means that the macro with name
9176 \begin_inset Flex Code
9179 \begin_layout Plain Layout
9185 will be inserted after the last layout which has
9186 \begin_inset Quotes eld
9190 \begin_inset Flex Code
9193 \begin_layout Plain Layout
9200 \begin_inset Quotes erd
9205 \begin_inset Flex Code
9208 \begin_layout Plain Layout
9214 corresponds to the case where the block of paragraphs which have
9215 \begin_inset Quotes eld
9219 \begin_inset Flex Code
9222 \begin_layout Plain Layout
9229 \begin_inset Quotes erd
9232 should be enclosed into the
9233 \begin_inset Flex Code
9236 \begin_layout Plain Layout
9245 \begin_layout Description
9246 \begin_inset Flex Code
9249 \begin_layout Plain Layout
9255 Sets which divisions are included in the table of contents.
9257 \begin_inset Flex Code
9260 \begin_layout Plain Layout
9269 \begin_layout Subsection
9270 \begin_inset Flex Code
9273 \begin_layout Plain Layout
9280 \begin_inset CommandInset label
9282 name "sub:ClassOptions"
9289 \begin_layout Standard
9291 \begin_inset Flex Code
9294 \begin_layout Plain Layout
9300 section can contain the following entries:
9303 \begin_layout Description
9304 \begin_inset Flex Code
9307 \begin_layout Plain Layout
9314 \begin_inset Flex Code
9317 \begin_layout Plain Layout
9323 ] The list of available font sizes for the document's main font, separated
9325 \begin_inset Quotes eld
9329 \begin_inset Flex Code
9332 \begin_layout Plain Layout
9339 \begin_inset Quotes erd
9345 \begin_layout Description
9346 \begin_inset Flex Code
9349 \begin_layout Plain Layout
9355 Used to set the DTD line with XML-based output classes.
9357 \begin_inset space \thinspace{}
9361 \begin_inset Quotes eld
9364 -//OASIS//DTD DocBook V4.2//EN
9365 \begin_inset Quotes erd
9371 \begin_layout Description
9372 \begin_inset Flex Code
9375 \begin_layout Plain Layout
9382 \begin_inset Flex Code
9385 \begin_layout Plain Layout
9386 string="empty|plain|headings|fancy"
9391 ] The list of available page styles, separated by
9392 \begin_inset Quotes eld
9396 \begin_inset Flex Code
9399 \begin_layout Plain Layout
9406 \begin_inset Quotes erd
9412 \begin_layout Description
9413 \begin_inset Flex Code
9416 \begin_layout Plain Layout
9423 \begin_inset Flex Code
9426 \begin_layout Plain Layout
9432 ] Some document class options, separated by a comma, that will be added
9433 to the optional part of the
9434 \begin_inset Flex Code
9437 \begin_layout Plain Layout
9448 \begin_layout Standard
9450 \begin_inset Flex Code
9453 \begin_layout Plain Layout
9459 section must end with
9460 \begin_inset Quotes eld
9464 \begin_inset Flex Code
9467 \begin_layout Plain Layout
9474 \begin_inset Quotes erd
9480 \begin_layout Subsection
9482 \begin_inset CommandInset label
9484 name "sub:Paragraph-Styles"
9491 \begin_layout Standard
9492 A paragraph style description looks like this:
9496 \begin_layout Plain Layout
9497 Note that this will either define a new
9498 \change_deleted 34634807 1296982902
9500 \change_inserted 34634807 1296982902
9503 or modify an existing one.
9511 \begin_layout LyX-Code
9518 \begin_layout LyX-Code
9522 \begin_layout LyX-Code
9526 \begin_layout Standard
9527 where the following commands are allowed:
9530 \begin_layout Description
9531 \begin_inset Flex Code
9534 \begin_layout Plain Layout
9541 \begin_inset Flex Code
9544 \begin_layout Plain Layout
9549 , left, right, center
9554 ] Paragraph alignment.
9557 \begin_layout Description
9558 \begin_inset Flex Code
9561 \begin_layout Plain Layout
9568 \begin_inset Flex Code
9571 \begin_layout Plain Layout
9576 , left, right, center
9581 ] A comma separated list of permitted alignments.
9582 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
9584 For example a right-aligned or centered enumeration isn't possible.)
9587 \begin_layout Description
9588 \begin_inset Flex Code
9591 \begin_layout Plain Layout
9597 Note that this will completely override any prior
9598 \begin_inset Flex Code
9601 \begin_layout Plain Layout
9607 declaration for this style.
9609 \begin_inset Quotes eld
9613 \begin_inset Flex Code
9616 \begin_layout Plain Layout
9623 \begin_inset Quotes erd
9628 \begin_inset CommandInset ref
9630 reference "sub:I18n"
9634 for details on its use.
9637 \begin_layout Description
9638 \begin_inset Flex Code
9641 \begin_layout Plain Layout
9648 \begin_inset Flex Code
9651 \begin_layout Plain Layout
9661 \begin_layout Plain Layout
9662 Note that a `float' here is a real number, such as: 1.5.
9667 The vertical space with which the last of a chain of paragraphs with this
9669 \change_deleted 34634807 1296982906
9671 \change_inserted 34634807 1296982906
9674 is separated from the following paragraph.
9675 If the next paragraph has another
9676 \change_deleted 34634807 1296982915
9678 \change_inserted 34634807 1296982915
9681 , the separations are not simply added, but the maximum is taken.
9684 \begin_layout Description
9685 \begin_inset Flex Code
9688 \begin_layout Plain Layout
9695 \begin_inset Flex Code
9698 \begin_layout Plain Layout
9704 The category for this style.
9705 This is used to group related styles in the
9706 \change_deleted 34634807 1296982925
9708 \change_inserted 34634807 1296982925
9711 combobox on the toolbar.
9712 Any string can be used, but you may want to use existing categories with
9717 \begin_layout Description
9718 \begin_inset Flex Code
9721 \begin_layout Plain Layout
9727 Depth of XML command.
9728 Used only with XML-type formats.
9731 \begin_layout Description
9732 \begin_inset Flex Code
9735 \begin_layout Plain Layout
9742 \begin_inset CommandInset label
9744 name "des:CopyStyle"
9749 \begin_inset Flex Code
9752 \begin_layout Plain Layout
9758 Copies all the features of an existing style into the current one.
9762 \begin_layout Description
9763 \begin_inset Flex Code
9766 \begin_layout Plain Layout
9772 The name of a style whose preamble should be output
9777 This allows to ensure some ordering of the preamble snippets when macros
9778 definitions depend on one another.
9782 \begin_layout Plain Layout
9783 Note that, besides that functionality, there is no way to ensure any ordering
9785 The ordering that you see in a given version of LyX may change without
9786 warning in later versions.
9794 \begin_layout Description
9795 \begin_inset Flex Code
9798 \begin_layout Plain Layout
9805 \begin_inset Flex Code
9808 \begin_layout Plain Layout
9813 , Box, Filled_Box, Static
9818 ] The type of label that stands at the end of the paragraph (or sequence
9820 \begin_inset Flex Code
9823 \begin_layout Plain Layout
9830 \begin_inset Flex Code
9833 \begin_layout Plain Layout
9840 \begin_inset Flex Code
9843 \begin_layout Plain Layout
9850 \begin_inset Flex Code
9853 \begin_layout Plain Layout
9861 \begin_inset Flex Code
9864 \begin_layout Plain Layout
9871 \begin_inset Quotes eld
9875 \begin_inset Quotes erd
9879 \begin_inset Flex Code
9882 \begin_layout Plain Layout
9889 \begin_inset Flex Code
9892 \begin_layout Plain Layout
9893 \begin_inset space ~
9902 \begin_inset space ~
9905 black) square suitable for end of proof markers,
9906 \begin_inset Flex Code
9909 \begin_layout Plain Layout
9915 is an explicit text string.
9918 \begin_layout Description
9919 \begin_inset Flex Code
9922 \begin_layout Plain Layout
9929 \begin_inset Flex Code
9932 \begin_layout Plain Layout
9938 ] The string used for a label with a
9939 \begin_inset Flex Code
9942 \begin_layout Plain Layout
9949 \begin_inset Flex Code
9952 \begin_layout Plain Layout
9962 \begin_layout Description
9964 \change_deleted 34634807 1296982079
9965 \begin_inset Flex Code
9968 \begin_layout Plain Layout
9975 \begin_inset Flex Code
9978 \begin_layout Plain Layout
9989 \begin_inset Flex Code
9992 \begin_layout Plain Layout
10001 \begin_layout Description
10003 \change_deleted 34634807 1296982079
10004 \begin_inset Flex Code
10007 \begin_layout Plain Layout
10014 \begin_inset Flex Code
10017 \begin_layout Plain Layout
10027 ] With this parameter the
10028 \begin_inset Flex MenuItem
10031 \begin_layout Plain Layout
10038 \begin_inset Quotes eld
10041 Vertical space above
10042 \begin_inset Quotes erd
10046 \begin_inset Flex MenuItem
10049 \begin_layout Plain Layout
10050 Edit\SpecialChar \menuseparator
10052 \begin_inset space ~
10060 dialog can be set when initializing a paragraph with this style.
10066 \begin_layout Plain Layout
10069 Note from Jean-Marc:
10071 I'm not sure that this setting has much use, and it should probably be
10072 removed in later versions.
10078 \change_inserted 34634807 1296982107
10080 \begin_inset Note Note
10083 \begin_layout Plain Layout
10085 \change_inserted 34634807 1296982125
10087 \begin_inset Quotes eld
10090 Vertical space above
10091 \begin_inset Quotes erd
10095 \begin_inset Quotes eld
10098 Vertical space below
10099 \begin_inset Quotes erd
10102 in Edit\SpecialChar \menuseparator
10104 \begin_inset space ~
10107 Settings, so this seems obsolete, as Jean-Marc noticed (Note by J.P.
10119 \begin_layout Description
10120 \begin_inset Flex Code
10123 \begin_layout Plain Layout
10129 The font used for both the text body
10135 \begin_inset space ~
10139 \begin_inset CommandInset ref
10141 reference "sub:Font-description"
10146 Note that defining this font automatically defines the
10147 \begin_inset Flex Code
10150 \begin_layout Plain Layout
10157 So you should define this one first if you also want to define
10158 \begin_inset Flex Code
10161 \begin_layout Plain Layout
10170 \begin_layout Description
10171 \begin_inset Flex Code
10174 \begin_layout Plain Layout
10181 \begin_inset CommandInset label
10183 name "des:FreeSpacing"
10188 \begin_inset Flex Code
10191 \begin_layout Plain Layout
10200 \begin_inset Flex Code
10203 \begin_layout Plain Layout
10209 ] Usually LyX doesn't allow you to insert more than one space between words,
10210 since a space is considered as the separation between two words, not a
10211 character or symbol of its own.
10212 This is a very fine thing but sometimes annoying, for example, when typing
10213 program code or plain LaTeX code.
10215 \begin_inset Flex Code
10218 \begin_layout Plain Layout
10225 Note that LyX will create protected blanks for the additional blanks when
10226 in another mode than LaTeX-mode.
10229 \begin_layout Description
10230 \begin_inset Flex Code
10233 \begin_layout Plain Layout
10239 These tags are used with XHTML output.
10241 \begin_inset CommandInset ref
10243 reference "sub:Paragraph-Style-XHTML"
10250 \begin_layout Description
10251 \begin_inset Flex Code
10254 \begin_layout Plain Layout
10260 [[FIXME]] (Used only with XML-type formats.)
10263 \begin_layout Description
10264 \begin_inset Flex Code
10267 \begin_layout Plain Layout
10274 \begin_inset Flex Code
10277 \begin_layout Plain Layout
10284 \change_deleted 34634807 1296982928
10286 \change_inserted 34634807 1296982928
10289 as to be included in the document preamble rather than in the document
10291 This is useful for document classes that want such information as the title
10292 and author to appear in the preamble.
10293 Note that this works only for
10294 \change_deleted 34634807 1296982930
10296 \change_inserted 34634807 1296982930
10300 \begin_inset Flex Code
10303 \begin_layout Plain Layout
10310 \begin_inset Flex Code
10313 \begin_layout Plain Layout
10320 \begin_inset Flex Code
10323 \begin_layout Plain Layout
10332 \begin_layout Description
10333 \begin_inset Flex Code
10336 \begin_layout Plain Layout
10343 \begin_inset Flex Code
10346 \begin_layout Plain Layout
10353 \change_deleted 34634807 1296982932
10355 \change_inserted 34634807 1296982932
10358 as being part of a title block (see also the
10359 \begin_inset Flex Code
10362 \begin_layout Plain Layout
10369 \begin_inset Flex Code
10372 \begin_layout Plain Layout
10381 \begin_layout Description
10382 \begin_inset Flex Code
10385 \begin_layout Plain Layout
10392 \begin_inset Flex Code
10395 \begin_layout Plain Layout
10401 ] This provides extra space between paragraphs that have the same
10402 \change_deleted 34634807 1296982933
10404 \change_inserted 34634807 1296982933
10409 \change_deleted 34634807 1296982940
10411 \change_inserted 34634807 1296982940
10414 s into an environment, each is separated with the environment's
10415 \begin_inset Flex Code
10418 \begin_layout Plain Layout
10425 But the whole items of the environment are additionally separated with
10427 \begin_inset Flex Code
10430 \begin_layout Plain Layout
10437 Note that this is a
10442 \begin_layout Description
10443 \begin_inset Flex Code
10446 \begin_layout Plain Layout
10452 [[FIXME]] (Used only with XML-type formats.)
10455 \begin_layout Description
10456 \begin_inset Flex Code
10459 \begin_layout Plain Layout
10466 \begin_inset CommandInset label
10468 name "des:KeepEmpty"
10473 \begin_inset Flex Code
10476 \begin_layout Plain Layout
10485 \begin_inset Flex Code
10488 \begin_layout Plain Layout
10494 ] Usually LyX does not allow you to leave a paragraph empty, since it would
10495 lead to empty LaTeX output.
10496 There are some cases where this could be desirable however: in a letter
10497 template, the required fields can be provided as empty fields, so that
10498 people do not forget them; in some special classes, a
10499 \change_deleted 34634807 1296982945
10501 \change_inserted 34634807 1296982945
10504 can be used as some kind of break, which does not contain actual text.
10507 \begin_layout Description
10508 \begin_inset Flex Code
10511 \begin_layout Plain Layout
10517 [float=0] The vertical space between the label and the text body.
10518 Only used for labels that are above the text body (
10519 \begin_inset Flex Code
10522 \begin_layout Plain Layout
10529 \begin_inset Flex Code
10532 \begin_layout Plain Layout
10533 Centered_Top_Environment
10541 \begin_layout Description
10542 \begin_inset Flex Code
10545 \begin_layout Plain Layout
10552 \begin_inset Flex Code
10555 \begin_layout Plain Layout
10562 \begin_inset Newline newline
10565 The name of the counter for automatic numbering.
10567 \begin_inset Newline newline
10575 \begin_inset Flex Code
10578 \begin_layout Plain Layout
10585 \begin_inset Flex Code
10588 \begin_layout Plain Layout
10595 In that case, the counter will be stepped each time the
10596 \change_deleted 34634807 1296982948
10598 \change_inserted 34634807 1296982948
10603 \begin_inset Newline newline
10611 \begin_inset Flex Code
10614 \begin_layout Plain Layout
10621 \begin_inset Flex Code
10624 \begin_layout Plain Layout
10630 , though this case is a bit complicated.
10631 Suppose you declare
10632 \begin_inset Quotes eld
10636 \begin_inset Flex Code
10639 \begin_layout Plain Layout
10640 LabelCounter myenum
10646 \begin_inset Quotes erd
10650 Then the actual counters used are
10651 \begin_inset Flex Code
10654 \begin_layout Plain Layout
10661 \begin_inset Flex Code
10664 \begin_layout Plain Layout
10671 \begin_inset Flex Code
10674 \begin_layout Plain Layout
10681 \begin_inset Flex Code
10684 \begin_layout Plain Layout
10690 , much as in LaTeX.
10691 These counters must all be declared separately.
10692 \begin_inset Newline newline
10696 \begin_inset CommandInset ref
10698 reference "sub:Counters"
10702 for details on counters.
10705 \begin_layout Description
10706 \begin_inset Flex Code
10709 \begin_layout Plain Layout
10715 The font used for the label.
10717 \begin_inset space ~
10721 \begin_inset CommandInset ref
10723 reference "sub:Font-description"
10730 \begin_layout Description
10731 \begin_inset Flex Code
10734 \begin_layout Plain Layout
10740 Text that indicates how far a label should be indented.
10743 \begin_layout Description
10744 \begin_inset Flex Code
10747 \begin_layout Plain Layout
10754 \begin_inset Flex Code
10757 \begin_layout Plain Layout
10763 ] The horizontal space between the label and the text body.
10764 Only used for labels that are not above the text body.
10767 \begin_layout Description
10768 \begin_inset Flex Code
10771 \begin_layout Plain Layout
10778 \begin_inset Flex Code
10781 \begin_layout Plain Layout
10787 ] The string used for a label with a
10788 \begin_inset Flex Code
10791 \begin_layout Plain Layout
10799 \begin_inset Flex Code
10802 \begin_layout Plain Layout
10808 is set, this string can be contain the special formatting commands described
10810 \begin_inset CommandInset ref
10812 reference "sub:Counters"
10820 \begin_layout Plain Layout
10821 For the sake of backwards compatibility, the string
10822 \begin_inset Flex Code
10825 \begin_layout Plain Layout
10835 will be replaced by the expanded
10836 \begin_inset Flex Code
10839 \begin_layout Plain Layout
10846 \begin_inset Flex Code
10849 \begin_layout Plain Layout
10858 This feature is now obsolete and should be replaced by the mechanisms of
10860 \begin_inset CommandInset ref
10862 reference "sub:Counters"
10874 \begin_layout Description
10875 \begin_inset Flex Code
10878 \begin_layout Plain Layout
10879 LabelStringAppendix
10885 \begin_inset Flex Code
10888 \begin_layout Plain Layout
10894 ] This is used inside the appendix instead of
10895 \begin_inset Flex Code
10898 \begin_layout Plain Layout
10906 \begin_inset Flex Code
10909 \begin_layout Plain Layout
10916 \begin_inset Flex Code
10919 \begin_layout Plain Layout
10920 LabelStringAppendix
10928 \begin_layout Description
10929 \begin_inset Flex Code
10932 \begin_layout Plain Layout
10938 [FIXME] (Used only with XML-type formats.)
10941 \begin_layout Description
10942 \begin_inset Flex Code
10945 \begin_layout Plain Layout
10952 \begin_inset Flex Code
10955 \begin_layout Plain Layout
10960 , Manual, Static, Top_Environment, Centered_Top_Environment, Counter, Sensitive,
10961 Enumerate, Itemize, Bibliography
10970 \begin_layout Itemize
10971 \begin_inset Flex Code
10974 \begin_layout Plain Layout
10980 means the label is the very first word (up to the first real blank).
10981 Use protected spaces (like
10982 \begin_inset space ~
10985 that one) if you want more than one word as the label.
10989 \begin_layout Itemize
10990 \begin_inset Flex Code
10993 \begin_layout Plain Layout
10999 means the label is simply whatever
11000 \begin_inset Flex Code
11003 \begin_layout Plain Layout
11010 Note that this really is `static'.
11013 \begin_layout Itemize
11014 \begin_inset Flex Code
11017 \begin_layout Plain Layout
11024 \begin_inset Flex Code
11027 \begin_layout Plain Layout
11028 Centered_Top_Environment
11033 are special cases of
11034 \begin_inset Flex Code
11037 \begin_layout Plain Layout
11044 The label will be printed above the paragraph, but only at the top of an
11045 environment or the top of a chain of paragraphs with this
11046 \change_deleted 34634807 1296982950
11048 \change_inserted 34634807 1296982950
11052 This might be used with the
11053 \begin_inset Flex MenuItem
11056 \begin_layout Plain Layout
11063 \change_deleted 34634807 1296982953
11065 \change_inserted 34634807 1296982953
11071 \begin_layout Itemize
11072 \begin_inset Flex Code
11075 \begin_layout Plain Layout
11081 is a special case for the caption-labels
11082 \begin_inset Quotes eld
11086 \begin_inset Quotes erd
11090 \begin_inset Quotes eld
11094 \begin_inset Quotes erd
11099 \begin_inset Flex Code
11102 \begin_layout Plain Layout
11108 means the (hardcoded) label string depends on the kind of float: It is
11109 hardcoded to be `FloatType N', where N is the value of the counter associated
11113 \begin_layout Itemize
11115 \begin_inset Flex Code
11118 \begin_layout Plain Layout
11124 label type defines automatically numbered labels.
11126 \begin_inset Flex Code
11129 \begin_layout Plain Layout
11135 will be expanded to resolve any counter references it contains: For example,
11137 \begin_inset Quotes eld
11141 \begin_inset Flex Code
11144 \begin_layout Plain Layout
11155 \begin_inset Quotes erd
11160 \begin_inset CommandInset ref
11162 reference "sub:Counters"
11166 for more information on counters.
11169 \begin_layout Itemize
11170 \begin_inset Flex Code
11173 \begin_layout Plain Layout
11179 produces the usual sort of enumeration labels.
11180 At present, it is hardcoded to use Arabic numerals, lowercase letters,
11181 small Roman numerals, and uppercase letters for the four possible depths.
11184 \begin_layout Itemize
11185 \begin_inset Flex Code
11188 \begin_layout Plain Layout
11194 produces various bullets at the different levels.
11195 It is also hardcoded.
11198 \begin_layout Itemize
11199 \begin_inset Flex Code
11202 \begin_layout Plain Layout
11208 is used internally by LyX and should be used only with
11209 \begin_inset Flex Code
11212 \begin_layout Plain Layout
11213 LatexType BibEnvironment
11222 \begin_layout Description
11223 \begin_inset Flex Code
11226 \begin_layout Plain Layout
11232 Note that this will completely override any prior
11233 \begin_inset Flex Code
11236 \begin_layout Plain Layout
11242 declaration for this style.
11244 \begin_inset Quotes eld
11248 \begin_inset Flex Code
11251 \begin_layout Plain Layout
11258 \begin_inset Quotes erd
11263 \begin_inset CommandInset ref
11265 reference "sub:I18n"
11269 for details on its use.
11272 \begin_layout Description
11273 \begin_inset Flex Code
11276 \begin_layout Plain Layout
11282 The name of the corresponding LaTeX stuff.
11283 Either the environment or command name.
11286 \begin_layout Description
11287 \begin_inset Flex Code
11290 \begin_layout Plain Layout
11296 An optional parameter for the corresponding
11297 \begin_inset Flex Code
11300 \begin_layout Plain Layout
11307 This parameter cannot be changed from within LyX.
11310 \begin_layout Description
11311 \begin_inset Flex Code
11314 \begin_layout Plain Layout
11321 \begin_inset CommandInset label
11323 name "des:LatexType"
11328 \begin_inset Flex Code
11331 \begin_layout Plain Layout
11336 , Command, Environment, Item_Environment,
11342 \begin_inset Flex Code
11345 \begin_layout Plain Layout
11346 List_Environment, Bib_Environment
11352 \change_deleted 34634807 1296982955
11354 \change_inserted 34634807 1296982955
11357 should be translated into LaTeX.
11361 \begin_layout Plain Layout
11362 \begin_inset Flex Code
11365 \begin_layout Plain Layout
11371 is perhaps a bit misleading, since these rules apply to SGML classes, too.
11372 Visit the SGML class files for specific examples.
11381 \begin_layout Itemize
11382 \begin_inset Flex Code
11385 \begin_layout Plain Layout
11391 means nothing special.
11395 \begin_layout Itemize
11396 \begin_inset Flex Code
11399 \begin_layout Plain Layout
11406 \begin_inset Flex Code
11409 \begin_layout Plain Layout
11416 {\SpecialChar \ldots{}
11425 \begin_layout Itemize
11426 \begin_inset Flex Code
11429 \begin_layout Plain Layout
11436 \begin_inset Flex Code
11439 \begin_layout Plain Layout
11446 }\SpecialChar \ldots{}
11462 \begin_layout Itemize
11463 \begin_inset Flex Code
11466 \begin_layout Plain Layout
11473 \begin_inset Flex Code
11476 \begin_layout Plain Layout
11483 \begin_inset Flex Code
11486 \begin_layout Plain Layout
11494 is generated for each paragraph of this environment.
11498 \begin_layout Itemize
11499 \begin_inset Flex Code
11502 \begin_layout Plain Layout
11509 \begin_inset Flex Code
11512 \begin_layout Plain Layout
11519 \begin_inset Flex Code
11522 \begin_layout Plain Layout
11528 is passed as an argument to the environment.
11530 \begin_inset Flex Code
11533 \begin_layout Plain Layout
11539 can be defined in the
11540 \begin_inset Flex MenuItem
11543 \begin_layout Plain Layout
11545 \change_deleted 34634807 1296982208
11551 \change_inserted 34634807 1296982209
11558 \SpecialChar \menuseparator
11564 \change_inserted 34634807 1296982216
11566 \begin_inset space ~
11580 \begin_layout Standard
11581 Putting the last few things together, the LaTeX output will be either:
11584 \begin_layout LyX-Code
11587 latexname[latexparam]{\SpecialChar \ldots{}
11591 \begin_layout Standard
11595 \begin_layout LyX-Code
11598 begin{latexname}[latexparam] \SpecialChar \ldots{}
11604 \begin_layout Standard
11605 depending upon the LaTeX type.
11609 \begin_layout Description
11610 \begin_inset Flex Code
11613 \begin_layout Plain Layout
11620 \begin_inset Flex Code
11623 \begin_layout Plain Layout
11630 \change_deleted 34634807 1296982960
11632 \change_inserted 34634807 1296982960
11635 s into environments, the leftmargins are not simply added, but added with
11637 \begin_inset Formula $\frac{4}{depth+4}$
11641 Note that this parameter is also used when the margin is defined as
11642 \begin_inset Flex Code
11645 \begin_layout Plain Layout
11652 \begin_inset Flex Code
11655 \begin_layout Plain Layout
11662 Then it is added to the manual or dynamic margin.
11664 \begin_inset Newline newline
11667 The argument is passed as a string.
11669 \begin_inset Quotes eld
11673 \begin_inset Flex Code
11676 \begin_layout Plain Layout
11683 \begin_inset Quotes erd
11686 means that the paragraph is indented with the width of
11687 \begin_inset Quotes eld
11691 \begin_inset Flex Code
11694 \begin_layout Plain Layout
11701 \begin_inset Quotes erd
11704 in the normal font.
11705 You can get a negative width by prefixing the string with
11706 \begin_inset Quotes eld
11710 \begin_inset Flex Code
11713 \begin_layout Plain Layout
11720 \begin_inset Quotes erd
11724 This way was chosen so that the look is the same with each used screen
11729 \begin_layout Description
11730 \begin_inset Flex Code
11733 \begin_layout Plain Layout
11740 \begin_inset Flex Code
11743 \begin_layout Plain Layout
11748 , Manual, Dynamic, First_Dynamic, Right_Address_Box
11754 \begin_inset Newline newline
11757 The kind of margin that the
11758 \change_deleted 34634807 1296982962
11760 \change_inserted 34634807 1296982962
11763 has on the left side.
11765 \begin_inset Flex Code
11768 \begin_layout Plain Layout
11774 just means a fixed margin.
11776 \begin_inset Flex Code
11779 \begin_layout Plain Layout
11785 means that the left margin depends on the string entered in the
11786 \begin_inset Flex MenuItem
11789 \begin_layout Plain Layout
11790 Edit\SpecialChar \menuseparator
11792 \begin_inset space ~
11801 This is used to typeset nice lists without tabulators.
11803 \begin_inset Flex Code
11806 \begin_layout Plain Layout
11812 means that the margin depends on the size of the label.
11813 This is used for automatic enumerated headlines.
11814 It is obvious that the headline
11815 \begin_inset Quotes eld
11818 5.4.3.2.1 Very long headline
11819 \begin_inset Quotes erd
11822 must have a wider left margin (as wide as
11823 \begin_inset Quotes eld
11827 \begin_inset Quotes erd
11830 plus the space) than
11831 \begin_inset Quotes eld
11834 3.2 Very long headline
11835 \begin_inset Quotes erd
11839 \begin_inset Quotes eld
11843 \begin_inset Quotes erd
11846 are not able to do this.
11848 \begin_inset Flex Code
11851 \begin_layout Plain Layout
11857 is similar, but only the very first row of the paragraph is dynamic, while
11858 the others are static; this is used, for example, for descriptions.
11860 \begin_inset Flex Code
11863 \begin_layout Plain Layout
11869 means the margin is chosen in a way that the longest row of this paragraph
11870 fits to the right margin.
11871 This is used to typeset an address on the right edge of the page.
11874 \begin_layout Description
11875 \begin_inset Flex Code
11878 \begin_layout Plain Layout
11885 \begin_inset Flex Code
11888 \begin_layout Plain Layout
11897 \begin_inset Flex Code
11900 \begin_layout Plain Layout
11906 ] Whether fragile commands in this
11907 \change_deleted 34634807 1296982964
11909 \change_inserted 34634807 1296982964
11913 \begin_inset Flex Code
11916 \begin_layout Plain Layout
11929 whether this command should itself be protected.)
11932 \begin_layout Description
11933 \begin_inset Flex Code
11936 \begin_layout Plain Layout
11943 \begin_inset Flex Code
11946 \begin_layout Plain Layout
11953 \begin_inset Flex Code
11956 \begin_layout Plain Layout
11964 ] Whether newlines are translated into LaTeX newlines (
11965 \begin_inset Flex Code
11968 \begin_layout Plain Layout
11979 The translation can be switched off to allow more comfortable LaTeX editing
11983 \begin_layout Description
11984 \begin_inset Flex Code
11987 \begin_layout Plain Layout
11994 \begin_inset Flex Code
11997 \begin_layout Plain Layout
12004 \begin_inset Flex Code
12007 \begin_layout Plain Layout
12015 ] Whether the following Paragraph is allowed to indent its very first row.
12017 \begin_inset Flex Code
12020 \begin_layout Plain Layout
12026 means that it is not allowed to do so;
12027 \begin_inset Flex Code
12030 \begin_layout Plain Layout
12036 means it could do so if it wants to.
12039 \begin_layout Description
12040 \begin_inset Flex Code
12043 \begin_layout Plain Layout
12050 \change_deleted 34634807 1296982966
12052 \change_inserted 34634807 1296982966
12055 that has replaced this
12056 \change_deleted 34634807 1296982967
12058 \change_inserted 34634807 1296982967
12062 This is used to rename a
12063 \change_deleted 34634807 1296982969
12065 \change_inserted 34634807 1296982969
12068 , while keeping backward compatibility.
12071 \begin_layout Description
12072 \begin_inset Flex Code
12075 \begin_layout Plain Layout
12082 \begin_inset Flex Code
12085 \begin_layout Plain Layout
12091 ] The number of optional arguments that can be used with this
12092 \change_deleted 34634807 1296982970
12094 \change_inserted 34634807 1296982970
12098 This is useful for things like section headings, and only makes sense with
12100 Note that, on output, the optional arguments will all precede any required
12101 arguments (see below).
12102 So one can have constructs like:
12106 \begin_layout LyX-Code
12109 mycmd[opt1]{req1}{contents of paragraph}
12112 \begin_layout Standard
12113 but one cannot have things like:
12116 \begin_layout LyX-Code
12119 mycmd[opt1]{req1}[opt2]{contents of paragraph}
12122 \begin_layout Standard
12123 at least, not without ERT (with which you can have anything).
12128 \begin_layout Description
12129 \begin_inset Flex Code
12132 \begin_layout Plain Layout
12139 \begin_inset CommandInset label
12141 name "des:ParbreakIsNewline"
12146 \begin_inset Flex Code
12149 \begin_layout Plain Layout
12158 \begin_inset Flex Code
12161 \begin_layout Plain Layout
12167 ] Indicates that paragraphs will not be separated by an empty line in LaTeX
12168 output, but only by a line break; together with
12169 \begin_inset Flex Code
12172 \begin_layout Plain Layout
12178 , this allows to emulate a plain text editor (like the ERT inset).
12181 \begin_layout Description
12182 \begin_inset Flex Code
12185 \begin_layout Plain Layout
12192 \begin_inset Flex Code
12195 \begin_layout Plain Layout
12201 ] The indent of the very first line of a paragraph.
12203 \begin_inset Flex Code
12206 \begin_layout Plain Layout
12212 will be fixed for a certain
12213 \change_deleted 34634807 1296982972
12215 \change_inserted 34634807 1296982972
12220 \change_deleted 34634807 1296982262
12222 \change_inserted 34634807 1296982262
12224 \begin_inset Flex Code
12227 \begin_layout Plain Layout
12229 \change_inserted 34634807 1296982262
12240 \change_deleted 34634807 1296982974
12242 \change_inserted 34634807 1296982974
12245 , since the indentation of a
12246 \change_deleted 34634807 1296982283
12248 \change_inserted 34634807 1296982283
12250 \begin_inset Flex Code
12253 \begin_layout Plain Layout
12255 \change_inserted 34634807 1296982283
12266 \change_deleted 34634807 1296982976
12268 \change_inserted 34634807 1296982976
12271 paragraph can be prohibited with
12272 \begin_inset Flex Code
12275 \begin_layout Plain Layout
12283 \change_deleted 34634807 1296982295
12285 \change_inserted 34634807 1296982295
12287 \begin_inset Flex Code
12290 \begin_layout Plain Layout
12292 \change_inserted 34634807 1296982295
12303 \change_deleted 34634807 1296982977
12305 \change_inserted 34634807 1296982977
12308 paragraphs inside environments use the
12309 \begin_inset Flex Code
12312 \begin_layout Plain Layout
12318 of the environment, not their native one.
12320 \change_deleted 34634807 1296982308
12322 \change_inserted 34634807 1296982308
12324 \begin_inset Flex Code
12327 \begin_layout Plain Layout
12329 \change_inserted 34634807 1296982308
12339 paragraphs inside an enumeration are not indented.
12342 \begin_layout Description
12343 \begin_inset Flex Code
12346 \begin_layout Plain Layout
12353 \begin_inset Flex Code
12356 \begin_layout Plain Layout
12362 ] The vertical space between two paragraphs of this
12363 \change_deleted 34634807 1296982979
12365 \change_inserted 34634807 1296982979
12371 \begin_layout Description
12372 \begin_inset Flex Code
12375 \begin_layout Plain Layout
12382 \begin_inset Flex Code
12385 \begin_layout Plain Layout
12391 ] LyX allows the user to choose either
12392 \begin_inset Quotes eld
12396 \begin_inset Quotes erd
12400 \begin_inset Quotes eld
12404 \begin_inset Quotes erd
12407 to typeset a document.
12409 \begin_inset Quotes eld
12413 \begin_inset Quotes erd
12416 is chosen, this value is completely ignored.
12418 \begin_inset Quotes eld
12422 \begin_inset Quotes erd
12425 is chosen, the parindent of a LaTeXtype
12426 \begin_inset Quotes eld
12430 \begin_inset Quotes erd
12434 \change_deleted 34634807 1296982981
12436 \change_inserted 34634807 1296982981
12439 is ignored and all paragraphs are separated by this parskip argument.
12440 The vertical space is calculated with
12441 \begin_inset Flex Code
12444 \begin_layout Plain Layout
12446 \begin_inset space ~
12455 \begin_inset Flex Code
12458 \begin_layout Plain Layout
12464 is the height of a row with the normal font.
12465 This way, the look stays the same with different screen fonts.
12468 \begin_layout Description
12469 \begin_inset Flex Code
12472 \begin_layout Plain Layout
12479 \begin_inset CommandInset label
12481 name "des:PassThru"
12486 \begin_inset Flex Code
12489 \begin_layout Plain Layout
12498 \begin_inset Flex Code
12501 \begin_layout Plain Layout
12507 ] Whether the contents of this paragraph should be output in raw form, meaning
12508 without special translations that LaTeX would require.
12511 \begin_layout Description
12512 \begin_inset Flex Code
12515 \begin_layout Plain Layout
12522 \begin_inset CommandInset label
12524 name "des:Preamble"
12528 Information to be included in the LaTeX preamble when this style is used.
12529 Used to define macros, load packages, etc., required by this particular
12532 \begin_inset Quotes eld
12536 \begin_inset Flex Code
12539 \begin_layout Plain Layout
12546 \begin_inset Quotes erd
12552 \begin_layout Description
12553 \begin_inset Flex Code
12556 \begin_layout Plain Layout
12563 \begin_inset Flex Code
12566 \begin_layout Plain Layout
12572 ] The prefix to use when creating labels referring to paragraphs of this
12574 This allows the use of formatted references.
12577 \begin_layout Description
12578 \begin_inset Flex Code
12581 \begin_layout Plain Layout
12588 \begin_inset Flex Code
12591 \begin_layout Plain Layout
12597 ] The number of required arguments that the LaTeX command or environment
12598 corresponding to this
12599 \change_deleted 34634807 1296982982
12601 \change_inserted 34634807 1296982982
12605 In the case of a command, these are required arguments
12609 that associated with the content of the paragraph itself.
12610 These do not actually have to be provided: LyX will output empty arguments
12612 Note that optional arguments will be output before required arguments.
12613 See the discussion of the
12614 \begin_inset Flex Code
12617 \begin_layout Plain Layout
12623 tag above for more information.
12626 \begin_layout Description
12627 \begin_inset Flex Code
12630 \begin_layout Plain Layout
12637 \begin_inset Flex Code
12640 \begin_layout Plain Layout
12647 \begin_inset CommandInset label
12649 name "des:Requires"
12654 \change_deleted 34634807 1296982984
12656 \change_inserted 34634807 1296982984
12659 requires the feature
12660 \begin_inset Flex Code
12663 \begin_layout Plain Layout
12670 See the description of
12671 \begin_inset Flex Code
12674 \begin_layout Plain Layout
12681 \begin_inset CommandInset ref
12682 LatexCommand pageref
12683 reference "des:FreeSpacing"
12687 ) for information on `features'.
12691 \begin_layout Description
12692 \begin_inset Flex Code
12695 \begin_layout Plain Layout
12702 \begin_inset Flex Code
12705 \begin_layout Plain Layout
12712 \begin_inset Flex Code
12715 \begin_layout Plain Layout
12724 \begin_layout Description
12725 \begin_inset Flex Code
12728 \begin_layout Plain Layout
12735 \begin_inset Flex Code
12738 \begin_layout Plain Layout
12743 , onehalf, double, other
12752 ] This defines what the default spacing should be in the
12753 \change_deleted 34634807 1296982985
12755 \change_inserted 34634807 1296982985
12760 \begin_inset Flex Code
12763 \begin_layout Plain Layout
12770 \begin_inset Flex Code
12773 \begin_layout Plain Layout
12780 \begin_inset Flex Code
12783 \begin_layout Plain Layout
12789 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
12790 If you specify the argument
12791 \begin_inset Flex Code
12794 \begin_layout Plain Layout
12800 , then you should also provide a numerical argument which will be the actual
12802 Note that, contrary to other parameters,
12803 \begin_inset Flex Code
12806 \begin_layout Plain Layout
12812 implies the generation of specific LaTeX code, using the package
12815 \begin_inset Flex Code
12818 \begin_layout Plain Layout
12827 \begin_layout Description
12828 \begin_inset Flex Code
12831 \begin_layout Plain Layout
12838 \begin_inset Flex Code
12841 \begin_layout Plain Layout
12848 \begin_inset Flex Code
12851 \begin_layout Plain Layout
12859 ] Spellcheck paragraphs of this style.
12863 \begin_layout Description
12864 \begin_inset Flex Code
12867 \begin_layout Plain Layout
12873 The font used for the text body .
12875 \begin_inset CommandInset ref
12877 reference "sub:Font-description"
12884 \begin_layout Description
12885 \begin_inset Flex Code
12888 \begin_layout Plain Layout
12897 \begin_inset Flex Code
12900 \begin_layout Plain Layout
12910 The level of the style in the table of contents.
12911 This is used for automatic numbering of section headings.
12914 \begin_layout Description
12915 \begin_inset Flex Code
12918 \begin_layout Plain Layout
12925 \begin_inset Flex Code
12928 \begin_layout Plain Layout
12934 ] The vertical space with which the very first of a chain of paragraphs
12936 \change_deleted 34634807 1296982986
12938 \change_inserted 34634807 1296982986
12941 is separated from the previous paragraph.
12942 If the previous paragraph has another
12943 \change_deleted 34634807 1296982988
12945 \change_inserted 34634807 1296982988
12948 , the separations are not simply added, but the maximum is taken.
12951 \begin_layout Subsection
12952 \begin_inset CommandInset label
12958 Internationalization of Paragraph Styles
12961 \begin_layout Standard
12962 LyX has long supported internationalization of layout information, but,
12963 until version 2.0, this applied only to the user interface and not to, say,
12965 Thus, French authors were forced to resort to ugly hacks if they wanted
12970 1' instead of `Theorem 1'.
12971 Thanks to Georg Baum, that is no longer the case.
12974 \begin_layout Standard
12976 \begin_inset Flex Code
12979 \begin_layout Plain Layout
12985 defines text that is to appear in the typeset document, it may use
12986 \begin_inset Flex Code
12989 \begin_layout Plain Layout
12996 \begin_inset Flex Code
12999 \begin_layout Plain Layout
13005 to support non-English and even multi-language documents correctly.
13006 The following excerpt (from the
13007 \begin_inset Flex Code
13010 \begin_layout Plain Layout
13016 file) shows how this works:
13019 \begin_layout LyX-Code
13024 \begin_layout LyX-Code
13027 theoremstyle{remark}
13030 \begin_layout LyX-Code
13033 newtheorem{claim}[thm]{
13040 \begin_layout LyX-Code
13044 \begin_layout LyX-Code
13048 \begin_layout LyX-Code
13053 claimname}{_(Claim)}
13056 \begin_layout LyX-Code
13060 \begin_layout LyX-Code
13064 \begin_layout LyX-Code
13073 claimname}{_(Claim)}}
13076 \begin_layout LyX-Code
13081 \begin_layout Standard
13082 In principle, any legal LaTeX may appear in the
13083 \begin_inset Flex Code
13086 \begin_layout Plain Layout
13093 \begin_inset Flex Code
13096 \begin_layout Plain Layout
13102 tags, but in practice they will typically look as they do here.
13103 The key to correct translation of the typeset text is the definition of
13105 \begin_inset Flex Code
13108 \begin_layout Plain Layout
13117 \begin_inset Flex Code
13120 \begin_layout Plain Layout
13132 \begin_layout Standard
13134 \begin_inset Flex Code
13137 \begin_layout Plain Layout
13143 tag provides for internationalization based upon the overall language of
13145 The contents of the tag will be included in the preamble, just as with
13147 \begin_inset Flex Code
13150 \begin_layout Plain Layout
13157 What makes it special is the use of the
13158 \begin_inset Quotes eld
13162 \begin_inset Quotes erd
13166 \begin_inset Flex Code
13169 \begin_layout Plain Layout
13175 , which will be replaced, when LyX produces LaTeX output, with the translation
13176 of its argument into the document language.
13179 \begin_layout Standard
13181 \begin_inset Flex Code
13184 \begin_layout Plain Layout
13190 tag is more complex, since it is meant to provide support for multi-language
13191 documents and so offers an interface to the
13192 \begin_inset Flex Code
13195 \begin_layout Plain Layout
13202 Its contents will be added to the preamble once for each language that
13203 appears in the document.
13204 In this case, the argument to
13205 \begin_inset Flex Code
13208 \begin_layout Plain Layout
13214 will be replaced with its translation into the language in question; the
13216 \begin_inset Flex Code
13219 \begin_layout Plain Layout
13225 is replaced by the language name (as used by the babel package).
13228 \begin_layout Standard
13229 A German document that also included a French section would thus have the
13230 following in the preamble:
13233 \begin_layout LyX-Code
13242 claimname}{Affirmation}}
13250 claimname}{Behauptung}}
13254 claimname}{Behauptung}
13257 \begin_layout Standard
13259 \begin_inset Flex Code
13262 \begin_layout Plain Layout
13268 will then conspire to produce the correct text in the output.
13271 \begin_layout Standard
13272 One important point to note here is that the translations are provided by
13273 LyX itself, through the same mechanism it uses for internationalization
13274 of the user interface.
13275 This means, in effect, that
13276 \begin_inset Flex Code
13279 \begin_layout Plain Layout
13286 \begin_inset Flex Code
13289 \begin_layout Plain Layout
13295 are really only of use in layout files that are provided with LyX, since
13296 text entered in user-created layout files will not be seen by LyX's internation
13297 alization routines.
13298 That said, however, any layout created with the intention that it will
13299 be included with LyX should use these tags where appropriate.
13302 \begin_layout Subsection
13304 \begin_inset CommandInset label
13313 \begin_layout Standard
13314 Since version 1.3.0 of LyX, it is has been both possible and necessary to
13315 define the floats (
13316 \begin_inset Flex MenuItem
13319 \begin_layout Plain Layout
13326 \begin_inset Flex MenuItem
13329 \begin_layout Plain Layout
13335 , \SpecialChar \ldots{}
13336 ) in the text class itself.
13337 Standard floats are included in the file
13338 \begin_inset Flex Code
13341 \begin_layout Plain Layout
13347 , so you may have to do no more than add
13350 \begin_layout LyX-Code
13351 Input stdfloats.inc
13354 \begin_layout Standard
13355 to your layout file.
13356 If you want to implement a text class that proposes some other float types
13357 (like the AGU class bundled with LyX), the information below will hopefully
13361 \begin_layout Description
13362 \begin_inset Flex Code
13365 \begin_layout Plain Layout
13372 \begin_inset Flex Code
13375 \begin_layout Plain Layout
13382 \begin_inset Quotes erd
13386 \begin_inset Quotes erd
13389 ] The file name extension of an auxiliary file for the list of figures (or
13391 LaTeX writes the captions to this file.
13394 \begin_layout Description
13395 \begin_inset Flex Code
13398 \begin_layout Plain Layout
13405 \begin_inset Flex Code
13408 \begin_layout Plain Layout
13415 \begin_inset Quotes erd
13419 \begin_inset Quotes erd
13422 ] The string that will be used in the menus and also for the caption.
13423 This is translated to the current language if babel is used.
13426 \begin_layout Description
13427 \begin_inset Flex Code
13430 \begin_layout Plain Layout
13436 These are used for XHTML output.
13438 \begin_inset CommandInset ref
13440 reference "sec:Tags-for-XHTML"
13447 \begin_layout Description
13448 \begin_inset Flex Code
13451 \begin_layout Plain Layout
13460 \begin_inset Flex Code
13463 \begin_layout Plain Layout
13472 \begin_inset Flex Code
13475 \begin_layout Plain Layout
13481 ] Indicates whether the float is already defined in the document class or
13482 if we instead need to load
13483 \begin_inset Flex Code
13486 \begin_layout Plain Layout
13492 and use what it provides to define it on-the-fly.
13494 \begin_inset Flex Code
13497 \begin_layout Plain Layout
13504 \begin_inset Flex Code
13507 \begin_layout Plain Layout
13514 It should be set to
13515 \begin_inset Flex Code
13518 \begin_layout Plain Layout
13524 if the float is already defined by the LaTeX document class.
13527 \begin_layout Description
13528 \begin_inset Flex Code
13531 \begin_layout Plain Layout
13538 \begin_inset Flex Code
13541 \begin_layout Plain Layout
13548 \begin_inset Quotes erd
13552 \begin_inset Quotes erd
13555 ] The command used to generate a list of floats of this type; the leading
13558 ' should be omitted.
13564 \begin_inset Flex Code
13567 \begin_layout Plain Layout
13573 is false, since there is no standard way to generate this command.
13575 \begin_inset Flex Code
13578 \begin_layout Plain Layout
13584 is true, since in that case there is a standard way to define the command.
13587 \begin_layout Description
13588 \begin_inset Flex Code
13591 \begin_layout Plain Layout
13598 \begin_inset Flex Code
13601 \begin_layout Plain Layout
13608 \begin_inset Quotes erd
13612 \begin_inset Quotes erd
13615 ] A title for a list of floats of this kind (list of figures, tables, or
13617 It is used for the screen label within LyX; it is passed to LaTeX for use
13618 as the title there; and it is used as the title in XHTML output.
13619 It will be translated to the document language.
13622 \begin_layout Description
13623 \begin_inset Flex Code
13626 \begin_layout Plain Layout
13633 \begin_inset Flex Code
13636 \begin_layout Plain Layout
13643 \begin_inset Quotes erd
13647 \begin_inset Quotes erd
13650 ] This (optional) argument determines whether floats of this class will
13651 be numbered within some sectional unit of the document.
13652 For example, if within is equal to
13653 \begin_inset Flex Code
13656 \begin_layout Plain Layout
13662 , the floats will be numbered within chapters.
13666 \begin_layout Description
13667 \begin_inset Flex Code
13670 \begin_layout Plain Layout
13677 \begin_inset Flex Code
13680 \begin_layout Plain Layout
13687 \begin_inset Quotes erd
13691 \begin_inset Quotes erd
13694 ] The default placement for the given class of floats.
13695 The string should be as in standard LaTeX:
13696 \begin_inset Flex Code
13699 \begin_layout Plain Layout
13706 \begin_inset Flex Code
13709 \begin_layout Plain Layout
13716 \begin_inset Flex Code
13719 \begin_layout Plain Layout
13726 \begin_inset Flex Code
13729 \begin_layout Plain Layout
13735 for top, bottom, page, and here, respectively.
13739 \begin_layout Plain Layout
13740 Note that the order of these letters in the string is irrelevant, like in
13746 On top of that there is a new type,
13747 \begin_inset Flex Code
13750 \begin_layout Plain Layout
13756 , which does not really correspond to a float, since it means: put it
13757 \begin_inset Quotes eld
13761 \begin_inset Quotes erd
13765 Note however that the
13766 \begin_inset Flex Code
13769 \begin_layout Plain Layout
13775 specifier is special and, because of implementation details, cannot be
13776 used in non-built in float types.
13777 If you do not understand what this means, just use
13778 \begin_inset Quotes eld
13782 \begin_inset Flex Code
13785 \begin_layout Plain Layout
13792 \begin_inset Quotes erd
13798 \begin_layout Description
13799 \begin_inset Flex Code
13802 \begin_layout Plain Layout
13809 \begin_inset Flex Code
13812 \begin_layout Plain Layout
13818 ] The prefix to use when creating labels referring to floats of this type.
13819 This allows the use of formatted references.
13820 Note that you can remove any
13821 \begin_inset Flex Code
13824 \begin_layout Plain Layout
13830 set by a copied style by using the special value
13831 \begin_inset Quotes eld
13835 \begin_inset Quotes erd
13838 , which must be all caps.
13841 \begin_layout Description
13842 \begin_inset Flex Code
13845 \begin_layout Plain Layout
13852 \begin_inset Flex Code
13855 \begin_layout Plain Layout
13862 \begin_inset Quotes erd
13866 \begin_inset Quotes erd
13869 ] The style used when defining the float using
13870 \begin_inset Flex Code
13873 \begin_layout Plain Layout
13884 \begin_layout Description
13885 \begin_inset Flex Code
13888 \begin_layout Plain Layout
13895 \begin_inset Flex Code
13898 \begin_layout Plain Layout
13905 \begin_inset Quotes erd
13909 \begin_inset Quotes erd
13913 \begin_inset Quotes eld
13917 \begin_inset Quotes erd
13920 of the new class of floats, like program or algorithm.
13921 After the appropriate
13922 \begin_inset Flex Code
13925 \begin_layout Plain Layout
13934 \begin_inset Flex Code
13937 \begin_layout Plain Layout
13946 \begin_inset Flex Code
13949 \begin_layout Plain Layout
13960 \begin_layout Description
13961 \begin_inset Flex Code
13964 \begin_layout Plain Layout
13971 \begin_inset Flex Code
13974 \begin_layout Plain Layout
13981 \begin_inset Flex Code
13984 \begin_layout Plain Layout
13992 ] Tells us whether this float is defined using the facilities provided by
13994 \begin_inset Flex Code
13997 \begin_layout Plain Layout
14003 , either by the class file or a package, or on-the-fly by LyX itself.
14006 \begin_layout Standard
14007 Note that defining a float with type
14008 \begin_inset Flex Code
14011 \begin_layout Plain Layout
14019 automatically defines the corresponding counter with name
14020 \begin_inset Flex Code
14023 \begin_layout Plain Layout
14034 \begin_layout Subsection
14035 Flex insets and InsetLayout
14036 \begin_inset CommandInset label
14038 name "sub:Flex-insets-and"
14045 \begin_layout Standard
14046 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
14047 these are called Flex insets.
14051 \begin_layout Standard
14052 Flex insets come in three different kinds:
14055 \begin_layout Itemize
14057 \begin_inset Flex Code
14060 \begin_layout Plain Layout
14066 ): These define semantic markup corresponding to such LaTeX commands as
14068 \begin_inset Flex Code
14071 \begin_layout Plain Layout
14080 \begin_inset Flex Code
14083 \begin_layout Plain Layout
14094 \begin_layout Itemize
14096 \begin_inset Flex Code
14099 \begin_layout Plain Layout
14105 ): These can be used to define custom collapsible insets, similar to TeX
14106 code, footnote, and the like.
14107 An obvious example is an endnote inset, which is defined in the
14108 \begin_inset Flex Code
14111 \begin_layout Plain Layout
14120 \begin_layout Itemize
14122 \begin_inset Flex Code
14125 \begin_layout Plain Layout
14131 ): For use with DocBook classes.
14134 \begin_layout Standard
14135 Flex insets are defined using the
14136 \begin_inset Flex Code
14139 \begin_layout Plain Layout
14145 tag, which shall be explained in a moment.
14148 \begin_layout Standard
14150 \begin_inset Flex Code
14153 \begin_layout Plain Layout
14159 tag also serves another function: It can be used to customize the general
14160 layout of many different types of insets.
14162 \begin_inset Flex Code
14165 \begin_layout Plain Layout
14171 can be used to customize the layout parameters for footnotes, marginal
14172 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
14173 boxes, tables, algorithms, URLs, and optional arguments, as well as to
14174 define Flex insets.
14177 \begin_layout Standard
14179 \begin_inset Flex Code
14182 \begin_layout Plain Layout
14188 definition must begin with a line of the form:
14191 \begin_layout LyX-Code
14195 \begin_layout Standard
14197 \begin_inset Flex Code
14200 \begin_layout Plain Layout
14206 indicates the inset whose layout is being defined, and here there are two
14210 \begin_layout Enumerate
14211 The layout for a pre-existing inset is being modified.
14212 In this case, can be
14213 \begin_inset Flex Code
14216 \begin_layout Plain Layout
14222 any one of the following:
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
14263 \begin_inset Flex Code
14266 \begin_layout Plain Layout
14273 \begin_inset Flex Code
14276 \begin_layout Plain Layout
14283 \begin_inset Flex Code
14286 \begin_layout Plain Layout
14293 \begin_inset Flex Code
14296 \begin_layout Plain Layout
14303 \begin_inset Flex Code
14306 \begin_layout Plain Layout
14313 \begin_inset Flex Code
14316 \begin_layout Plain Layout
14323 \begin_inset Flex Code
14326 \begin_layout Plain Layout
14333 \begin_inset Flex Code
14336 \begin_layout Plain Layout
14343 \begin_inset Flex Code
14346 \begin_layout Plain Layout
14353 \begin_inset Flex Code
14356 \begin_layout Plain Layout
14363 \begin_inset Flex Code
14366 \begin_layout Plain Layout
14373 \begin_inset Flex Code
14376 \begin_layout Plain Layout
14383 \begin_inset Flex Code
14386 \begin_layout Plain Layout
14393 \begin_inset Flex Code
14396 \begin_layout Plain Layout
14403 \begin_inset Flex Code
14406 \begin_layout Plain Layout
14413 \begin_inset Flex Code
14416 \begin_layout Plain Layout
14425 \begin_layout Enumerate
14426 The layout for a Flex inset is being defined.
14428 \begin_inset Flex Code
14431 \begin_layout Plain Layout
14437 may be be any valid identifier not used by a pre-existing inset.
14438 The identifier may include spaces, but in that case the whole thing must
14439 be wrapped in quotes.
14440 It may also include a namespace identifier, preceding a colon, such as
14442 \begin_inset Quotes eld
14446 \begin_inset Flex Code
14449 \begin_layout Plain Layout
14456 \begin_inset Quotes erd
14460 Note that the definition of a flex inset
14465 \begin_inset Flex Code
14468 \begin_layout Plain Layout
14474 entry, declaring which type of inset it defines.
14477 \begin_layout Standard
14479 \begin_inset Flex Code
14482 \begin_layout Plain Layout
14488 definition can contain the following entries:
14491 \begin_layout Description
14492 \begin_inset Flex Code
14495 \begin_layout Plain Layout
14501 The color for the inset's background.
14502 The valid colors are defined in
14503 \begin_inset Flex Code
14506 \begin_layout Plain Layout
14515 \begin_layout Description
14516 \begin_inset Flex Code
14519 \begin_layout Plain Layout
14526 \begin_inset Flex Code
14529 \begin_layout Plain Layout
14538 \begin_inset Flex Code
14541 \begin_layout Plain Layout
14547 ] Whether to use the content of the inset as the label, when the inset is
14552 \begin_layout Description
14553 \begin_inset Flex Code
14556 \begin_layout Plain Layout
14562 As with paragraph styles (see page
14563 \begin_inset CommandInset ref
14565 reference "des:CopyStyle"
14572 \begin_layout Description
14573 \begin_inset Flex Code
14576 \begin_layout Plain Layout
14583 \begin_inset Flex Code
14586 \begin_layout Plain Layout
14595 \begin_inset Flex Code
14598 \begin_layout Plain Layout
14604 ] Indicates whether the user may employ the Paragraph Settings dialog to
14605 customize the paragraph.
14608 \begin_layout Description
14609 \begin_inset Flex Code
14612 \begin_layout Plain Layout
14619 \begin_inset Flex Code
14622 \begin_layout Plain Layout
14629 \begin_inset Flex Code
14632 \begin_layout Plain Layout
14639 \begin_inset Flex Code
14642 \begin_layout Plain Layout
14648 , describing the rendering style used for the inset's frame and buttons.
14649 Footnotes generally use
14650 \begin_inset Flex Code
14653 \begin_layout Plain Layout
14659 , ERT insets generally
14660 \begin_inset Flex Code
14663 \begin_layout Plain Layout
14669 , and character styles
14670 \begin_inset Flex Code
14673 \begin_layout Plain Layout
14682 \begin_layout Description
14683 \begin_inset Flex Code
14686 \begin_layout Plain Layout
14693 \begin_inset Flex Code
14696 \begin_layout Plain Layout
14703 \begin_inset Flex Code
14706 \begin_layout Plain Layout
14715 \begin_inset Flex Code
14718 \begin_layout Plain Layout
14725 \begin_inset Flex Code
14728 \begin_layout Plain Layout
14735 Indicates whether the environment will stand on its own in LaTeX output
14736 or will appear inline with the surrounding text.
14737 If set to false, it is supposed that the LaTeX environment ignores white
14738 space (including one newline character) after the
14739 \begin_inset Flex Code
14742 \begin_layout Plain Layout
14755 \begin_inset Flex Code
14758 \begin_layout Plain Layout
14774 \begin_layout Description
14775 \begin_inset Flex Code
14778 \begin_layout Plain Layout
14784 Required at the end of the InsetLayout declarations.
14787 \begin_layout Description
14788 \begin_inset Flex Code
14791 \begin_layout Plain Layout
14797 The font used for both the text body
14803 \begin_inset space ~
14807 \begin_inset CommandInset ref
14809 reference "sub:Font-description"
14814 Note that defining this font automatically defines the
14815 \begin_inset Flex Code
14818 \begin_layout Plain Layout
14824 to the same value, so define this first and define
14825 \begin_inset Flex Code
14828 \begin_layout Plain Layout
14834 later if you want them to be different.
14837 \begin_layout Description
14838 \begin_inset Flex Code
14841 \begin_layout Plain Layout
14848 \begin_inset Quotes eld
14852 \begin_inset Quotes erd
14855 language, leading to Left-to-Right (latin) output, e.
14856 \begin_inset space \thinspace{}
14860 \begin_inset space \space{}
14863 in TeX code or URL.
14867 \begin_layout Description
14868 \begin_inset Flex Code
14871 \begin_layout Plain Layout
14878 \begin_inset Flex Code
14881 \begin_layout Plain Layout
14890 \begin_inset Flex Code
14893 \begin_layout Plain Layout
14899 ] Indicates whether the
14900 \change_deleted 34634807 1296982392
14902 \change_inserted 34634807 1296982392
14904 \begin_inset Flex Code
14907 \begin_layout Plain Layout
14909 \change_inserted 34634807 1296982392
14919 should be used or, instead, the user can change the paragraph style used
14924 \begin_layout Description
14925 \begin_inset Flex Code
14928 \begin_layout Plain Layout
14934 As with paragraph styles (see page
14935 \begin_inset CommandInset ref
14936 LatexCommand pageref
14937 reference "des:FreeSpacing"
14945 \begin_layout Description
14946 \begin_inset Flex Code
14949 \begin_layout Plain Layout
14955 These tags control XHTML output.
14957 \begin_inset CommandInset ref
14959 reference "sec:Tags-for-XHTML"
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 ] Whether to include the contents of this inset in the strings generated
14999 for the `Outline' pane.
15000 One would not, for example, want the content of a footnote in a section
15001 header to be included in the TOC displayed in the outline, but one would
15002 normally want the content of a character style displayed.
15003 Default is false: not to include.
15006 \begin_layout Description
15007 \begin_inset Flex Code
15010 \begin_layout Plain Layout
15016 As with paragraph styles (see page
15017 \begin_inset CommandInset ref
15018 LatexCommand pageref
15019 reference "des:KeepEmpty"
15027 \begin_layout Description
15028 \begin_inset Flex Code
15031 \begin_layout Plain Layout
15037 The font used for the label.
15039 \begin_inset space ~
15043 \begin_inset CommandInset ref
15045 reference "sub:Font-description"
15050 Note that this definition can never appear before
15051 \begin_inset Flex Code
15054 \begin_layout Plain Layout
15060 , lest it be ineffective.
15063 \begin_layout Description
15064 \begin_inset Flex Code
15067 \begin_layout Plain Layout
15073 What will be displayed on the button or elsewhere as the inset label.
15075 \change_deleted 34634807 1296982426
15077 \change_inserted 34634807 1296982426
15079 \begin_inset Flex Code
15082 \begin_layout Plain Layout
15084 \change_inserted 34634807 1296982426
15095 \change_deleted 34634807 1296982433
15097 \change_inserted 34634807 1296982433
15099 \begin_inset Flex Code
15102 \begin_layout Plain Layout
15104 \change_inserted 34634807 1296982433
15114 ) modify this label on the fly.
15117 \begin_layout Description
15118 \begin_inset Flex Code
15121 \begin_layout Plain Layout
15127 The name of the corresponding LaTeX stuff.
15128 Either the environment or command name.
15131 \begin_layout Description
15132 \begin_inset Flex Code
15135 \begin_layout Plain Layout
15141 The optional parameter for the corresponding
15142 \begin_inset Flex Code
15145 \begin_layout Plain Layout
15151 stuff, including possible bracket pairs like
15152 \begin_inset Flex Code
15155 \begin_layout Plain Layout
15162 This parameter cannot be changed from within LyX.
15165 \begin_layout Description
15166 \begin_inset Flex Code
15169 \begin_layout Plain Layout
15175 As with paragraph styles (see page
15176 \begin_inset CommandInset ref
15177 LatexCommand pageref
15178 reference "des:LatexType"
15185 \begin_layout Description
15186 \begin_inset Flex Code
15189 \begin_layout Plain Layout
15196 \begin_inset Flex Code
15199 \begin_layout Plain Layout
15206 \begin_inset Flex Code
15209 \begin_layout Plain Layout
15216 \begin_inset Flex Code
15219 \begin_layout Plain Layout
15226 \begin_inset Flex Code
15229 \begin_layout Plain Layout
15235 (indicating a dummy definition ending definitions of charstyles, etc).
15236 This entry is required in and is only meaningful for Flex insets.
15237 Among other things, it determines on which menu this inset will appear.
15239 \begin_inset Flex Code
15242 \begin_layout Plain Layout
15249 \begin_inset Flex Code
15252 \begin_layout Plain Layout
15259 \begin_inset Flex Code
15262 \begin_layout Plain Layout
15270 \begin_inset Flex Code
15273 \begin_layout Plain Layout
15279 can be set to true for charstyle insets, if you wish, by setting it
15284 \begin_inset Flex Code
15287 \begin_layout Plain Layout
15296 \begin_layout Description
15297 \begin_inset Flex Code
15300 \begin_layout Plain Layout
15307 \begin_inset Flex Code
15310 \begin_layout Plain Layout
15319 \begin_inset Flex Code
15322 \begin_layout Plain Layout
15328 ] Whether multiple paragraphs are permitted in this inset.
15330 \begin_inset Flex Code
15333 \begin_layout Plain Layout
15339 to the same value and
15340 \begin_inset Flex Code
15343 \begin_layout Plain Layout
15349 to the opposite value.
15350 These can be reset to other values, if they are used
15355 \begin_inset Flex Code
15358 \begin_layout Plain Layout
15368 \begin_layout Description
15369 \begin_inset Flex Code
15372 \begin_layout Plain Layout
15379 \begin_inset Flex Code
15382 \begin_layout Plain Layout
15391 \begin_inset Flex Code
15394 \begin_layout Plain Layout
15400 ] Whether fragile commands in this
15401 \change_deleted 34634807 1296982465
15403 \change_inserted 34634807 1296982466
15407 \begin_inset Flex Code
15410 \begin_layout Plain Layout
15423 whether the command should itself be protected.) Default is false.
15426 \begin_layout Description
15427 \begin_inset Flex Code
15430 \begin_layout Plain Layout
15437 \begin_inset Flex Code
15440 \begin_layout Plain Layout
15449 \begin_inset Flex Code
15452 \begin_layout Plain Layout
15458 ] As with paragraph styles (see page
15459 \begin_inset CommandInset ref
15460 LatexCommand pageref
15461 reference "des:ParbreakIsNewline"
15469 \begin_layout Description
15470 \begin_inset Flex Code
15473 \begin_layout Plain Layout
15480 \begin_inset Flex Code
15483 \begin_layout Plain Layout
15492 \begin_inset Flex Code
15495 \begin_layout Plain Layout
15501 ] As with paragraph styles (see page
15502 \begin_inset CommandInset ref
15503 LatexCommand pageref
15504 reference "des:PassThru"
15512 \begin_layout Description
15513 \begin_inset Flex Code
15516 \begin_layout Plain Layout
15522 As with paragraph styles (see page
15523 \begin_inset CommandInset ref
15524 LatexCommand pageref
15525 reference "des:Preamble"
15532 \begin_layout Description
15533 \begin_inset Flex Code
15536 \begin_layout Plain Layout
15543 \begin_inset Flex Code
15546 \begin_layout Plain Layout
15552 ] The prefix to use when creating labels referring to insets of this type.
15553 This allows the use of formatted references.
15556 \begin_layout Description
15557 \begin_inset Flex Code
15560 \begin_layout Plain Layout
15567 \begin_inset Flex Code
15570 \begin_layout Plain Layout
15576 ] As with paragraph styles (see page
15577 \begin_inset CommandInset ref
15578 LatexCommand pageref
15579 reference "des:Requires"
15586 \begin_layout Description
15587 \begin_inset Flex Code
15590 \begin_layout Plain Layout
15597 \begin_inset Flex Code
15600 \begin_layout Plain Layout
15607 \begin_inset Flex Code
15610 \begin_layout Plain Layout
15618 ] Whether this inset should use the font of its surrounding environment
15620 Default is true: uses its own.
15623 \begin_layout Description
15624 \begin_inset Flex Code
15627 \begin_layout Plain Layout
15634 \begin_inset Flex Code
15637 \begin_layout Plain Layout
15644 \begin_inset Flex Code
15647 \begin_layout Plain Layout
15655 ] Spellcheck the contents of this inset.
15659 \begin_layout Subsection
15661 \begin_inset CommandInset label
15663 name "sub:Counters"
15670 \begin_layout Standard
15671 Since version 1.3.0 of LyX, it is both possible and necessary to define the
15673 \begin_inset Flex MenuItem
15676 \begin_layout Plain Layout
15683 \begin_inset Flex MenuItem
15686 \begin_layout Plain Layout
15692 , \SpecialChar \ldots{}
15693 ) in the text class itself.
15694 The standard counters are defined in the file
15695 \begin_inset Flex Code
15698 \begin_layout Plain Layout
15704 , so you may have to do no more than add
15707 \begin_layout LyX-Code
15708 Input stdcounters.inc
15711 \begin_layout Standard
15712 to your layout file to get them to work.
15713 But if you want to define custom counters, then you can do so.
15714 The counter declaration must begin with:
15717 \begin_layout LyX-Code
15718 Counter CounterName
15721 \begin_layout Standard
15723 \begin_inset Flex Code
15726 \begin_layout Plain Layout
15732 ' is replaced by the name of the counter.
15733 And it must end with
15734 \begin_inset Quotes eld
15738 \begin_inset Flex Code
15741 \begin_layout Plain Layout
15748 \begin_inset Quotes erd
15752 The following parameters can also be used:
15755 \begin_layout Description
15756 \begin_inset Flex Code
15759 \begin_layout Plain Layout
15766 \begin_inset Flex Code
15769 \begin_layout Plain Layout
15776 \begin_inset Quotes erd
15780 \begin_inset Quotes erd
15783 ] When defined, this string defines how the counter is displayed.
15784 Setting this value sets
15785 \begin_inset Flex Code
15788 \begin_layout Plain Layout
15789 LabelStringAppendix
15795 The following special constructs can be used in the string:
15799 \begin_layout Itemize
15800 \begin_inset Flex Code
15803 \begin_layout Plain Layout
15811 will be replaced by the expansion of the
15812 \begin_inset Flex Code
15815 \begin_layout Plain Layout
15822 \begin_inset Flex Code
15825 \begin_layout Plain Layout
15826 LabelStringAppendix
15832 \begin_inset Flex Code
15835 \begin_layout Plain Layout
15845 \begin_layout Itemize
15846 counter values can be expressed using LaTeX-like macros
15847 \begin_inset Flex Code
15850 \begin_layout Plain Layout
15867 \begin_inset Flex Code
15870 \begin_layout Plain Layout
15882 \begin_layout Plain Layout
15892 Actually, the situation is a bit more complicated: any
15911 other than those described below will produce arabic numerals.
15912 It would not be surprising to see this change in the future.
15918 \begin_inset Flex Code
15921 \begin_layout Plain Layout
15927 : 1, 2, 3,\SpecialChar \ldots{}
15929 \begin_inset Flex Code
15932 \begin_layout Plain Layout
15938 for lower-case letters: a, b, c, \SpecialChar \ldots{}
15940 \begin_inset Flex Code
15943 \begin_layout Plain Layout
15949 for upper-case letters: A, B, C, \SpecialChar \ldots{}
15951 \begin_inset Flex Code
15954 \begin_layout Plain Layout
15960 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
15962 \begin_inset Flex Code
15965 \begin_layout Plain Layout
15971 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
15973 \begin_inset Flex Code
15976 \begin_layout Plain Layout
15982 for hebrew numerals.
15986 \begin_layout Standard
15987 If LabelString is not defined, a default value is constructed as follows:
15988 if the counter has a master counter
15989 \begin_inset Flex Code
15992 \begin_layout Plain Layout
15999 \begin_inset Flex Code
16002 \begin_layout Plain Layout
16009 \begin_inset Flex Code
16012 \begin_layout Plain Layout
16022 is used; otherwise the string
16023 \begin_inset Flex Code
16026 \begin_layout Plain Layout
16037 \begin_layout Description
16038 \begin_inset Flex Code
16041 \begin_layout Plain Layout
16042 LabelStringAppendix
16048 \begin_inset Flex Code
16051 \begin_layout Plain Layout
16058 \begin_inset Quotes erd
16062 \begin_inset Quotes erd
16066 \begin_inset Flex Code
16069 \begin_layout Plain Layout
16075 , but for use in the Appendix.
16078 \begin_layout Description
16079 \begin_inset Flex Code
16082 \begin_layout Plain Layout
16089 \begin_inset Flex Code
16092 \begin_layout Plain Layout
16099 \begin_inset Quotes erd
16103 \begin_inset Quotes erd
16106 ] A format for use with formatted references to this counter.
16107 For example, one might want to have references to section numbers appear
16109 \begin_inset Quotes eld
16113 \begin_inset Quotes erd
16117 The string should contain
16118 \begin_inset Quotes eld
16122 \begin_inset Quotes erd
16126 This will be replaced by the counter number itself.
16127 So, for sections, it would be: Section ##.
16130 \begin_layout Description
16131 \begin_inset Flex Code
16134 \begin_layout Plain Layout
16141 \begin_inset Flex Code
16144 \begin_layout Plain Layout
16151 \begin_inset Quotes erd
16155 \begin_inset Quotes erd
16158 ] If this is set to the name of another counter, the present counter will
16159 be reset every time the other one is increased.
16161 \begin_inset Flex Code
16164 \begin_layout Plain Layout
16171 \begin_inset Flex Code
16174 \begin_layout Plain Layout
16183 \begin_layout Subsection
16185 \begin_inset CommandInset label
16187 name "sub:Font-description"
16194 \begin_layout Standard
16195 A font description looks like this:
16198 \begin_layout LyX-Code
16208 \begin_layout LyX-Code
16212 \begin_layout LyX-Code
16216 \begin_layout Standard
16217 The following commands are available:
16220 \begin_layout Description
16221 \begin_inset Flex Code
16224 \begin_layout Plain Layout
16231 \begin_inset Flex Code
16234 \begin_layout Plain Layout
16243 \begin_inset Flex Code
16246 \begin_layout Plain Layout
16253 \begin_inset Flex Code
16256 \begin_layout Plain Layout
16263 \begin_inset Flex Code
16266 \begin_layout Plain Layout
16273 \begin_inset Flex Code
16276 \begin_layout Plain Layout
16283 \begin_inset Flex Code
16286 \begin_layout Plain Layout
16293 \begin_inset Flex Code
16296 \begin_layout Plain Layout
16303 \begin_inset Flex Code
16306 \begin_layout Plain Layout
16313 \begin_inset Flex Code
16316 \begin_layout Plain Layout
16325 \begin_layout Description
16326 \begin_inset Flex Code
16329 \begin_layout Plain Layout
16336 \begin_inset Flex Code
16339 \begin_layout Plain Layout
16348 \begin_inset Flex Code
16351 \begin_layout Plain Layout
16358 \begin_inset Flex Code
16361 \begin_layout Plain Layout
16370 \begin_layout Description
16371 \begin_inset Flex Code
16374 \begin_layout Plain Layout
16381 \begin_inset Flex Code
16384 \begin_layout Plain Layout
16390 ] Valid arguments are:
16391 \begin_inset Flex Code
16394 \begin_layout Plain Layout
16401 \begin_inset Flex Code
16404 \begin_layout Plain Layout
16411 \begin_inset Flex Code
16414 \begin_layout Plain Layout
16421 \begin_inset Flex Code
16424 \begin_layout Plain Layout
16431 \begin_inset Flex Code
16434 \begin_layout Plain Layout
16441 \begin_inset Flex Code
16444 \begin_layout Plain Layout
16451 Each of these turns on or off the corresponding attribute.
16453 \begin_inset Flex Code
16456 \begin_layout Plain Layout
16462 turns on emphasis, and
16463 \begin_inset Flex Code
16466 \begin_layout Plain Layout
16474 \begin_inset Newline newline
16477 If the latter seems puzzling, remember that the font settings for the present
16478 context are generally inherited from the surrounding context.
16480 \begin_inset Flex Code
16483 \begin_layout Plain Layout
16489 would turn off the emphasis that was anyway in effect, say, in a theorem
16493 \begin_layout Description
16494 \begin_inset Flex Code
16497 \begin_layout Plain Layout
16504 \begin_inset Flex Code
16507 \begin_layout Plain Layout
16516 \begin_inset Flex Code
16519 \begin_layout Plain Layout
16528 \begin_layout Description
16529 \begin_inset Flex Code
16532 \begin_layout Plain Layout
16539 \begin_inset Flex Code
16542 \begin_layout Plain Layout
16551 \begin_inset Flex Code
16554 \begin_layout Plain Layout
16561 \begin_inset Flex Code
16564 \begin_layout Plain Layout
16571 \begin_inset Flex Code
16574 \begin_layout Plain Layout
16583 \begin_layout Description
16584 \begin_inset Flex Code
16587 \begin_layout Plain Layout
16594 \begin_inset Flex Code
16597 \begin_layout Plain Layout
16604 \begin_inset Flex Code
16607 \begin_layout Plain Layout
16614 \begin_inset Flex Code
16617 \begin_layout Plain Layout
16626 \begin_inset Flex Code
16629 \begin_layout Plain Layout
16636 \begin_inset Flex Code
16639 \begin_layout Plain Layout
16646 \begin_inset Flex Code
16649 \begin_layout Plain Layout
16656 \begin_inset Flex Code
16659 \begin_layout Plain Layout
16666 \begin_inset Flex Code
16669 \begin_layout Plain Layout
16678 \begin_layout Subsection
16679 \begin_inset CommandInset label
16681 name "sub:Citation-format-description"
16685 Citation format description
16688 \begin_layout Standard
16690 \begin_inset Flex Code
16693 \begin_layout Plain Layout
16699 blocks are used to describe how bibliographic information should be displayed,
16700 both within LyX itself (in the citation dialog and in tooltips, for example)
16701 and in XHTML output.
16702 Such a block might look like this:
16705 \begin_layout LyX-Code
16709 \begin_layout LyX-Code
16713 \begin_layout LyX-Code
16717 \begin_layout LyX-Code
16721 \begin_layout Standard
16722 The individual lines define how the bibliographic information associated
16723 with an article or book, respectively, is to be displayed, and such a definitio
16724 n can be given for any `entry type' that might be present in a BibTeX file.
16725 LyX defines a default format in the source code that will be used if no
16726 specific definition has been given.
16727 LyX predefines several formats in the file
16728 \begin_inset Flex Code
16731 \begin_layout Plain Layout
16737 , which is included in most of LyX's document classes.
16740 \begin_layout Standard
16741 The definitions use a simple language that allows BibTeX keys to be replaced
16743 Keys should be enclosed in
16744 \begin_inset Flex Code
16747 \begin_layout Plain Layout
16754 \begin_inset Flex Code
16757 \begin_layout Plain Layout
16764 So a simple definition might look like this:
16767 \begin_layout LyX-Code
16769 \begin_inset Quotes eld
16773 \begin_inset Quotes erd
16779 \begin_layout Standard
16780 This would print the author, followed by a comma, followed by the title,
16781 in quotes, followed by a period.
16784 \begin_layout Standard
16785 Of course, sometimes you may want to print a key only if it exists.
16786 This can be done by using a conditional construction, such as:
16787 \begin_inset Flex Code
16790 \begin_layout Plain Layout
16792 \begin_inset space ~
16802 \begin_inset Flex Code
16805 \begin_layout Plain Layout
16811 key exists, then print
16812 \begin_inset Quotes eld
16816 \begin_inset space ~
16820 \begin_inset Quotes erd
16823 followed by the volume key.
16824 It is also possible to have an else clause in the conditional, such as:
16826 \begin_inset Flex Code
16829 \begin_layout Plain Layout
16830 {%author%[[%author%]][[%editor%, ed.]]}
16837 \begin_inset Flex Code
16840 \begin_layout Plain Layout
16846 key is printed if it exists; otherwise, the editor key is printed, followed
16848 \begin_inset Quotes eld
16852 \begin_inset space ~
16856 \begin_inset Quotes erd
16859 Note that the key is again enclosed in
16860 \begin_inset Flex Code
16863 \begin_layout Plain Layout
16869 signs; the entire conditional is enclosed in braces; and the if and else
16870 clauses are enclosed in double brackets,
16871 \begin_inset Quotes eld
16875 \begin_inset Flex Code
16878 \begin_layout Plain Layout
16885 \begin_inset Quotes eld
16889 \begin_inset Quotes eld
16893 \begin_inset Flex Code
16896 \begin_layout Plain Layout
16903 \begin_inset Quotes erd
16907 There must be no space between any of these.
16910 \begin_layout Standard
16911 There is one other piece of syntax available in definitions, which looks
16913 \begin_inset Flex Code
16916 \begin_layout Plain Layout
16923 This defines a piece of formatting information that is to be used when
16925 \begin_inset Quotes eld
16929 \begin_inset Quotes erd
16933 Obviously, we do not want to output HTML tags when writing plain text,
16934 so they should be wrapped in
16935 \begin_inset Quotes eld
16939 \begin_inset Quotes erd
16943 \begin_inset Quotes eld
16947 \begin_inset Quotes erd
16953 \begin_layout Standard
16954 Two special sorts of definitions are also possible in a
16955 \begin_inset Flex Code
16958 \begin_layout Plain Layout
16965 An example of the first would be:
16968 \begin_layout LyX-Code
16970 \begin_inset Quotes eld
16974 \begin_inset Quotes erd
16980 \begin_layout Standard
16981 This is an abbreviation, or macro, and it can be used by treating it as
16983 \begin_inset Flex Code
16986 \begin_layout Plain Layout
16994 \begin_inset Flex Code
16997 \begin_layout Plain Layout
17003 exactly as it would treat its definition.
17004 So, let us issue the obvious
17012 \begin_layout LyX-Code
17016 \begin_layout Standard
17017 or anything like it.
17018 LyX shouldn't go into an infinite loop, but it may go into a long one before
17022 \begin_layout Standard
17023 The second sort of special definition might look like this:
17026 \begin_layout LyX-Code
17030 \begin_layout Standard
17031 This defines a translatable piece of text, which allows relevant parts of
17032 the bibliography to be translated.
17033 It can be included in a definition by treating it as a key:
17034 \begin_inset Flex Code
17037 \begin_layout Plain Layout
17044 Several of these are predefined in
17045 \begin_inset Flex Code
17048 \begin_layout Plain Layout
17055 Note that these are not macros, in the sense just defined.
17056 They will not be expanded.
17059 \begin_layout Standard
17060 So here then is an example that use all these features:
17063 \begin_layout LyX-Code
17064 !authoredit {%author%[[%author%, ]][[{%editor%[[%editor%, %_edtext%, ]]}]]}
17067 \begin_layout Standard
17068 This defines a macro that prints the author, followed by a comma, if the
17070 \begin_inset Flex Code
17073 \begin_layout Plain Layout
17079 key is defined, or else prints the name of the editor, followed by the
17081 \begin_inset Flex Code
17084 \begin_layout Plain Layout
17090 or its translation (it is by default
17091 \begin_inset Quotes eld
17095 \begin_inset Quotes erd
17099 \begin_inset Flex Code
17102 \begin_layout Plain Layout
17109 Note that this is in fact defined in
17110 \begin_inset Flex Code
17113 \begin_layout Plain Layout
17119 , so you can use it in your own definitions, or re-definitions, if you load
17123 \begin_layout Section
17124 \begin_inset CommandInset label
17126 name "sec:Tags-for-XHTML"
17130 Tags for XHTML output
17133 \begin_layout Standard
17134 As with LaTeX or DocBook, the format of LyX's XHTML output is also controlled
17135 by layout information.
17136 In general, LyX provides sensible defaults and, as mentioned earlier, it
17137 will even construct default CSS style rules from the other layout tags.
17138 For example, LyX will attempt to use the information provided in the
17139 \begin_inset Flex Code
17142 \begin_layout Plain Layout
17148 declaration for the Chapter style to write CSS that will appropriately
17149 format chapter headings.
17152 \begin_layout Standard
17153 In many cases, then, you may not have to do anything at all to get acceptable
17154 XHTML output for your own environments, custom insets, and so forth.
17155 But in some cases you will, and so LyX provides a number of layout tags
17156 that can be used to customize the XHTML and CSS that are generated.
17159 \begin_layout Standard
17160 Note that there are two tags,
17161 \begin_inset Flex Code
17164 \begin_layout Plain Layout
17171 \begin_inset Flex Code
17174 \begin_layout Plain Layout
17180 that may appear outside style and inset declarations.
17182 \begin_inset CommandInset ref
17184 reference "sub:General-text-class"
17188 for details on these.
17191 \begin_layout Subsection
17192 \begin_inset CommandInset label
17194 name "sub:Paragraph-Style-XHTML"
17201 \begin_layout Standard
17202 The sort of XHTML LyX outputs for a paragraph depends upon whether we are
17203 dealing with a normal paragraph, a command, or an environment, where this
17204 is itself determined by the contents of the corresponding
17205 \begin_inset Flex Code
17208 \begin_layout Plain Layout
17218 \begin_layout Standard
17219 For a command or normal paragraph, the output XHTML has the following form:
17222 \begin_layout LyX-Code
17224 \begin_inset Quotes erd
17228 \begin_inset Quotes erd
17234 \begin_layout LyX-Code
17236 \begin_inset Quotes erd
17240 \begin_inset Quotes erd
17246 \begin_layout LyX-Code
17247 Contents of the paragraph.
17250 \begin_layout LyX-Code
17254 \begin_layout Standard
17255 The label tags are of course omitted if the paragraph does not have a label.
17258 \begin_layout Standard
17259 For an environment that is not some sort of list, the XHTML takes this form:
17262 \begin_layout LyX-Code
17264 \begin_inset Quotes erd
17268 \begin_inset Quotes erd
17274 \begin_layout LyX-Code
17276 \begin_inset Quotes erd
17280 \begin_inset Quotes erd
17284 \begin_inset Quotes erd
17288 \begin_inset Quotes erd
17291 >Environment Label</labeltag>First paragraph.</itemtag>
17294 \begin_layout LyX-Code
17295 <itemtag>Second paragraph.</itemtag>
17298 \begin_layout LyX-Code
17302 \begin_layout Standard
17303 Note that the label is output only for the first paragraph, as it should
17304 be for a theorem, for example.
17308 \begin_layout Standard
17309 For a list, we have one of these forms:
17312 \begin_layout LyX-Code
17314 \begin_inset Quotes erd
17318 \begin_inset Quotes erd
17324 \begin_layout LyX-Code
17326 \begin_inset Quotes erd
17330 \begin_inset Quotes erd
17334 \begin_inset Quotes erd
17338 \begin_inset Quotes erd
17341 >List Label</labeltag>First item.</itemtag>
17344 \begin_layout LyX-Code
17346 \begin_inset Quotes erd
17350 \begin_inset Quotes erd
17354 \begin_inset Quotes erd
17358 \begin_inset Quotes erd
17361 >List Label</labeltag>Second item.</itemtag>
17364 \begin_layout LyX-Code
17368 \begin_layout LyX-Code
17372 \begin_layout LyX-Code
17374 \begin_inset Quotes erd
17378 \begin_inset Quotes erd
17384 \begin_layout LyX-Code
17386 \begin_inset Quotes erd
17390 \begin_inset Quotes erd
17393 >List Label</labeltag><itemtag attr=
17394 \begin_inset Quotes erd
17398 \begin_inset Quotes erd
17401 >First item.</itemtag>
17404 \begin_layout LyX-Code
17406 \begin_inset Quotes erd
17410 \begin_inset Quotes erd
17413 >List Label</labeltag><itemtag attr=
17414 \begin_inset Quotes erd
17418 \begin_inset Quotes erd
17421 >Second item.</itemtag>
17424 \begin_layout LyX-Code
17428 \begin_layout Standard
17429 Note the different orders of
17430 \begin_inset Flex Code
17433 \begin_layout Plain Layout
17440 \begin_inset Flex Code
17443 \begin_layout Plain Layout
17450 Which order we get depends upon the setting of
17451 \begin_inset Flex Code
17454 \begin_layout Plain Layout
17461 \begin_inset Flex Code
17464 \begin_layout Plain Layout
17470 is false (the default), you get the first of these, with the label within
17471 the item; if true, you get the second, with the label outside the item.
17474 \begin_layout Standard
17475 The specific tags and attributes output for each paragraph type can be controlle
17476 d by means of the layout tags we are about to describe.
17477 As mentioned earlier, however, LyX uses sensible defaults for many of these,
17478 so you often may not need to do very much to get good XHTML output.
17479 Think of the available tags as there so you can tweak things to your liking.
17482 \begin_layout Description
17483 \begin_inset Flex Code
17486 \begin_layout Plain Layout
17493 \begin_inset Flex Code
17496 \begin_layout Plain Layout
17502 ] Specifies attribute information to be output with the main tag.
17504 \begin_inset Quotes eld
17508 \begin_inset Flex Code
17511 \begin_layout Plain Layout
17518 \begin_inset Quotes erd
17522 By default, LyX will output
17523 \begin_inset Quotes eld
17527 \begin_inset Flex Code
17530 \begin_layout Plain Layout
17537 \begin_inset Quotes erd
17541 \begin_inset Flex Code
17544 \begin_layout Plain Layout
17550 is the LyX name of the layout, made lowercase, for example: chapter.
17555 contain any style information.
17557 \begin_inset Flex Code
17560 \begin_layout Plain Layout
17569 \begin_layout Description
17570 \begin_inset Flex Code
17573 \begin_layout Plain Layout
17580 \begin_inset Flex Code
17583 \begin_layout Plain Layout
17593 ] Whether to output the default CSS information LyX generates for this layout,
17594 even if additional information is explicitly provided via
17595 \begin_inset Flex Code
17598 \begin_layout Plain Layout
17606 \begin_inset Flex Code
17609 \begin_layout Plain Layout
17615 allows you to alter or augment the generated CSS, rather than to override
17618 \begin_inset Flex Code
17621 \begin_layout Plain Layout
17630 \begin_layout Description
17631 \begin_inset Flex Code
17634 \begin_layout Plain Layout
17641 \begin_inset Flex Code
17644 \begin_layout Plain Layout
17650 ] The tag to be used for individual paragraphs of environments, replacing
17652 \begin_inset Flex Code
17655 \begin_layout Plain Layout
17661 in the examples above.
17663 \begin_inset Flex Code
17666 \begin_layout Plain Layout
17675 \begin_layout Description
17676 \begin_inset Flex Code
17679 \begin_layout Plain Layout
17686 \begin_inset Flex Code
17689 \begin_layout Plain Layout
17695 ] Attributes for the item tag.
17697 \begin_inset Quotes eld
17701 \begin_inset Flex Code
17704 \begin_layout Plain Layout
17705 class=`layoutname_item'
17711 \begin_inset Quotes erd
17719 contain any style information.
17721 \begin_inset Flex Code
17724 \begin_layout Plain Layout
17733 \begin_layout Description
17734 \begin_inset Flex Code
17737 \begin_layout Plain Layout
17744 \begin_inset Flex Code
17747 \begin_layout Plain Layout
17753 ] The tag to be used for paragraph and item labels, replacing
17754 \begin_inset Flex Code
17757 \begin_layout Plain Layout
17763 in the examples above.
17765 \begin_inset Flex Code
17768 \begin_layout Plain Layout
17775 \begin_inset Flex Code
17778 \begin_layout Plain Layout
17785 \begin_inset Flex Code
17788 \begin_layout Plain Layout
17795 \begin_inset Flex Code
17798 \begin_layout Plain Layout
17799 Centered_Top_Environment
17804 , in which case it defaults to
17805 \begin_inset Flex Code
17808 \begin_layout Plain Layout
17817 \begin_layout Description
17818 \begin_inset Flex Code
17821 \begin_layout Plain Layout
17828 \begin_inset Flex Code
17831 \begin_layout Plain Layout
17837 ] Attributes for the label tag.
17839 \begin_inset Quotes eld
17843 \begin_inset Flex Code
17846 \begin_layout Plain Layout
17847 class=`layoutname_label'
17853 \begin_inset Quotes erd
17861 contain any style information.
17863 \begin_inset Flex Code
17866 \begin_layout Plain Layout
17875 \begin_layout Description
17876 \begin_inset Flex Code
17879 \begin_layout Plain Layout
17886 \begin_inset Flex Code
17889 \begin_layout Plain Layout
17899 ] Meaningful only for list-like environments, this tag controls whether
17900 the label tag is output before or inside the item tag.
17901 This is used, for example, in the description environment, where we want
17903 \begin_inset Flex Code
17906 \begin_layout Plain Layout
17907 <dt>\SpecialChar \ldots{}
17908 </dt><dd>\SpecialChar \ldots{}
17916 \begin_inset Flex Code
17919 \begin_layout Plain Layout
17925 : The label tag is output inside the item tag.
17928 \begin_layout Description
17929 \begin_inset Flex Code
17932 \begin_layout Plain Layout
17938 Information to be output in the
17939 \begin_inset Flex Code
17942 \begin_layout Plain Layout
17948 section when this style is used.
17949 This might, for example, be used to include a
17950 \begin_inset Flex Code
17953 \begin_layout Plain Layout
17960 \begin_inset Flex Code
17963 \begin_layout Plain Layout
17972 \begin_layout Description
17973 \begin_inset Flex Code
17976 \begin_layout Plain Layout
17982 CSS style information to be included when this style is used.
17983 Note that this will automatically be wrapped in a layout-generated
17984 \begin_inset Flex Code
17987 \begin_layout Plain Layout
17993 block, so only the CSS itself need be included.
17996 \begin_layout Description
17997 \begin_inset Flex Code
18000 \begin_layout Plain Layout
18007 \begin_inset Flex Code
18010 \begin_layout Plain Layout
18016 ] The tag to be used for the main label, replacing
18017 \begin_inset Flex Code
18020 \begin_layout Plain Layout
18026 in the examples above.
18028 \begin_inset Flex Code
18031 \begin_layout Plain Layout
18040 \begin_layout Description
18041 \begin_inset Flex Code
18044 \begin_layout Plain Layout
18051 \begin_inset Flex Code
18054 \begin_layout Plain Layout
18064 ] Marks this style as the one to be used to generate the
18065 \begin_inset Flex Code
18068 \begin_layout Plain Layout
18074 tag for the XHTML file.
18075 By default, it is false.
18077 \begin_inset Flex Code
18080 \begin_layout Plain Layout
18086 file sets it to true for the
18087 \begin_inset Flex Code
18090 \begin_layout Plain Layout
18100 \begin_layout Subsection
18104 \begin_layout Standard
18105 The XHTML output of insets can also be controlled by information in layout
18110 \begin_layout Plain Layout
18111 At present, this is true only for
18112 \begin_inset Quotes eld
18116 \begin_inset Quotes erd
18119 insets (insets you can type into) and is not true for
18120 \begin_inset Quotes eld
18124 \begin_inset Quotes erd
18127 insets (insets that are associated with dialog boxes).
18132 Here, too, LyX tries to provide sensible defaults, and it constructs default
18134 But everything can be customized.
18137 \begin_layout Standard
18138 The XHTML LyX outputs for an inset has the following form:
18141 \begin_layout LyX-Code
18143 \begin_inset Quotes erd
18147 \begin_inset Quotes erd
18153 \begin_layout LyX-Code
18154 <labeltag>Label</labeltag>
18157 \begin_layout LyX-Code
18159 \begin_inset Quotes erd
18163 \begin_inset Quotes erd
18166 >Contents of the inset.</innertag>
18169 \begin_layout LyX-Code
18173 \begin_layout Standard
18174 If the inset permits multiple paragraphs---that is, if
18175 \begin_inset Flex Code
18178 \begin_layout Plain Layout
18184 is true---then the contents of the inset will itself be output as paragraphs
18185 formatted according to the styles used for those paragraphs (standard,
18186 quote, and the like).
18187 The label tag is of course omitted if the paragraph does not have a label
18188 and, at present, is always
18189 \begin_inset Flex Code
18192 \begin_layout Plain Layout
18199 The inner tag is optional and, by default, does not appear.
18202 \begin_layout Standard
18203 The specific tags and attributes output for each inset can be controlled
18204 by means of the following layout tags.
18207 \begin_layout Description
18208 \begin_inset Flex Code
18211 \begin_layout Plain Layout
18218 \begin_inset Flex Code
18221 \begin_layout Plain Layout
18227 ] Specifies attribute information to be output with the main tag.
18229 \begin_inset Quotes eld
18233 \begin_inset Flex Code
18236 \begin_layout Plain Layout
18237 class=`myinset' onclick=`\SpecialChar \ldots{}
18244 \begin_inset Quotes erd
18248 By default, LyX will output
18249 \begin_inset Quotes eld
18253 \begin_inset Flex Code
18256 \begin_layout Plain Layout
18263 \begin_inset Quotes erd
18267 \begin_inset Flex Code
18270 \begin_layout Plain Layout
18276 is the LyX name of the inset, made lowercase and with non-alphanumeric
18277 characters converted to underscores, for example: footnote.
18280 \begin_layout Description
18281 \begin_inset Flex Code
18284 \begin_layout Plain Layout
18291 \begin_inset Flex Code
18294 \begin_layout Plain Layout
18304 ] Whether to output the default CSS information LyX generates for this layout,
18305 even if additional information is explicitly provided via
18306 \begin_inset Flex Code
18309 \begin_layout Plain Layout
18317 \begin_inset Flex Code
18320 \begin_layout Plain Layout
18326 allows you to alter or augment the generated CSS, rather than to override
18331 \begin_layout Description
18332 \begin_inset Flex Code
18335 \begin_layout Plain Layout
18342 \begin_inset Flex Code
18345 \begin_layout Plain Layout
18351 ] Attributes for the inner tag.
18353 \begin_inset Quotes eld
18357 \begin_inset Flex Code
18360 \begin_layout Plain Layout
18361 class=`insetname_inner'
18367 \begin_inset Quotes erd
18373 \begin_layout Description
18374 \begin_inset Flex Code
18377 \begin_layout Plain Layout
18384 \begin_inset Flex Code
18387 \begin_layout Plain Layout
18393 ] The inner tag, replacing
18394 \begin_inset Flex Code
18397 \begin_layout Plain Layout
18403 in the examples above.
18404 By default, there is none.
18407 \begin_layout Description
18408 \begin_inset Flex Code
18411 \begin_layout Plain Layout
18418 \begin_inset Flex Code
18421 \begin_layout Plain Layout
18429 ] Whether this inset represents a standalone block of text (such as a footnote)
18430 or instead represents material that is included in the surrounding text
18431 (such as a branch).
18435 \begin_layout Description
18436 \begin_inset Flex Code
18439 \begin_layout Plain Layout
18446 \begin_inset Flex Code
18449 \begin_layout Plain Layout
18455 ] A label for this inset, possibly including a reference to a counter.
18456 For example, for footnote, it might be:
18457 \begin_inset Flex Code
18460 \begin_layout Plain Layout
18469 This is optional, and there is no default.
18472 \begin_layout Description
18473 \begin_inset Flex Code
18476 \begin_layout Plain Layout
18482 Information to be output in the
18483 \begin_inset Flex Code
18486 \begin_layout Plain Layout
18492 section when this style is used.
18493 This might, for example, be used to include a
18494 \begin_inset Flex Code
18497 \begin_layout Plain Layout
18504 \begin_inset Flex Code
18507 \begin_layout Plain Layout
18516 \begin_layout Description
18517 \begin_inset Flex Code
18520 \begin_layout Plain Layout
18526 CSS style information to be included when this style is used.
18527 Note that this will automatically be wrapped in a layout-generated
18528 \begin_inset Flex Code
18531 \begin_layout Plain Layout
18537 block, so only the CSS itself need be included.
18540 \begin_layout Description
18541 \begin_inset Flex Code
18544 \begin_layout Plain Layout
18551 \begin_inset Flex Code
18554 \begin_layout Plain Layout
18560 ] The tag to be used for the main label, replacing
18561 \begin_inset Flex Code
18564 \begin_layout Plain Layout
18570 in the examples above.
18571 The default depends upon the setting of
18572 \begin_inset Flex Code
18575 \begin_layout Plain Layout
18582 \begin_inset Flex Code
18585 \begin_layout Plain Layout
18591 is true, the default is
18592 \begin_inset Flex Code
18595 \begin_layout Plain Layout
18601 ; if it is false, the default is
18602 \begin_inset Flex Code
18605 \begin_layout Plain Layout
18614 \begin_layout Subsection
18618 \begin_layout Standard
18619 The XHTML output for floats too can be controlled by layout information.
18620 The output has the following form:
18623 \begin_layout LyX-Code
18625 \begin_inset Quotes erd
18629 \begin_inset Quotes erd
18635 \begin_layout LyX-Code
18636 Contents of the float.
18639 \begin_layout LyX-Code
18643 \begin_layout Standard
18644 The caption, if there is one, is a separate inset and will be output as
18646 Its appearance can be controlled via the InsetLayout for caption insets.
18650 \begin_layout Description
18651 \begin_inset Flex Code
18654 \begin_layout Plain Layout
18661 \begin_inset Flex Code
18664 \begin_layout Plain Layout
18670 ] Specifies attribute information to be output with the main tag.
18672 \begin_inset Quotes eld
18676 \begin_inset Flex Code
18679 \begin_layout Plain Layout
18680 class=`myfloat' onclick=`\SpecialChar \ldots{}
18687 \begin_inset Quotes erd
18691 By default, LyX will output
18692 \begin_inset Quotes eld
18696 \begin_inset Flex Code
18699 \begin_layout Plain Layout
18700 class=`float float-floattype'
18706 \begin_inset Quotes erd
18710 \begin_inset Flex Code
18713 \begin_layout Plain Layout
18719 is LyX's name for this type of float, as determined by the float declaration
18721 \begin_inset CommandInset ref
18723 reference "sub:Floats"
18727 ), though made lowercase and with non-alphanumeric characters converted
18728 to underscores, for example: float-table.
18731 \begin_layout Description
18732 \begin_inset Flex Code
18735 \begin_layout Plain Layout
18741 CSS style information to be included when this float is used.
18742 Note that this will automatically be wrapped in a layout-generated
18743 \begin_inset Flex Code
18746 \begin_layout Plain Layout
18752 block, so only the CSS itself need be included.
18755 \begin_layout Description
18756 \begin_inset Flex Code
18759 \begin_layout Plain Layout
18766 \begin_inset Flex Code
18769 \begin_layout Plain Layout
18775 ] The tag to be used for this float, replacing
18776 \begin_inset Quotes eld
18780 \begin_inset Flex Code
18783 \begin_layout Plain Layout
18790 \begin_inset Quotes erd
18793 in the example above.
18795 \begin_inset Flex Code
18798 \begin_layout Plain Layout
18804 and will rarely need changing.
18807 \begin_layout Subsection
18808 Bibliography formatting
18811 \begin_layout Standard
18812 The bibliography can be formatted using
18813 \begin_inset Flex Code
18816 \begin_layout Plain Layout
18824 \begin_inset CommandInset ref
18826 reference "sub:Citation-format-description"
18833 \begin_layout Subsection
18837 \begin_layout Standard
18838 We have several times mentioned that LyX will generate default CSS style
18839 rules for both insets and paragraph styles, based upon the other layout
18840 information that is provided.
18841 In this section, we shall say a word about which layout information LyX
18845 \begin_layout Standard
18846 At present, LyX auto-generates CSS only for font information, making use
18848 \begin_inset Flex Code
18851 \begin_layout Plain Layout
18858 \begin_inset Flex Code
18861 \begin_layout Plain Layout
18868 \begin_inset Flex Code
18871 \begin_layout Plain Layout
18878 \begin_inset Flex Code
18881 \begin_layout Plain Layout
18888 \begin_inset Flex Code
18891 \begin_layout Plain Layout
18899 \begin_inset CommandInset ref
18901 reference "sub:Font-description"
18905 .) The translation is mostly straightforward and obvious.
18907 \begin_inset Quotes eld
18911 \begin_inset Flex Code
18914 \begin_layout Plain Layout
18921 \begin_inset Quotes erd
18925 \begin_inset Quotes eld
18929 \begin_inset Flex Code
18932 \begin_layout Plain Layout
18933 font-family: sans-serif;
18939 \begin_inset Quotes erd
18943 The correspondence of LyX sizes and CSS sizes is a little less obvious
18944 but nonetheless intuitive.
18946 \begin_inset Flex Code
18949 \begin_layout Plain Layout
18956 \begin_inset Flex URL
18959 \begin_layout Plain Layout
18970 \begin_layout Chapter
18971 Including External Material
18974 \begin_layout Standard
18975 \begin_inset Box Shadowbox
18985 height_special "totalheight"
18988 \begin_layout Plain Layout
18989 WARNING: This portion of the documentation has not been updated for some
18991 We certainly hope that it is still accurate, but there are no guarantees.
18999 \begin_layout Standard
19000 The use of material from sources external to LyX is covered in detail in
19006 This part of the manual covers what needs to happen behind the scenes for
19007 new sorts of material to be included.
19010 \begin_layout Section
19014 \begin_layout Standard
19015 The external material feature is based on the concept of a
19020 A template is a specification of how LyX should interface with a certain
19022 As bundled, LyX comes with predefined templates for Xfig figures, various
19023 raster format images, chess diagrams, and LilyPond music notation.
19024 You can check the actual list by using the menu
19025 \begin_inset Flex MenuItem
19028 \begin_layout Plain Layout
19029 Insert\SpecialChar \menuseparator
19030 File\SpecialChar \menuseparator
19037 Furthermore, it is possible to roll your own template to support a specific
19039 Later we'll describe in more detail what is involved, and hopefully you
19040 will submit all the templates you create so we can include them in a later
19044 \begin_layout Standard
19045 Another basic idea of the external material feature is to distinguish between
19046 the original file that serves as a base for final material and the produced
19047 file that is included in your exported or printed document.
19048 For example, consider the case of a figure produced with
19049 \begin_inset Flex Code
19052 \begin_layout Plain Layout
19059 The Xfig application itself works on an original file with the
19060 \begin_inset Flex Code
19063 \begin_layout Plain Layout
19070 Within Xfig, you create and change your figure, and when you are done,
19072 \begin_inset Flex Code
19075 \begin_layout Plain Layout
19082 When you want to include the figure in your document, you invoke
19083 \begin_inset Flex Code
19086 \begin_layout Plain Layout
19092 in order to create a PostScript file that can readily be included in your
19095 \begin_inset Flex Code
19098 \begin_layout Plain Layout
19104 file is the original file, and the PostScript file is the produced file.
19107 \begin_layout Standard
19108 This distinction is important in order to allow updating of the material
19109 while you are in the process of writing the document.
19110 Furthermore, it provides us with the flexibility that is needed to support
19111 multiple export formats.
19112 For instance, in the case of a plain text file, it is not exactly an award-winn
19113 ing idea to include the figure as raw PostScript.
19114 Instead, you'd either prefer to just include a reference to the figure
19115 or try to invoke some graphics to ASCII converter to make the final result
19116 look similar to the real graphics.
19117 The external material management allows you to do this, because it is parametri
19118 zed on the different export formats that LyX supports.
19121 \begin_layout Standard
19122 Besides supporting the production of different products according to the
19123 exported format, it supports tight integration with editing and viewing
19125 In the case of an Xfig figure, you are able to invoke Xfig on the original
19126 file with a single click from within the external material dialog in LyX,
19127 and also preview the produced PostScript file with Ghostview with another
19129 No more fiddling around with the command line and/or file browsers to locate
19130 and manipulate the original or produced files.
19131 In this way, you are finally able to take full advantage of the many different
19132 applications that are relevant to use when you write your documents, and
19133 ultimately be more productive.
19136 \begin_layout Section
19137 The external template configuration file
19140 \begin_layout Standard
19141 It is relatively easy to add custom external template definitions to LyX.
19142 However, be aware that doing this in an careless manner most probably
19146 introduce an easily exploitable security hole.
19147 So before you do this, please read the discussion about security in section
19149 \begin_inset CommandInset ref
19151 reference "sec:Security-discussion"
19158 \begin_layout Standard
19159 Having said that, we encourage you to submit any interesting templates that
19164 \begin_layout Standard
19165 The external templates are defined in the
19166 \begin_inset Flex Code
19169 \begin_layout Plain Layout
19170 LyXDir/lib/external_templates
19176 You can place your own version in
19177 \begin_inset Flex Code
19180 \begin_layout Plain Layout
19181 UserDir/external_templates
19189 \begin_layout Standard
19190 A typical template looks like this:
19193 \begin_layout LyX-Code
19197 \begin_layout LyX-Code
19198 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
19201 \begin_layout LyX-Code
19205 \begin_layout LyX-Code
19209 \begin_layout LyX-Code
19213 \begin_layout LyX-Code
19217 \begin_layout LyX-Code
19221 \begin_layout LyX-Code
19222 AutomaticProduction true
19225 \begin_layout LyX-Code
19229 \begin_layout LyX-Code
19233 \begin_layout LyX-Code
19237 \begin_layout LyX-Code
19238 TransformCommand Rotate RotationLatexCommand
19241 \begin_layout LyX-Code
19242 TransformCommand Resize ResizeLatexCommand
19245 \begin_layout LyX-Code
19246 Product "$$RotateFront$$ResizeFront
19249 \begin_layout LyX-Code
19254 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
19257 \begin_layout LyX-Code
19258 $$ResizeBack$$RotateBack"
19261 \begin_layout LyX-Code
19265 \begin_layout LyX-Code
19266 UpdateResult "$$AbsPath$$Basename.pstex_t"
19269 \begin_layout LyX-Code
19270 Requirement "graphicx"
19273 \begin_layout LyX-Code
19274 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
19277 \begin_layout LyX-Code
19278 ReferencedFile latex "$$AbsPath$$Basename.eps"
19281 \begin_layout LyX-Code
19282 ReferencedFile dvi "$$AbsPath$$Basename.eps"
19285 \begin_layout LyX-Code
19289 \begin_layout LyX-Code
19293 \begin_layout LyX-Code
19294 TransformCommand Rotate RotationLatexCommand
19297 \begin_layout LyX-Code
19298 TransformCommand Resize ResizeLatexCommand
19301 \begin_layout LyX-Code
19302 Product "$$RotateFront$$ResizeFront
19305 \begin_layout LyX-Code
19310 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
19313 \begin_layout LyX-Code
19314 $$ResizeBack$$RotateBack"
19317 \begin_layout LyX-Code
19318 UpdateFormat pdftex
19321 \begin_layout LyX-Code
19322 UpdateResult "$$AbsPath$$Basename.pdftex_t"
19325 \begin_layout LyX-Code
19326 Requirement "graphicx"
19329 \begin_layout LyX-Code
19330 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
19333 \begin_layout LyX-Code
19334 ReferencedFile latex "$$AbsPath$$Basename.pdf"
19337 \begin_layout LyX-Code
19341 \begin_layout LyX-Code
19345 \begin_layout LyX-Code
19346 Product "$$Contents(
19348 "$$AbsPath$$Basename.asc
19353 \begin_layout LyX-Code
19354 UpdateFormat asciixfig
19357 \begin_layout LyX-Code
19358 UpdateResult "$$AbsPath$$Basename.asc"
19361 \begin_layout LyX-Code
19365 \begin_layout LyX-Code
19369 \begin_layout LyX-Code
19370 Product "<graphic fileref=
19372 "$$AbsOrRelPathMaster$$Basename.eps
19377 \begin_layout LyX-Code
19381 \begin_layout LyX-Code
19385 \begin_layout LyX-Code
19386 UpdateResult "$$AbsPath$$Basename.eps"
19389 \begin_layout LyX-Code
19390 ReferencedFile docbook "$$AbsPath$$Basename.eps"
19393 \begin_layout LyX-Code
19394 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
19397 \begin_layout LyX-Code
19401 \begin_layout LyX-Code
19402 Product "[XFig: $$FName]"
19405 \begin_layout LyX-Code
19409 \begin_layout LyX-Code
19413 \begin_layout Standard
19414 As you can see, the template is enclosed in
19415 \begin_inset Flex Code
19418 \begin_layout Plain Layout
19424 \SpecialChar \ldots{}
19426 \begin_inset Flex Code
19429 \begin_layout Plain Layout
19436 It contains a header specifying some general settings and, for each supported
19437 primary document file format, a section
19438 \begin_inset Flex Code
19441 \begin_layout Plain Layout
19447 \SpecialChar \ldots{}
19449 \begin_inset Flex Code
19452 \begin_layout Plain Layout
19461 \begin_layout Subsection
19462 The template header
19465 \begin_layout Description
19466 \begin_inset Flex Code
19469 \begin_layout Plain Layout
19470 AutomaticProduction
19471 \begin_inset space ~
19479 Whether the file represented by the template must be generated by LyX.
19480 This command must occur exactly once.
19483 \begin_layout Description
19484 \begin_inset Flex Code
19487 \begin_layout Plain Layout
19489 \begin_inset space ~
19497 A glob pattern that is used in the file dialog to filter out the desired
19499 If there is more than one possible file extension (e.
19500 \begin_inset space \thinspace{}
19504 \begin_inset space \space{}
19508 \begin_inset Flex Code
19511 \begin_layout Plain Layout
19518 \begin_inset Flex Code
19521 \begin_layout Plain Layout
19527 ), use something like
19528 \begin_inset Flex Code
19531 \begin_layout Plain Layout
19538 This command must occur exactly once.
19541 \begin_layout Description
19542 \begin_inset Flex Code
19545 \begin_layout Plain Layout
19547 \begin_inset space ~
19555 The text that is displayed on the button.
19556 This command must occur exactly once.
19559 \begin_layout Description
19560 \begin_inset Flex Code
19563 \begin_layout Plain Layout
19565 \begin_inset space ~
19569 \begin_inset space ~
19577 The help text that is used in the External dialog.
19578 Provide enough information to explain to the user just what the template
19579 can provide him with.
19580 This command must occur exactly once.
19583 \begin_layout Description
19584 \begin_inset Flex Code
19587 \begin_layout Plain Layout
19589 \begin_inset space ~
19597 The file format of the original file.
19598 This must be the name of a format that is known to LyX (see section
19599 \change_inserted 34634807 1296982650
19601 \begin_inset space ~
19605 \change_deleted 34634807 1296982649
19609 \begin_inset CommandInset ref
19611 reference "sec:Formats"
19617 \begin_inset Quotes eld
19621 \begin_inset Flex Code
19624 \begin_layout Plain Layout
19631 \begin_inset Quotes erd
19634 if the template can handle original files of more than one format.
19635 LyX will attempt to interrogate the file itself in order to deduce its
19636 format in this case.
19637 This command must occur exactly once.
19640 \begin_layout Description
19641 \begin_inset Flex Code
19644 \begin_layout Plain Layout
19646 \begin_inset space ~
19654 A unique name for the template.
19655 It must not contain substitution macros (see below).
19658 \begin_layout Description
19659 \begin_inset Flex Code
19662 \begin_layout Plain Layout
19664 \begin_inset space ~
19667 Rotate|Resize|Clip|Extra
19672 This command specifies which transformations are supported by this template.
19673 It may occur zero or more times.
19674 This command enables the corresponding tabs in the external dialog.
19676 \begin_inset Flex Code
19679 \begin_layout Plain Layout
19685 command must have either a corresponding
19686 \begin_inset Flex Code
19689 \begin_layout Plain Layout
19696 \begin_inset Flex Code
19699 \begin_layout Plain Layout
19706 \begin_inset Flex Code
19709 \begin_layout Plain Layout
19716 Otherwise the transformation will not be supported by that format.
19719 \begin_layout Subsection
19723 \begin_layout Description
19724 \begin_inset Flex Code
19727 \begin_layout Plain Layout
19729 \begin_inset space ~
19732 LaTeX|PDFLaTeX|PlainText|DocBook
19737 The primary document file format that this format definition is for.
19738 Not every template has a sensible representation in all document file formats.
19739 Please define nevertheless a
19740 \begin_inset Flex Code
19743 \begin_layout Plain Layout
19750 \change_deleted 34634807 1296982695
19752 \change_inserted 34634807 1296982711
19754 \begin_inset Note Note
19757 \begin_layout Plain Layout
19759 \change_inserted 34634807 1296982711
19760 format or template here ?
19768 Use a dummy text when no representation is available.
19769 Then you can at least see a reference to the external material in the exported
19773 \begin_layout Description
19774 \begin_inset Flex Code
19777 \begin_layout Plain Layout
19779 \begin_inset space ~
19783 \begin_inset space ~
19791 This command defines an additional macro
19792 \begin_inset Flex Code
19795 \begin_layout Plain Layout
19801 for substitution in
19802 \begin_inset Flex Code
19805 \begin_layout Plain Layout
19813 \begin_inset Flex Code
19816 \begin_layout Plain Layout
19822 itself may contain substitution macros.
19823 The advantage over using
19824 \begin_inset Flex Code
19827 \begin_layout Plain Layout
19834 \begin_inset Flex Code
19837 \begin_layout Plain Layout
19843 is that the substituted value of
19844 \begin_inset Flex Code
19847 \begin_layout Plain Layout
19853 is sanitized so that it is a valid optional argument in the document format.
19854 This command may occur zero or more times.
19857 \begin_layout Description
19858 \begin_inset Flex Code
19861 \begin_layout Plain Layout
19863 \begin_inset space ~
19871 The text that is inserted in the exported document.
19872 This is actually the most important command and can be quite complex.
19873 This command must occur exactly once.
19876 \begin_layout Description
19877 \begin_inset Flex Code
19880 \begin_layout Plain Layout
19882 \begin_inset space ~
19890 This command specifies a preamble snippet that will be included in the
19892 It has to be defined using
19893 \begin_inset Flex Code
19896 \begin_layout Plain Layout
19902 \SpecialChar \ldots{}
19904 \begin_inset Flex Code
19907 \begin_layout Plain Layout
19914 This command may occur zero or more times.
19917 \begin_layout Description
19918 \begin_inset Flex Code
19921 \begin_layout Plain Layout
19923 \begin_inset space ~
19927 \begin_inset space ~
19935 This command denotes files that are created by the conversion process and
19936 are needed for a particular export format.
19937 If the filename is relative, it is interpreted relative to the master document.
19938 This command may be given zero or more times.
19941 \begin_layout Description
19942 \begin_inset Flex Code
19945 \begin_layout Plain Layout
19947 \begin_inset space ~
19955 The name of a required LaTeX package.
19956 The package is included via
19957 \begin_inset Flex Code
19960 \begin_layout Plain Layout
19968 in the LaTeX preamble.
19969 This command may occur zero or more times.
19972 \begin_layout Description
19973 \begin_inset Flex Code
19976 \begin_layout Plain Layout
19978 \begin_inset space ~
19982 \begin_inset space ~
19985 RotationLatexCommand
19990 This command specifies that the built in LaTeX command should be used for
19992 This command may occur once or not at all.
19995 \begin_layout Description
19996 \begin_inset Flex Code
19999 \begin_layout Plain Layout
20001 \begin_inset space ~
20005 \begin_inset space ~
20013 This command specifies that the built in LaTeX command should be used for
20015 This command may occur once or not at all.
20018 \begin_layout Description
20019 \begin_inset Flex Code
20022 \begin_layout Plain Layout
20024 \begin_inset space ~
20028 \begin_inset space ~
20031 RotationLatexOption
20036 This command specifies that rotation is done via an optional argument.
20037 This command may occur once or not at all.
20040 \begin_layout Description
20041 \begin_inset Flex Code
20044 \begin_layout Plain Layout
20046 \begin_inset space ~
20050 \begin_inset space ~
20058 This command specifies that resizing is done via an optional argument.
20059 This command may occur once or not at all.
20062 \begin_layout Description
20063 \begin_inset Flex Code
20066 \begin_layout Plain Layout
20068 \begin_inset space ~
20072 \begin_inset space ~
20080 This command specifies that clipping is done via an optional argument.
20081 This command may occur once or not at all.
20084 \begin_layout Description
20085 \begin_inset Flex Code
20088 \begin_layout Plain Layout
20090 \begin_inset space ~
20094 \begin_inset space ~
20102 This command specifies that an extra optional argument is used.
20103 This command may occur once or not at all.
20106 \begin_layout Description
20107 \begin_inset Flex Code
20110 \begin_layout Plain Layout
20112 \begin_inset space ~
20120 The file format of the converted file.
20121 This must be the name of a format that is known to LyX (see the
20122 \begin_inset Flex MenuItem
20125 \begin_layout Plain Layout
20130 ools\SpecialChar \menuseparator
20136 \change_deleted 34634807 1296982746
20138 \change_inserted 34634807 1296982770
20140 \begin_inset space ~
20143 handling\SpecialChar \menuseparator
20145 \begin_inset space ~
20156 This command must occur exactly once.
20159 \begin_layout Description
20160 \begin_inset Flex Code
20163 \begin_layout Plain Layout
20165 \begin_inset space ~
20173 The file name of the converted file.
20174 The file name must be absolute.
20175 This command must occur exactly once.
20178 \begin_layout Subsection
20179 Preamble definitions
20182 \begin_layout Standard
20183 The external template configuration file may contain additional preamble
20184 definitions enclosed by
20185 \begin_inset Flex Code
20188 \begin_layout Plain Layout
20194 \SpecialChar \ldots{}
20196 \begin_inset Flex Code
20199 \begin_layout Plain Layout
20206 They can be used by the templates in the
20207 \begin_inset Flex Code
20210 \begin_layout Plain Layout
20219 \begin_layout Section
20220 The substitution mechanism
20223 \begin_layout Standard
20224 When the external material facility invokes an external program, it is done
20225 on the basis of a command defined in the template configuration file.
20226 These commands can contain various macros that are expanded before execution.
20227 Execution always take place in the directory of the containing document.
20230 \begin_layout Standard
20231 Also, whenever external material is to be displayed, the name will be produced
20232 by the substitution mechanism, and most other commands in the template
20233 definition support substitution as well.
20236 \begin_layout Standard
20237 The available macros are the following:
20240 \begin_layout Description
20241 \begin_inset Flex Code
20244 \begin_layout Plain Layout
20245 $$AbsOrRelPathMaster
20250 The file path, absolute or relative to the master LyX document.
20253 \begin_layout Description
20254 \begin_inset Flex Code
20257 \begin_layout Plain Layout
20258 $$AbsOrRelPathParent
20263 The file path, absolute or relative to the LyX document.
20266 \begin_layout Description
20267 \begin_inset Flex Code
20270 \begin_layout Plain Layout
20276 The absolute file path.
20279 \begin_layout Description
20280 \begin_inset Flex Code
20283 \begin_layout Plain Layout
20289 The filename without path and without the extension.
20292 \begin_layout Description
20293 \begin_inset Flex Code
20296 \begin_layout Plain Layout
20298 \begin_inset Quotes eld
20302 \begin_inset Quotes erd
20310 This macro will expand to the contents of the file with the name
20311 \begin_inset Flex Code
20314 \begin_layout Plain Layout
20323 \begin_layout Description
20324 \begin_inset Flex Code
20327 \begin_layout Plain Layout
20333 The file extension (including the dot).
20336 \begin_layout Description
20337 \begin_inset Flex Code
20340 \begin_layout Plain Layout
20346 The filename of the file specified in the external material dialog.
20347 This is either an absolute name, or it is relative to the LyX document.
20350 \begin_layout Description
20351 \begin_inset Flex Code
20354 \begin_layout Plain Layout
20361 \begin_inset Flex Code
20364 \begin_layout Plain Layout
20370 (absolute name or relative to the LyX document).
20373 \begin_layout Description
20374 \begin_inset Flex Code
20377 \begin_layout Plain Layout
20383 The file path, relative to the master LyX document.
20386 \begin_layout Description
20387 \begin_inset Flex Code
20390 \begin_layout Plain Layout
20396 The file path, relative to the LyX document.
20399 \begin_layout Description
20400 \begin_inset Flex Code
20403 \begin_layout Plain Layout
20409 This macro will expand to the absolute path of the system directory.
20410 This is typically used to point to the various helper scripts that are
20414 \begin_layout Description
20415 \begin_inset Flex Code
20418 \begin_layout Plain Layout
20424 A name and full path to a temporary file which will be automatically deleted
20425 whenever the containing document is closed, or the external material insertion
20429 \begin_layout Standard
20430 All path macros contain a trailing directory separator, so you can construct
20432 \begin_inset space \thinspace{}
20436 \begin_inset space \space{}
20439 the absolute filename with
20440 \begin_inset Flex Code
20443 \begin_layout Plain Layout
20444 $$AbsPath$$Basename$$Extension
20452 \begin_layout Standard
20453 The macros above are substituted in all commands unless otherwise noted.
20455 \begin_inset Flex Code
20458 \begin_layout Plain Layout
20464 supports additionally the following substitutions if they are enabled by
20466 \begin_inset Flex Code
20469 \begin_layout Plain Layout
20476 \begin_inset Flex Code
20479 \begin_layout Plain Layout
20488 \begin_layout Description
20489 \begin_inset Flex Code
20492 \begin_layout Plain Layout
20498 The front part of the resize command.
20501 \begin_layout Description
20502 \begin_inset Flex Code
20505 \begin_layout Plain Layout
20511 The back part of the resize command.
20514 \begin_layout Description
20515 \begin_inset Flex Code
20518 \begin_layout Plain Layout
20524 The front part of the rotation command.
20527 \begin_layout Description
20528 \begin_inset Flex Code
20531 \begin_layout Plain Layout
20537 The back part of the rotation command.
20540 \begin_layout Standard
20541 The value string of the
20542 \begin_inset Flex Code
20545 \begin_layout Plain Layout
20551 command supports additionally the following substitutions if they are enabled
20553 \begin_inset Flex Code
20556 \begin_layout Plain Layout
20563 \begin_inset Flex Code
20566 \begin_layout Plain Layout
20575 \begin_layout Description
20576 \begin_inset Flex Code
20579 \begin_layout Plain Layout
20588 \begin_layout Description
20589 \begin_inset Flex Code
20592 \begin_layout Plain Layout
20601 \begin_layout Description
20602 \begin_inset Flex Code
20605 \begin_layout Plain Layout
20614 \begin_layout Description
20615 \begin_inset Flex Code
20618 \begin_layout Plain Layout
20624 The rotation option.
20627 \begin_layout Standard
20628 You may ask why there are so many path macros.
20629 There are mainly two reasons:
20632 \begin_layout Enumerate
20633 Relative and absolute file names should remain relative or absolute, respectivel
20635 Users may have reasons to prefer either form.
20636 Relative names are useful for portable documents that should work on different
20637 machines, for example.
20638 Absolute names may be required by some programs.
20641 \begin_layout Enumerate
20642 LaTeX treats relative file names differently than LyX and other programs
20643 in nested included files.
20644 For LyX, a relative file name is always relative to the document that contains
20646 For LaTeX, it is always relative to the master document.
20647 These two definitions are identical if you have only one document, but
20648 differ if you have a master document that includes part documents.
20649 That means that relative filenames must be transformed when presented to
20651 Fortunately LyX does this automatically for you if you choose the right
20655 \begin_layout Standard
20656 So which path macro should be used in new template definitions? The rule
20660 \begin_layout Itemize
20662 \begin_inset Flex Code
20665 \begin_layout Plain Layout
20671 if an absolute path is required.
20674 \begin_layout Itemize
20676 \begin_inset Flex Code
20679 \begin_layout Plain Layout
20680 $$AbsOrRelPathMaster
20685 if the substituted string is some kind of LaTeX input.
20688 \begin_layout Itemize
20690 \begin_inset Flex Code
20693 \begin_layout Plain Layout
20694 $$AbsOrRelPathParent
20699 in order to preserve the user's choice.
20702 \begin_layout Standard
20703 There are special cases where this rule does not work and e.
20704 \begin_inset space \thinspace{}
20708 \begin_inset space \space{}
20711 relative names are needed, but normally it will work just fine.
20712 One example for such a case is the command
20713 \begin_inset Flex Code
20716 \begin_layout Plain Layout
20717 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
20722 in the XFig template above: We can't use the absolute name because the
20724 \begin_inset Flex Code
20727 \begin_layout Plain Layout
20733 files needs the relative name in order to rewrite the file content.
20736 \begin_layout Section
20737 Security discussion
20738 \begin_inset CommandInset label
20740 name "sec:Security-discussion"
20747 \begin_layout Standard
20748 The external material feature interfaces with a lot of external programs
20749 and does so automatically, so we have to consider the security implications
20751 In particular, since you have the option of including your own filenames
20752 and/or parameter strings and those are expanded into a command, it seems
20753 that it would be possible to create a malicious document which executes
20754 arbitrary commands when a user views or prints the document.
20755 This is something we definitely want to avoid.
20758 \begin_layout Standard
20759 However, since the external program commands are specified in the template
20760 configuration file only, there are no security issues if LyX is properly
20761 configured with safe templates only.
20762 This is so because the external programs are invoked with the
20763 \begin_inset Flex Code
20766 \begin_layout Plain Layout
20772 -system call rather than the
20773 \begin_inset Flex Code
20776 \begin_layout Plain Layout
20782 system-call, so it's not possible to execute arbitrary commands from the
20783 filename or parameter section via the shell.
20786 \begin_layout Standard
20787 This also implies that you are restricted in what command strings you can
20788 use in the external material templates.
20789 In particular, pipes and redirection are not readily available.
20790 This has to be so if LyX should remain safe.
20791 If you want to use some of the shell features, you should write a safe
20792 script to do this in a controlled manner, and then invoke the script from
20793 the command string.
20797 \begin_layout Standard
20798 It is possible to design a template that interacts directly with the shell,
20799 but since this would allow a malicious user to execute arbitrary commands
20800 by writing clever filenames and/or parameters, we generally recommend that
20801 you only use safe scripts that work with the
20802 \begin_inset Flex Code
20805 \begin_layout Plain Layout
20811 system call in a controlled manner.
20812 Of course, for use in a controlled environment, it can be tempting to just
20813 fall back to use ordinary shell scripts.
20814 If you do so, be aware that you
20818 provide an easily exploitable security hole in your system.
20819 Of course it stands to reason that such unsafe templates will never be
20820 included in the standard LyX distribution, although we do encourage people
20821 to submit new templates in the open source tradition.
20822 But LyX as shipped from the official distribution channels will never have
20826 \begin_layout Standard
20827 Including external material provides a lot of power, and you have to be
20828 careful not to introduce security hazards with this power.
20829 A subtle error in a single line in an innocent looking script can open
20830 the door to huge security problems.
20831 So if you do not fully understand the issues, we recommend that you consult
20832 a knowledgeable security professional or the LyX development team if you
20833 have any questions about whether a given template is safe or not.
20834 And do this before you use it in an uncontrolled environment.