1 #LyX 2.0 created this file. For more info see http://www.lyx.org/
7 % DO NOT ALTER THIS PREAMBLE!!!
9 % This preamble is designed to ensure that this document prints
10 % out as advertised. If you mess with this preamble,
11 % parts of this document may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 % 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 Flex: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}}
73 \language_package default
78 \font_typewriter default
79 \font_default_family default
80 \use_non_tex_fonts false
87 \default_output_format default
89 \bibtex_command default
90 \index_command default
94 \pdf_title "LyX Configuration Manual"
95 \pdf_author "LyX Team"
96 \pdf_subject "LyX-documentation Customization"
97 \pdf_keywords "LyX, documentation, customization"
99 \pdf_bookmarksnumbered true
100 \pdf_bookmarksopen true
101 \pdf_bookmarksopenlevel 1
102 \pdf_breaklinks false
106 \pdf_pdfusetitle false
107 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
117 \paperorientation portrait
131 \paragraph_separation indent
132 \paragraph_indentation default
133 \quotes_language english
136 \paperpagestyle headings
137 \tracking_changes true
138 \output_changes false
142 \author 1414654397 "Richard Heck"
148 Customizing LyX: Features for the Advanced User
156 \begin_layout Plain Layout
158 If you have comments or error corrections, please send them to the LyX Documenta
160 \begin_inset CommandInset href
162 target "lyx-docs@lists.lyx.org"
169 \begin_inset Quotes eld
173 \begin_inset Quotes erd
176 in the subject header, and please cc the current maintainer of this file,
177 Richard Heck <rgheck@comcast.net>.
183 \begin_inset Newline newline
187 \begin_inset Newline newline
193 \begin_layout Standard
194 \begin_inset CommandInset toc
195 LatexCommand tableofcontents
202 \begin_layout Standard
203 \begin_inset Note Note
206 \begin_layout Plain Layout
207 Please use change tracking when modifying this document.
208 This makes it easier for our translators to recognize things that have
209 been changed, and it helps the maintainer keep up-to-date with what's been
218 \begin_layout Chapter
222 \begin_layout Standard
223 This manual covers the customization features present in LyX.
224 In it, we discuss issues like keyboard shortcuts, screen previewing options,
225 printer options, sending commands to LyX via the LyX Server, internationalizati
226 on, installing new LaTeX classes and LyX layouts, etc.
227 We can't possibly hope to touch on everything you can change—our developers
228 add new features faster than we can document them—but we will explain the
229 most common customizations and hopefully point you in the right direction
230 for some of the more obscure ones.
233 \begin_layout Standard
234 \begin_inset Branch OutDated
237 \begin_layout Standard
238 Information from previous versions of this document that now seems to be
239 outdated is contained in the OutDated branch of this document.
240 By default, this information will not appear in the LaTeX output.
248 \begin_layout Chapter
249 LyX configuration files
252 \begin_layout Standard
253 This chapter aims to help you to find your way through the LyX configuration
255 Before continuing to read this chapter, you should find out where your
256 LyX library and user directories are by using
257 \begin_inset Flex MenuItem
260 \begin_layout Plain Layout
261 Help\SpecialChar \menuseparator
272 The library directory is the place where LyX places its system-wide configurati
273 on files; the user directory is where you can place your modified versions.
274 We will call the former
275 \begin_inset Flex Code
278 \begin_layout Plain Layout
285 \begin_inset Flex MenuItem
288 \begin_layout Plain Layout
294 in the remainder of this document.
298 \begin_layout Section
300 \begin_inset Flex Code
303 \begin_layout Plain Layout
312 \begin_layout Standard
313 \begin_inset Flex Code
316 \begin_layout Plain Layout
322 and its sub-directories contain a number of files and that can be used
323 to customize LyX's behavior.
324 You can change many of these files from within LyX itself through the
325 \begin_inset Flex MenuItem
328 \begin_layout Plain Layout
329 Tools\SpecialChar \menuseparator
336 Most customization that you will want to do in LyX is possible through
338 However, many other inner aspects of LyX can be customized by modifying
340 \begin_inset Flex Code
343 \begin_layout Plain Layout
350 These files fall in different categories, described in the following subsection
354 \begin_layout Subsection
355 Automatically generated files
358 \begin_layout Standard
359 The files, which are to be found in
360 \begin_inset Flex MenuItem
363 \begin_layout Plain Layout
369 , are generated when you configure LyX.
370 They contain various default values that are guessed by inspection.
371 In general, it is not a good idea to modify them, since they might be overwritt
375 \begin_layout Labeling
376 \labelwidthstring 00.00.0000
377 \begin_inset Flex Code
380 \begin_layout Plain Layout
386 contains defaults for various commands.
389 \begin_layout Labeling
390 \labelwidthstring 00.00.0000
391 \begin_inset Flex Code
394 \begin_layout Plain Layout
400 contains the list of packages that have been recognized by LyX.
401 It is currently unused by the LyX program itself, but the information extracted
402 , and more, is made available with
403 \begin_inset Flex MenuItem
406 \begin_layout Plain Layout
407 Help\SpecialChar \menuseparator
420 \begin_layout Labeling
421 \labelwidthstring 00.00.0000
422 \begin_inset Flex Code
425 \begin_layout Plain Layout
431 the list of text classes that have been found in your
432 \begin_inset Flex Code
435 \begin_layout Plain Layout
441 directories, along with the associated LaTeX document class and their descripti
445 \begin_layout Labeling
446 \labelwidthstring 00.00.0000
447 \begin_inset Flex Code
450 \begin_layout Plain Layout
456 the list of layout modules found in your
457 \begin_inset Flex Code
460 \begin_layout Plain Layout
469 \begin_layout Labeling
470 \labelwidthstring 00.00.0000
471 \begin_inset Flex Code
474 \begin_layout Plain Layout
480 lists of various sorts of LaTeX-related files found on your system
483 \begin_layout Labeling
484 \labelwidthstring 00.00.0000
485 \begin_inset Flex Code
488 \begin_layout Plain Layout
494 is automatically generated during configuration from the file
495 \begin_inset Flex Code
498 \begin_layout Plain Layout
505 It contains information on your LaTeX configuration.
508 \begin_layout Subsection
512 \begin_layout Standard
513 These directories are duplicated between
514 \begin_inset Flex Code
517 \begin_layout Plain Layout
524 \begin_inset Flex Code
527 \begin_layout Plain Layout
534 If a particular files exists in both places, the one in
535 \begin_inset Flex Code
538 \begin_layout Plain Layout
547 \begin_layout Labeling
548 \labelwidthstring 00.00.0000
549 \begin_inset Flex Code
552 \begin_layout Plain Layout
558 this directory contains files with the extension
559 \begin_inset Flex Code
562 \begin_layout Plain Layout
568 that define the keybindings used in LyX.
569 If there exists an internationalized version of the bind file named
570 \begin_inset Flex Code
573 \begin_layout Plain Layout
579 , that will be used first.
582 \begin_layout Labeling
583 \labelwidthstring 00.00.0000
584 \begin_inset Flex Code
587 \begin_layout Plain Layout
593 contains graphics files that can be included in documents.
597 \begin_layout Labeling
598 \labelwidthstring 00.00.0000
599 \begin_inset Flex Code
602 \begin_layout Plain Layout
608 contains LyX documentation files (including the one you are currently reading).
610 \begin_inset Flex Code
613 \begin_layout Plain Layout
619 deserves special attention, as noted above.
620 The internationalized help docs are in subdirectories
621 \begin_inset Flex Code
624 \begin_layout Plain Layout
631 \begin_inset Quotes eld
635 \begin_inset Quotes erd
638 is the ISO language code.
644 \begin_inset CommandInset ref
646 reference "cha:Internationalizing-LyX"
653 \begin_layout Labeling
654 \labelwidthstring 00.00.0000
655 \begin_inset Flex Code
658 \begin_layout Plain Layout
664 contains example files that explain how to use some features.
665 In the file browser, press the
666 \begin_inset Flex MenuItem
669 \begin_layout Plain Layout
678 \begin_layout Labeling
679 \labelwidthstring 00.00.0000
680 \begin_inset Flex Code
683 \begin_layout Plain Layout
689 contains image files that are used by the
690 \begin_inset Flex MenuItem
693 \begin_layout Plain Layout
700 In addition, it also contains the individual icons used in the toolbar
701 and the banners that can be shown when LyX is launched.
704 \begin_layout Labeling
705 \labelwidthstring 00.00.0000
706 \begin_inset Flex Code
709 \begin_layout Plain Layout
715 contains keyboard keymapping files.
721 \begin_inset CommandInset ref
723 reference "sec:International-Keymap-Stuff"
730 \begin_layout Labeling
731 \labelwidthstring 00.00.0000
732 \begin_inset Flex Code
735 \begin_layout Plain Layout
741 contains the text class and module files described in Chapter
746 \begin_inset CommandInset ref
748 reference "cha:Installing-New-Document"
755 \begin_layout Labeling
756 \labelwidthstring 00.00.0000
757 \begin_inset Flex Code
760 \begin_layout Plain Layout
767 \begin_inset Flex Code
770 \begin_layout Plain Layout
776 Python scripts used to convert between LyX versions.
777 These can be run from the command line if, say, you want to batch-convert
781 \begin_layout Labeling
782 \labelwidthstring 00.00.0000
783 \begin_inset Flex Code
786 \begin_layout Plain Layout
792 contains some files that demonstrate the capabilities of the
793 \begin_inset Flex MenuItem
796 \begin_layout Plain Layout
807 Also contains some scripts used by LyX itself.
810 \begin_layout Labeling
811 \labelwidthstring 00.00.0000
812 \begin_inset Flex Code
815 \begin_layout Plain Layout
821 contains the standard LyX template files described in Chapter
826 \begin_inset CommandInset ref
828 reference "sub:Creating-Templates"
835 \begin_layout Labeling
836 \labelwidthstring 00.00.0000
837 \begin_inset Flex Code
840 \begin_layout Plain Layout
846 contains files with the extension
847 \begin_inset Flex Code
850 \begin_layout Plain Layout
856 that define the user interface to LyX.
857 That is, the files define which items appear in which menus and the items
858 appearing on the toolbar.
861 \begin_layout Subsection
862 Files you don't want to modify
865 \begin_layout Standard
866 These files are used internally by LyX and you generally do not need to
867 modify them unless you are a developer.
870 \begin_layout Labeling
871 \labelwidthstring 00.00.0000
872 \begin_inset Flex Code
875 \begin_layout Plain Layout
881 this file contains the list of LyX developers.
882 The contents are displayed with the menu entry
883 \begin_inset Flex MenuItem
886 \begin_layout Plain Layout
887 Help\SpecialChar \menuseparator
900 \begin_layout Labeling
901 \labelwidthstring 00.00.0000
902 \begin_inset Flex Code
905 \begin_layout Plain Layout
911 this is a LaTeX script used during the configuration process.
915 \begin_layout Labeling
916 \labelwidthstring 00.00.0000
917 \begin_inset Flex Code
920 \begin_layout Plain Layout
926 this is the script that is used to re-configure LyX.
927 It creates configuration files in the directory it was run from.
930 \begin_layout Subsection
931 Other files needing a line or two...
934 \begin_layout Labeling
935 \labelwidthstring 00.00.0000
936 \begin_inset Flex Code
939 \begin_layout Plain Layout
945 this contains tables describing how different character encodings can be
949 \begin_layout Labeling
950 \labelwidthstring 00.00.0000
951 \begin_inset Flex Code
954 \begin_layout Plain Layout
960 this file contains the templates available to the new
961 \begin_inset Flex MenuItem
964 \begin_layout Plain Layout
977 \begin_layout Labeling
978 \labelwidthstring 00.00.0000
979 \begin_inset Flex Code
982 \begin_layout Plain Layout
988 this file contains a list of all the languages currently supported by LyX.
991 \begin_layout Section
992 Your local configuration directory
995 \begin_layout Standard
996 Even if you are using LyX as an unprivileged user, you might want to change
997 LyX configuration for your own use.
999 \begin_inset Flex Code
1002 \begin_layout Plain Layout
1008 directory contains all your personal configuration files.
1009 This is the directory described as
1010 \begin_inset Quotes eld
1014 \begin_inset Quotes erd
1018 \begin_inset Flex MenuItem
1021 \begin_layout Plain Layout
1022 Help\SpecialChar \menuseparator
1024 \begin_inset space ~
1033 This directory is used as a mirror of
1034 \begin_inset Flex Code
1037 \begin_layout Plain Layout
1043 , which means that every file in
1044 \begin_inset Flex Code
1047 \begin_layout Plain Layout
1053 is a replacement for the corresponding file in
1054 \begin_inset Flex Code
1057 \begin_layout Plain Layout
1064 Any configuration file described in the above sections can be placed either
1065 in the system-wide directory, in which case it will affect all users, or
1066 in your local directory for your own use.
1069 \begin_layout Standard
1070 To make things clearer, let's provide a few examples:
1073 \begin_layout Itemize
1074 The preferences set in the
1075 \begin_inset Flex MenuItem
1078 \begin_layout Plain Layout
1079 Tools\SpecialChar \menuseparator
1085 dialog are saved to a file
1086 \begin_inset Flex Code
1089 \begin_layout Plain Layout
1096 \begin_inset Flex Code
1099 \begin_layout Plain Layout
1108 \begin_layout Itemize
1109 When you reconfigure using
1110 \begin_inset Flex MenuItem
1113 \begin_layout Plain Layout
1114 Tools\SpecialChar \menuseparator
1121 \begin_inset Flex Code
1124 \begin_layout Plain Layout
1130 script, and the resulting files are written in your local configuration
1132 This means that any additional text class file that you might have added
1134 \begin_inset Flex Code
1137 \begin_layout Plain Layout
1143 will be added to the list of classes in the
1144 \begin_inset Flex MenuItem
1147 \begin_layout Plain Layout
1148 Document\SpecialChar \menuseparator
1157 \begin_layout Itemize
1158 If you get some updated documentation from LyX ftp site and cannot install
1159 it because you do not have sysadmin rights on your system, you can just
1161 \begin_inset Flex Code
1164 \begin_layout Plain Layout
1170 and the items in the
1171 \begin_inset Flex MenuItem
1174 \begin_layout Plain Layout
1180 menu will open them!
1183 \begin_layout Section
1184 Running LyX with multiple configurations
1187 \begin_layout Standard
1188 The configuration freedom of the local configuration directory may not suffice
1189 if you want to have more than one configuration at your disposal.
1190 For example, you may want to be use different key bindings or printer settings
1192 You can achieve this by having several such directories.
1193 You then specify which directory to use at run-time.
1196 \begin_layout Standard
1197 Invoking LyX with the command line switch
1198 \begin_inset Flex Code
1201 \begin_layout Plain Layout
1211 instructs the program to read the configuration from that directory, and
1212 not from the default directory.
1213 (You can determine the default directory by running LyX without the
1214 \begin_inset Flex Code
1217 \begin_layout Plain Layout
1223 switch.) If the specified directory does not exist, LyX offers to create
1224 it for you, just like it does for the default directory on the first time
1225 you run the program.
1226 You can modify the configuration options in this additional user directory
1227 exactly as you would for the default directory.
1228 These directories are completely independent (but read on).
1229 Note that setting the environment variable
1230 \begin_inset Flex Code
1233 \begin_layout Plain Layout
1239 to some value has exactly the same effect.
1242 \begin_layout Standard
1243 Having several configurations also requires more maintenance: if you want
1244 to add a new layout to
1245 \begin_inset Flex Code
1248 \begin_layout Plain Layout
1254 which you want available from all your configurations, you must add it
1255 to each directory separately.
1256 You can avoid this with the following trick: after LyX creates the additional
1257 directory, most of the subdirectories (see above) are empty.
1258 If you want the new configuration to mirror an existing one, replace the
1259 empty subdirectory with a symbolic link to the matching subdirectory in
1260 the existing configuration.
1262 \begin_inset Flex Code
1265 \begin_layout Plain Layout
1271 subdirectory, however, since it contains a file written by the configuration
1272 script (also accessible through
1273 \begin_inset Flex MenuItem
1276 \begin_layout Plain Layout
1277 Tools\SpecialChar \menuseparator
1283 ) which is configuration-specific.
1286 \begin_layout Chapter
1287 The Preferences dialog
1290 \begin_layout Standard
1291 All options of the preferences dialog are described in the Appendix
1293 The Preferences Dialog
1300 For some options you might find here more details.
1303 \begin_layout Section
1305 \begin_inset CommandInset label
1314 \begin_layout Standard
1315 The first step is to define your file formats if they are not already defined.
1317 \begin_inset Flex MenuItem
1320 \begin_layout Plain Layout
1321 Tools\SpecialChar \menuseparator
1329 \begin_inset Flex MenuItem
1332 \begin_layout Plain Layout
1333 File Handling\SpecialChar \menuseparator
1340 \begin_inset Flex MenuItem
1343 \begin_layout Plain Layout
1344 New\SpecialChar \ldots{}
1350 button to define your new format.
1352 \begin_inset Flex MenuItem
1355 \begin_layout Plain Layout
1361 field contains the name used to identify the format in the GUI.
1363 \begin_inset Flex MenuItem
1366 \begin_layout Plain Layout
1372 is used to identify the format internally.
1373 You will also need to enter a file extension.
1374 These are all required.
1376 \begin_inset Flex MenuItem
1379 \begin_layout Plain Layout
1385 field is used to provide a keyboard shortcut on the menus.
1386 (For example, pressing
1387 \begin_inset Flex MenuItem
1390 \begin_layout Plain Layout
1397 \begin_inset Flex MenuItem
1400 \begin_layout Plain Layout
1401 View\SpecialChar \menuseparator
1402 View (Other Formats)\SpecialChar \menuseparator
1411 \begin_layout Standard
1413 \begin_inset Flex MenuItem
1416 \begin_layout Plain Layout
1423 \begin_inset Flex MenuItem
1426 \begin_layout Plain Layout
1433 For example, you might want to use
1434 \begin_inset Flex MenuItem
1437 \begin_layout Plain Layout
1443 to view PostScript files.
1444 You can enter the command needed to start the program in the corresponding
1446 In defining this command, you can use the four variables listed in the
1448 The viewer is launched when you view an image in LyX or use the
1449 \begin_inset Flex MenuItem
1452 \begin_layout Plain Layout
1459 The editor is for example launched when you right-click on an image and
1461 \begin_inset Flex MenuItem
1464 \begin_layout Plain Layout
1470 in the appearing context menu.
1473 \begin_layout Standard
1475 \begin_inset Flex MenuItem
1478 \begin_layout Plain Layout
1484 option tells LyX that a format is suitable for document export.
1485 If this is set and if a suitable conversion route exists (see sec.
1486 \begin_inset space \thinspace{}
1490 \begin_inset CommandInset ref
1492 reference "sec:Converters"
1496 ), the format will appear in the
1497 \begin_inset Flex MenuItem
1500 \begin_layout Plain Layout
1501 File\SpecialChar \menuseparator
1508 The format will also appear in the
1509 \begin_inset Flex MenuItem
1512 \begin_layout Plain Layout
1518 menu if a viewer is specified for the format.
1519 Pure image formats, such as
1520 \begin_inset Flex Code
1523 \begin_layout Plain Layout
1529 , should not use this option.
1530 Formats that can both represent vector graphics and documents like
1531 \begin_inset Flex Code
1534 \begin_layout Plain Layout
1543 \begin_layout Standard
1545 \begin_inset Flex MenuItem
1548 \begin_layout Plain Layout
1549 Vector graphics format
1554 tells LyX that a format can contain vector graphics.
1555 This information is used to determine the target format of included graphics
1557 \begin_inset Flex MenuItem
1560 \begin_layout Plain Layout
1567 Included graphics may need to be converted to either
1568 \begin_inset Flex MenuItem
1571 \begin_layout Plain Layout
1578 \begin_inset Flex MenuItem
1581 \begin_layout Plain Layout
1588 \begin_inset Flex MenuItem
1591 \begin_layout Plain Layout
1598 \begin_inset Flex MenuItem
1601 \begin_layout Plain Layout
1607 cannot handle other image formats.
1608 If an included graphic is not already in
1609 \begin_inset Flex MenuItem
1612 \begin_layout Plain Layout
1619 \begin_inset Flex MenuItem
1622 \begin_layout Plain Layout
1629 \begin_inset Flex MenuItem
1632 \begin_layout Plain Layout
1638 format, it is converted to
1639 \begin_inset Flex MenuItem
1642 \begin_layout Plain Layout
1648 if the vector format option is set, and otherwise to
1649 \begin_inset Flex MenuItem
1652 \begin_layout Plain Layout
1661 \begin_layout Section
1665 \begin_layout Standard
1666 Since all conversions from one format to another take place in LyX's temporary
1667 directory, it is sometimes necessary to modify a file before copying it
1668 to the temporary directory in order that the conversion may be performed.
1672 \begin_layout Plain Layout
1673 For example, the file may refer to other files—images, for example—using
1674 relative file names, and these may become invalid when the file is copied
1675 to the temporary directory.
1680 This is done by a Copier: It copies a file to (or from) the temporary directory
1681 and may modify it in the process.
1684 \begin_layout Standard
1685 The definitions of the copiers may use four variables:
1688 \begin_layout Labeling
1689 \labelwidthstring 00.00.0000
1690 \begin_inset Flex Code
1693 \begin_layout Plain Layout
1699 The LyX system directory (e.
1700 \begin_inset space \thinspace{}
1704 \begin_inset space \space{}
1708 \begin_inset Flex MenuItem
1711 \begin_layout Plain Layout
1720 \begin_layout Labeling
1721 \labelwidthstring 00.00.0000
1722 \begin_inset Flex Code
1725 \begin_layout Plain Layout
1734 \begin_layout Labeling
1735 \labelwidthstring 00.00.0000
1736 \begin_inset Flex Code
1739 \begin_layout Plain Layout
1748 \begin_layout Labeling
1749 \labelwidthstring 00.00.0000
1750 \begin_inset Flex Code
1753 \begin_layout Plain Layout
1762 \begin_layout Standard
1763 The latter should be the filename as it would be used in a LaTeX's
1770 It is relevant only when exporting files suitable for such inclusion.
1773 \begin_layout Standard
1774 Copiers can be used to do almost anything with output files.
1775 For example, suppose you want generated pdf files to be copied to a special
1777 \begin_inset Flex Code
1780 \begin_layout Plain Layout
1787 Then you could write a shell script such as this one:
1790 \begin_layout Standard
1791 \begin_inset listings
1795 \begin_layout Plain Layout
1800 \begin_layout Plain Layout
1805 \begin_layout Plain Layout
1807 TOFILE=`basename $2`
1810 \begin_layout Plain Layout
1812 cp $FROMFILE /home/you/pdf/$TOFILE
1817 Save it in your local LyX directory—say,
1818 \begin_inset Flex Code
1821 \begin_layout Plain Layout
1822 /home/you/.lyx/scripts/pdfcopier.sh
1827 —and make it executable, if you need to do so on your platform.
1829 \begin_inset Flex MenuItem
1832 \begin_layout Plain Layout
1833 Tools\SpecialChar \menuseparator
1839 dialog, select under
1840 \begin_inset Flex MenuItem
1843 \begin_layout Plain Layout
1844 File Handling\SpecialChar \menuseparator
1851 \begin_inset Flex MenuItem
1854 \begin_layout Plain Layout
1860 format—or one of the other pdf formats—and enter
1861 \begin_inset Flex Code
1864 \begin_layout Plain Layout
1865 pdfcopier.sh $$i $$o
1871 \begin_inset Flex MenuItem
1874 \begin_layout Plain Layout
1884 \begin_layout Standard
1885 Copiers are used by LyX in various of its own conversions.
1886 For example, if appropriate programs are found, LyX will automatically
1887 install copiers for the
1888 \begin_inset Flex MenuItem
1891 \begin_layout Plain Layout
1898 \begin_inset Flex MenuItem
1901 \begin_layout Plain Layout
1903 \begin_inset space ~
1912 When these formats are exported, the copier sees that not just the main
1913 HTML file but various associated files (style files, images, etc.) are also
1915 All these files are written to a subdirectory of the directory in which
1916 the original LyX file was found.
1920 \begin_layout Plain Layout
1921 This copier can be customized.
1923 \begin_inset Quotes eld
1927 \begin_inset Quotes erd
1930 argument takes a comma-separated list of extensions to be copied; if it
1931 is omitted, all files will be copied.
1933 \begin_inset Quotes eld
1937 \begin_inset Quotes erd
1940 argument determines the extension added to the generated directory.
1942 \begin_inset Quotes eld
1946 \begin_inset Flex MenuItem
1949 \begin_layout Plain Layout
1956 \begin_inset Quotes erd
1959 , so HTML generated from
1960 \begin_inset Flex MenuItem
1963 \begin_layout Plain Layout
1964 /path/to/filename.lyx
1970 \begin_inset Flex MenuItem
1973 \begin_layout Plain Layout
1974 /path/to/filename.html.LyXconv
1988 \begin_layout Section
1990 \begin_inset CommandInset label
1992 name "sec:Converters"
1999 \begin_layout Standard
2000 You can define your own Converters to convert files between different formats.
2002 \begin_inset Flex MenuItem
2005 \begin_layout Plain Layout
2006 Tools\SpecialChar \menuseparator
2007 Preferences\SpecialChar \menuseparator
2008 File Handling\SpecialChar \menuseparator
2017 \begin_layout Standard
2018 To define a new converter, select the
2019 \begin_inset Flex MenuItem
2022 \begin_layout Plain Layout
2024 \begin_inset space ~
2033 \begin_inset Flex MenuItem
2036 \begin_layout Plain Layout
2038 \begin_inset space ~
2046 from the drop-down lists, enter the command needed for the conversion,
2048 \begin_inset Flex MenuItem
2051 \begin_layout Plain Layout
2058 Several variables can be used in the definition of converters:
2061 \begin_layout Labeling
2062 \labelwidthstring 00.00.0000
2063 \begin_inset Flex Code
2066 \begin_layout Plain Layout
2072 The LyX system directory
2075 \begin_layout Labeling
2076 \labelwidthstring 00.00.0000
2077 \begin_inset Flex Code
2080 \begin_layout Plain Layout
2089 \begin_layout Labeling
2090 \labelwidthstring 00.00.0000
2091 \begin_inset Flex Code
2094 \begin_layout Plain Layout
2103 \begin_layout Labeling
2104 \labelwidthstring 00.00.0000
2105 \begin_inset Flex Code
2108 \begin_layout Plain Layout
2114 The base filename of the input file (i.
2115 \begin_inset space \thinspace{}
2118 g., without the extension)
2121 \begin_layout Labeling
2122 \labelwidthstring 00.00.0000
2123 \begin_inset Flex Code
2126 \begin_layout Plain Layout
2132 The path to the input file
2135 \begin_layout Labeling
2136 \labelwidthstring 00.00.0000
2137 \begin_inset Flex Code
2140 \begin_layout Plain Layout
2146 The path to the original input file (this is different from $$p when a
2147 chain of converters is called)
2150 \begin_layout Labeling
2151 \labelwidthstring 00.00.0000
2152 \begin_inset Flex Code
2155 \begin_layout Plain Layout
2161 The iconv name for the encoding of the document.
2164 \begin_layout Standard
2166 \begin_inset Flex MenuItem
2169 \begin_layout Plain Layout
2171 \begin_inset space ~
2179 field you can enter the following flags, separated by commas:
2182 \begin_layout Labeling
2183 \labelwidthstring 00.00.0000
2184 \begin_inset Flex Code
2187 \begin_layout Plain Layout
2193 This converter runs some form of LaTeX.
2194 This will make LyX's LaTeX error logs available.
2197 \begin_layout Labeling
2198 \labelwidthstring 00.00.0000
2199 \begin_inset Flex Code
2202 \begin_layout Plain Layout
2209 \begin_inset Flex MenuItem
2212 \begin_layout Plain Layout
2218 file for the conversion.
2221 \begin_layout Labeling
2222 \labelwidthstring 00.00.0000
2223 \begin_inset Flex Code
2226 \begin_layout Plain Layout
2235 \begin_layout Standard
2236 The following three flags are not really flags at all because they take
2238 \begin_inset Flex MenuItem
2241 \begin_layout Plain Layout
2243 \begin_inset space ~
2247 \begin_inset space ~
2258 \begin_layout Labeling
2259 \labelwidthstring 00.00.0000
2260 \begin_inset Flex Code
2263 \begin_layout Plain Layout
2269 If set, the converter's standard error will be redirected to a file
2270 \begin_inset Flex Code
2273 \begin_layout Plain Layout
2279 , and the script given as argument will be run as:
2280 \begin_inset Flex Code
2283 \begin_layout Plain Layout
2284 script < infile.out > infile.log
2290 The argument may contain
2291 \begin_inset Flex Code
2294 \begin_layout Plain Layout
2303 \begin_layout Labeling
2304 \labelwidthstring 00.00.0000
2305 \begin_inset Flex Code
2308 \begin_layout Plain Layout
2314 The name of the directory in which the converter will dump the generated
2316 LyX will not create this directory, and it does not copy anything into
2317 it, though it will copy this directory to the destination.
2318 The argument may contain
2319 \begin_inset Flex Code
2322 \begin_layout Plain Layout
2328 , which will be replaced by the base name of the input and output files,
2329 respectively, when the directory is copied.
2330 \begin_inset Newline newline
2333 Note that resultdir and usetempdir make no sense together.
2334 The latter will be ignored if the former is given.
2337 \begin_layout Labeling
2338 \labelwidthstring 00.00.0000
2339 \begin_inset Flex Code
2342 \begin_layout Plain Layout
2348 Determines the output file name and may, contain
2349 \begin_inset Flex Code
2352 \begin_layout Plain Layout
2359 Sensible only with resultdir and optional even then; if not given, it defaults
2363 \begin_layout Standard
2364 None of these last three are presently used in any of the converters that
2365 are installed with LyX.
2369 \begin_layout Standard
2370 You do not have to define converters for all formats between which you want
2372 For example, you will note that there is no `LyX to PostScript' converter,
2373 but LyX will export PostScript.
2374 It does so by first creating a LaTeX file (no converter needs to be defined
2375 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2376 and finally converting the resulting DVI file to PostScript.
2377 LyX finds such `chains' of converters automatically, and it will always
2378 choose the shortest possible chain.
2379 You can, though, still define multiple conversion methods between file
2381 For example, the standard LyX configuration provides three ways to convert
2382 LaTeX to PDF: Directly, using
2383 \begin_inset Flex MenuItem
2386 \begin_layout Plain Layout
2392 ; via (DVI and) PostScript, using
2393 \begin_inset Flex MenuItem
2396 \begin_layout Plain Layout
2403 \begin_inset Flex MenuItem
2406 \begin_layout Plain Layout
2413 To define such alternate chains, you must define multiple target `file
2414 formats', as described in section
2415 \begin_inset CommandInset ref
2417 reference "sec:Formats"
2422 For example, in the standard configuration, the formats named
2423 \begin_inset Flex MenuItem
2426 \begin_layout Plain Layout
2433 \begin_inset Flex MenuItem
2436 \begin_layout Plain Layout
2443 \begin_inset Flex MenuItem
2446 \begin_layout Plain Layout
2452 are defined, all of which share the extension
2453 \begin_inset Flex MenuItem
2456 \begin_layout Plain Layout
2462 , and which correspond to the conversion methods just mentioned.
2465 \begin_layout Chapter
2466 Internationalizing LyX
2467 \begin_inset CommandInset label
2469 name "cha:Internationalizing-LyX"
2476 \begin_layout Standard
2477 LyX supports using a translated interface.
2478 Last time we checked, LyX provided text in thirty languages.
2479 The language of choice is called your
2484 (For further reading on locale settings, see also the documentation for
2485 locale that comes with your operating system.
2486 For Linux, the manual page for
2487 \begin_inset Flex Code
2490 \begin_layout Plain Layout
2496 could be a good place to start).
2499 \begin_layout Standard
2500 Notice that these translations will work, but do contain a few flaws.
2501 In particular, all dialogs have been designed with the English text in
2502 mind, which means that some of the translated text will be too large to
2503 fit within the space allocated.
2504 This is only a display problem and will not cause any harm.
2505 Also, you will find that some of the translations do not define shortcut
2506 keys for everything.
2507 Sometimes, there are simply not enough free letters to do it.
2508 Other times, the translator just hasn't got around to doing it yet.
2509 Our localization team, which you may wish to join,
2513 \begin_layout Plain Layout
2514 If you are a fluent speaker of a language other than English, joining these
2515 teams is a great way to give back to the LyX community!
2520 will of course try to fix these shortcomings in future versions of LyX.
2523 \begin_layout Section
2527 \begin_layout Subsection
2528 Translating the graphical user interface (text messages).
2531 \begin_layout Standard
2533 \begin_inset Flex Code
2536 \begin_layout Plain Layout
2542 library to handle the internationalization of the interface.
2543 To have LyX speak your favorite language in all menus and dialogs, you
2545 \begin_inset Flex Code
2548 \begin_layout Plain Layout
2554 -file for that language.
2555 When this is available, you'll have to generate a
2556 \begin_inset Flex Code
2559 \begin_layout Plain Layout
2565 -file from it and install the
2566 \begin_inset Flex Code
2569 \begin_layout Plain Layout
2576 The process of doing all of this is explained in the documentation for
2578 \begin_inset Flex Code
2581 \begin_layout Plain Layout
2588 It is possible to do this just for yourself, but if you're going to do
2589 it, you might as well share the results of your labors with the rest of
2591 Send a message to the LyX developers' list for more information about how
2595 \begin_layout Standard
2596 In short, this is what you should do (xx denotes the language code):
2599 \begin_layout Itemize
2600 Check out the LyX source code.
2602 \begin_inset CommandInset href
2604 name "information on the web"
2605 target "http://www.lyx.org/HowToUseSVN"
2612 \begin_layout Itemize
2614 \begin_inset Flex Code
2617 \begin_layout Plain Layout
2623 to the folder of the
2624 \begin_inset Flex Code
2627 \begin_layout Plain Layout
2635 \begin_inset Flex Code
2638 \begin_layout Plain Layout
2646 \begin_inset Flex Code
2649 \begin_layout Plain Layout
2655 doesn't exist anywhere, it can be remade with the console command
2656 \begin_inset Flex Code
2659 \begin_layout Plain Layout
2665 in that directory, or you can use an existing po-file for some other language
2669 \begin_layout Itemize
2671 \begin_inset Flex Code
2674 \begin_layout Plain Layout
2684 \begin_layout Plain Layout
2685 This is just a text file, so it can be edited in any text editor.
2686 But there are also specialized programs that support such editing, such
2691 (for all platforms) or
2700 contains a `mode' for editing
2701 \begin_inset Flex Code
2704 \begin_layout Plain Layout
2715 For some menu- and widget-labels, there are also shortcut keys that should
2717 Those keys are marked after a `|', and should be translated according to
2718 the words and phrases of the language.
2719 You should also fill also out the information at the beginning of the new
2721 \begin_inset Flex Code
2724 \begin_layout Plain Layout
2730 -file with your email-address, etc., so people know where to reach you with
2731 suggestions and entertaining flames.
2734 \begin_layout Standard
2735 If you are just doing this on your own, then:
2738 \begin_layout Itemize
2740 \begin_inset Flex Code
2743 \begin_layout Plain Layout
2750 This can be done with
2751 \begin_inset Flex Code
2754 \begin_layout Plain Layout
2755 msgfmt -o xx.mo < xx.po
2763 \begin_layout Itemize
2765 \begin_inset Flex Code
2768 \begin_layout Plain Layout
2774 -file to your locale-tree, at the correct directory for application messages
2779 xx, and under the name
2780 \begin_inset Flex Code
2783 \begin_layout Plain Layout
2790 \begin_inset space \thinspace{}
2794 \begin_inset space \space{}
2798 \begin_inset Flex Code
2801 \begin_layout Plain Layout
2802 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2812 \begin_layout Standard
2813 As said, however, it would be best if the new
2814 \begin_inset Flex Code
2817 \begin_layout Plain Layout
2823 -file could be added to the LyX distribution, so others can use it.
2824 Adding it involves making additional changes to LyX.
2825 So send an email to the developers' mailing list if you're interested in
2829 \begin_layout Subsubsection
2833 \begin_layout Standard
2834 Sometimes it turns out that one English message needs to be translated into
2835 different messages in the target language.
2836 One example is the message
2837 \begin_inset Flex Code
2840 \begin_layout Plain Layout
2846 which has the German translation
2854 , depending upon exactly what the English
2855 \begin_inset Quotes eld
2859 \begin_inset Quotes erd
2864 \begin_inset Flex Code
2867 \begin_layout Plain Layout
2873 does not handle such ambiguous translations.
2874 Therefore you have to add some context information to the message: Instead
2876 \begin_inset Flex Code
2879 \begin_layout Plain Layout
2886 \begin_inset Flex Code
2889 \begin_layout Plain Layout
2890 To[[as in 'From format x to format y']]
2896 \begin_inset Flex Code
2899 \begin_layout Plain Layout
2900 To[[as in 'From page x to page y']].
2905 Now the two occurrences of
2906 \begin_inset Flex Code
2909 \begin_layout Plain Layout
2916 \begin_inset Flex Code
2919 \begin_layout Plain Layout
2925 and can be translated correctly to
2936 \begin_layout Standard
2937 Of course the context information needs to be stripped off the original
2938 message when no translation is used.
2939 Therefore you have to put it in double square brackets at the end of the
2940 message (see the example above).
2941 The translation mechanism of LyX ensures that everything in double square
2942 brackets at the end of messages is removed before displaying the message.
2945 \begin_layout Subsection
2946 Translating the documentation.
2949 \begin_layout Standard
2950 The online documentation (in the
2951 \begin_inset Flex MenuItem
2954 \begin_layout Plain Layout
2960 -menu) can (and should!) be translated.
2961 If there are translated versions of the documentation available
2965 \begin_layout Plain Layout
2966 As of March 2008, at least some of the documents have been translated into
2967 fourteen languages, with the Tutorial available in a few more.
2972 and the locale is set accordingly, these will be used automagically by
2974 LyX looks for translated versions as
2975 \begin_inset Flex Code
2978 \begin_layout Plain Layout
2979 LyXDir/doc/xx/DocName.lyx
2985 \begin_inset Flex Code
2988 \begin_layout Plain Layout
2994 is the code for the language currently in use.
2995 If there are no translated documents, the default English versions will
2997 Note that the translated versions must have the same filenames (
2998 \begin_inset Flex Code
3001 \begin_layout Plain Layout
3007 above) as the original.
3008 If you feel up to translating the documentation (an excellent way to proof-read
3009 the original documentation by the way!), there are a few things you should
3013 \begin_layout Itemize
3014 Check out the documentation translation web page at
3015 \begin_inset CommandInset href
3017 name "http://www.lyx.org/Translation"
3018 target "http://www.lyx.org/Translation"
3023 That way, you can find out which (if any) documents have already been translate
3024 d into your language.
3025 You can also find out who (if anyone) is organizing the effort to translate
3026 the documentation into your language.
3027 If no one is organizing the effort, please let us know that you're interested.
3030 \begin_layout Standard
3031 Once you get to actually translating, here's a few hints for you that may
3035 \begin_layout Itemize
3036 Join the documentation team! There is information on how to do that in
3037 \begin_inset Flex Code
3040 \begin_layout Plain Layout
3047 \begin_inset Flex MenuItem
3050 \begin_layout Plain Layout
3051 Help\SpecialChar \menuseparator
3057 ), which by the way is the first document you should translate.
3060 \begin_layout Itemize
3061 Learn the typographic conventions for the language you are translating to.
3062 Typography is an ancient art and over the centuries, a great variety of
3063 conventions have developed throughout different parts of the world.
3064 Also study the professional terminology amongst typographers in your country.
3065 Inventing your own terminology will only confuse the users.
3068 (Warning! Typography is addictive!)
3071 \begin_layout Itemize
3072 Make a copy of the document.
3073 This will be your working copy.
3074 You can use this as your personal translated help-file by placing it in
3076 \begin_inset Flex Code
3079 \begin_layout Plain Layout
3088 \begin_layout Itemize
3089 Sometimes the original document (from the LyX-team) will be updated.
3090 Use the source viewer at
3091 \begin_inset CommandInset href
3093 name "http://www.lyx.org/trac/timeline"
3094 target "http://www.lyx.org/trac/timeline"
3098 to see what has been changed.
3099 That way you can easily see which parts of the translated document need
3103 \begin_layout Standard
3104 If you ever find an error in the original document, fix it and notify the
3105 rest of the documentation team of the changes! (You didn't forget to join
3106 the documentation team, did you?)
3109 \begin_layout Standard
3110 \begin_inset Branch OutDated
3113 \begin_layout Section
3114 International Keyboard Support
3117 \begin_layout Standard
3120 [Editor's Note: The following section is by
3128 It needs to be fixed to conform to the new Documentation Style sheet and
3129 to make use of the new v1.0 features.
3130 The whole thing also needs to be merged with the section following it.-jw
3131 It may also be badly out of date.-rh (2008)]
3134 \begin_layout Subsection
3135 Defining Own Keymaps: Keymap File Format
3138 \begin_layout Standard
3139 Let's look at a keyboard definition file a little closer.
3140 It is a plain text file defining
3143 \begin_layout Itemize
3144 key-to-key or key-to-string translations
3147 \begin_layout Itemize
3151 \begin_layout Itemize
3152 dead keys exceptions
3155 \begin_layout Standard
3156 To define key-to-key or key-to-string translation, use this command:
3159 \begin_layout Quotation
3160 \begin_inset Flex Code
3163 \begin_layout Plain Layout
3172 \begin_inset Flex Code
3175 \begin_layout Plain Layout
3184 \begin_layout Standard
3186 \begin_inset Flex Code
3189 \begin_layout Plain Layout
3195 is the key to be translated and
3196 \begin_inset Flex Code
3199 \begin_layout Plain Layout
3205 is the string to be inserted into the document.
3206 To define dead keys, use:
3209 \begin_layout Quotation
3210 \begin_inset Flex Code
3213 \begin_layout Plain Layout
3222 \begin_inset Flex Code
3225 \begin_layout Plain Layout
3234 \begin_layout Standard
3236 \begin_inset Flex Code
3239 \begin_layout Plain Layout
3245 is a keyboard key and
3246 \begin_inset Flex Code
3249 \begin_layout Plain Layout
3256 The following dead keys are supported (shortcut name is in parentheses):
3259 \begin_layout Quotation
3263 \begin_inset space \hfill{}
3269 \begin_layout Quotation
3271 \begin_inset space \hfill{}
3277 \begin_layout Quotation
3279 \begin_inset space \hfill{}
3285 \begin_layout Quotation
3287 \begin_inset space \hfill{}
3293 \begin_layout Quotation
3295 \begin_inset space \hfill{}
3301 \begin_layout Quotation
3303 \begin_inset space \hfill{}
3310 \begin_layout Plain Layout
3322 \begin_layout Quotation
3324 \begin_inset space \hfill{}
3330 \begin_layout Quotation
3332 \begin_inset space \hfill{}
3339 \begin_layout Plain Layout
3351 \begin_layout Quotation
3353 \begin_inset space \hfill{}
3359 \begin_layout Quotation
3361 \begin_inset space \hfill{}
3367 \begin_layout Quotation
3369 \begin_inset space \hfill{}
3376 \begin_layout Plain Layout
3388 \begin_layout Quotation
3390 \begin_inset space \hfill{}
3397 \begin_layout Plain Layout
3409 \begin_layout Quotation
3411 \begin_inset space \hfill{}
3417 \begin_layout Quotation
3418 hungarian umlaut (hug)
3419 \begin_inset space \hfill{}
3425 \begin_layout Quotation
3427 \begin_inset space \hfill{}
3433 \begin_layout Quotation
3435 \begin_inset space \hfill{}
3442 \begin_layout Plain Layout
3454 \begin_layout Standard
3455 Since in many international keyboards there are exceptions to what some
3456 dead keys should do, you can define them using
3459 \begin_layout Quotation
3460 \begin_inset Flex Code
3463 \begin_layout Plain Layout
3471 deadkey key outstring
3474 \begin_layout Standard
3475 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3479 \begin_layout Quotation
3480 \begin_inset Flex Code
3483 \begin_layout Plain Layout
3496 \begin_layout Standard
3497 to make it work correctly.
3498 Also, you have to define as exceptions dead keys over i and j, to remove
3499 the dot from them before inserting an accent mark.
3500 I will change this when the time comes, but so far I haven't had time.
3503 \begin_layout Standard
3504 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3507 \begin_inset Flex Code
3510 \begin_layout Plain Layout
3516 have different meaning.
3518 \begin_inset Flex Code
3521 \begin_layout Plain Layout
3527 marks comments, quotes start and end LaTeX-style commands.
3528 To enter quote, you'll need to use
3529 \begin_inset Flex Code
3532 \begin_layout Plain Layout
3541 \begin_inset Flex Code
3544 \begin_layout Plain Layout
3551 \begin_inset Flex Code
3554 \begin_layout Plain Layout
3565 \begin_layout Standard
3566 If you make a keyboard description file that works for your language, please
3567 mail it to me, so I can include it in the next keymap distribution.
3570 \begin_layout Standard
3571 More keywords will be supported in keymap configuration file in future,
3575 \begin_layout Itemize
3576 \begin_inset Flex Code
3579 \begin_layout Plain Layout
3590 \begin_inset space \hfill{}
3594 \begin_inset Flex Code
3597 \begin_layout Plain Layout
3606 \begin_layout Itemize
3607 \begin_inset Flex Code
3610 \begin_layout Plain Layout
3621 \begin_inset space \hfill{}
3625 \begin_inset Flex Code
3628 \begin_layout Plain Layout
3634 an external keymap translation program
3637 \begin_layout Standard
3638 Also, it should look into
3639 \begin_inset Flex Code
3642 \begin_layout Plain Layout
3648 file for defaults, too (for example, a
3649 \begin_inset Flex Code
3652 \begin_layout Plain Layout
3660 option to include default keyboard).
3668 \begin_layout Section
3669 International Keymap Stuff
3670 \begin_inset CommandInset label
3672 name "sec:International-Keymap-Stuff"
3679 \begin_layout Standard
3680 \begin_inset Note Note
3683 \begin_layout Plain Layout
3684 In doing the revisions on this document in March 2008, I did not look over
3685 this stuff, as I do not understand it.
3686 It would be good if someone else could do so.
3695 \begin_layout Standard
3696 The next two sections describe the
3697 \begin_inset Flex Code
3700 \begin_layout Plain Layout
3709 \begin_inset Flex Code
3712 \begin_layout Plain Layout
3720 file syntax in detail.
3721 These sections should help you design your own key map if the ones provided
3722 do not meet your needs.
3725 \begin_layout Subsection
3729 \begin_layout Standard
3733 \begin_inset Flex Code
3736 \begin_layout Plain Layout
3742 file maps keystrokes to characters or strings.
3743 As the name suggests, it sets a keyboard mapping.
3745 \begin_inset Flex Code
3748 \begin_layout Plain Layout
3759 \begin_inset Flex Code
3762 \begin_layout Plain Layout
3777 \begin_inset Flex Code
3780 \begin_layout Plain Layout
3793 \begin_inset Flex Code
3796 \begin_layout Plain Layout
3805 \begin_inset Flex Code
3808 \begin_layout Plain Layout
3816 are described in this section.
3819 \begin_layout Labeling
3820 \labelwidthstring 00.00.0000
3821 \begin_inset Flex Code
3824 \begin_layout Plain Layout
3832 Map a character to a string
3835 \begin_layout LyX-Code
3850 \begin_layout Standard
3883 the double-quote (")
3900 must be escaped with a preceding backslash (
3911 \begin_layout Standard
3913 \begin_inset Flex MenuItem
3916 \begin_layout Plain Layout
3924 statement to cause the symbol
3925 \begin_inset Flex MenuItem
3928 \begin_layout Plain Layout
3936 to be output for the keystroke
3937 \begin_inset Flex MenuItem
3940 \begin_layout Plain Layout
3951 \begin_layout LyX-Code
3957 \begin_layout Labeling
3958 \labelwidthstring 00.00.0000
3959 \begin_inset Flex Code
3962 \begin_layout Plain Layout
3970 Specify an accent character
3973 \begin_layout LyX-Code
3982 \begin_layout Standard
3983 This will make the cha
4021 This is the dead key
4025 \begin_layout Plain Layout
4032 refers to a key that does not produce a character by itself, but when followed
4033 with another key, produces the desired accent character.
4034 For example, a German characte
4036 r with an umlaut like
4046 can be produced in this manner.
4055 \begin_layout Standard
4068 and then another key not in
4085 followed by the other, not allowed key, as output.
4089 \begin_inset Flex MenuItem
4092 \begin_layout Plain Layout
4100 cancels a dead key, so if
4111 \begin_inset Flex MenuItem
4114 \begin_layout Plain Layout
4123 , the cursor will not go one position backwards but will instead cancel
4139 might have had on the next keystroke.
4143 \begin_layout Standard
4144 The following example specifies that the character ' is to be an acute accent,
4145 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4148 \begin_layout LyX-Code
4151 kmod ' acute aeiouAEIOU
4154 \begin_layout Labeling
4155 \labelwidthstring 00.00.0000
4156 \begin_inset Flex Code
4159 \begin_layout Plain Layout
4165 Specify an exception to the accent character
4168 \begin_layout LyX-Code
4177 \begin_layout Standard
4178 This defines an exce
4219 have been assigned a keystroke with a previous
4222 \begin_inset Flex Code
4225 \begin_layout Plain Layout
4249 must not belong in the
4296 If such a declaration does not exist in
4304 \begin_inset Flex Code
4307 \begin_layout Plain Layout
4341 \begin_inset Flex Code
4344 \begin_layout Plain Layout
4358 \begin_layout Standard
4359 The following command produces causes äi to be produced when you enter acute-i
4363 \begin_layout LyX-Code
4377 \begin_layout Labeling
4378 \labelwidthstring 00.00.0000
4379 \begin_inset Flex Code
4382 \begin_layout Plain Layout
4388 Combine two accent characters
4391 \begin_layout LyX-Code
4397 accent1 accent2 allowed
4400 \begin_layout Standard
4401 This one is getting pretty esoteric.
4402 It allows you to combine the effect
4458 \begin_inset Flex Code
4461 \begin_layout Plain Layout
4489 \begin_layout Standard
4490 Consider this example from the
4491 \begin_inset Flex Code
4494 \begin_layout Plain Layout
4505 \begin_layout LyX-Code
4508 kmod ; acute aeioyvhAEIOYVH
4512 kcomb acute umlaut iyIY
4515 \begin_layout Standard
4516 This allows you to press
4517 \begin_inset Flex MenuItem
4520 \begin_layout Plain Layout
4528 and get the effect of
4529 \begin_inset Flex Code
4532 \begin_layout Plain Layout
4551 in this case cancels the last dead key, so if you press
4552 \begin_inset Flex MenuItem
4555 \begin_layout Plain Layout
4564 \begin_inset Flex Code
4567 \begin_layout Plain Layout
4580 \begin_layout Subsection
4584 \begin_layout Standard
4586 \begin_inset Flex Code
4589 \begin_layout Plain Layout
4597 mapping is performed, a
4598 \begin_inset Flex Code
4601 \begin_layout Plain Layout
4611 file maps the strings that the symbols generate to characters in the current
4613 The LyX distribution currently includes at least the
4614 \begin_inset Flex Code
4617 \begin_layout Plain Layout
4626 \begin_inset Flex Code
4629 \begin_layout Plain Layout
4640 \begin_layout Standard
4642 \begin_inset Flex Code
4645 \begin_layout Plain Layout
4653 file is a sequence of declarations of the form
4656 \begin_layout LyX-Code
4669 \begin_layout Standard
4670 For example, in order to map
4671 \begin_inset Flex MenuItem
4674 \begin_layout Plain Layout
4684 to the corresponding character in the iso-8859-1 set (233), the following
4688 \begin_layout LyX-Code
4696 \begin_layout Standard
4698 \begin_inset Flex Code
4701 \begin_layout Plain Layout
4710 \begin_inset Flex Code
4713 \begin_layout Plain Layout
4731 the same character can apply to more than one string.
4733 \begin_inset Flex Code
4736 \begin_layout Plain Layout
4747 \begin_layout LyX-Code
4759 \begin_inset Newline newline
4775 \begin_layout Standard
4776 If LyX cannot find a mapping for the string produced by the keystroke or
4777 a deadkey sequence, it will check if it looks like an accented char and
4778 try to draw an accent over the character on screen.
4781 \begin_layout Subsection
4785 \begin_layout Standard
4786 There is a second way to add support for international characters through
4787 so-called dead-keys.
4788 A dead-key works in combination with a letter to produce an accented character.
4789 Here, we'll explain how to create a really simple dead-key to illustrate
4793 \begin_layout Standard
4794 Suppose you happen to need the circumflex character,
4795 \begin_inset Quotes eld
4799 \begin_inset Quotes erd
4804 \begin_inset Flex MenuItem
4807 \begin_layout Plain Layout
4814 \begin_inset space ~
4818 \begin_inset Flex MenuItem
4821 \begin_layout Plain Layout
4827 ] to the LyX command
4828 \begin_inset Flex Code
4831 \begin_layout Plain Layout
4838 \begin_inset Flex Code
4841 \begin_layout Plain Layout
4848 Now, whenever you type the
4849 \begin_inset Flex MenuItem
4852 \begin_layout Plain Layout
4858 -key followed by a letter, that letter will have a circumflex accent on
4860 For example, the sequence
4861 \begin_inset Quotes eld
4865 \begin_inset Flex MenuItem
4868 \begin_layout Plain Layout
4875 \begin_inset Quotes erd
4878 produces the letter:
4879 \begin_inset Quotes eld
4883 \begin_inset Quotes erd
4887 If you tried to type
4888 \begin_inset Quotes eld
4892 \begin_inset Flex MenuItem
4895 \begin_layout Plain Layout
4902 \begin_inset Quotes erd
4905 , however, LyX will complain with a beep, since a
4906 \begin_inset Quotes eld
4910 \begin_inset Flex MenuItem
4913 \begin_layout Plain Layout
4920 \begin_inset Quotes erd
4923 never takes a circumflex accent.
4925 \begin_inset Flex MenuItem
4928 \begin_layout Plain Layout
4934 after a dead-key produces the bare-accent.
4935 Please note this last point! If you bind a key to a dead-key, you'll need
4936 to rebind the character on that key to yet another key.
4938 \begin_inset Flex MenuItem
4941 \begin_layout Plain Layout
4947 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
4950 \begin_layout Standard
4951 One common way to bind dead-keys is to use
4952 \begin_inset Flex MenuItem
4955 \begin_layout Plain Layout
4962 \begin_inset Flex MenuItem
4965 \begin_layout Plain Layout
4972 \begin_inset Flex MenuItem
4975 \begin_layout Plain Layout
4981 in combination with an accent, like
4982 \begin_inset Quotes eld
4986 \begin_inset Flex MenuItem
4989 \begin_layout Plain Layout
4996 \begin_inset Quotes erd
5000 \begin_inset Quotes eld
5004 \begin_inset Flex MenuItem
5007 \begin_layout Plain Layout
5014 \begin_inset Quotes erd
5018 \begin_inset Quotes eld
5022 \begin_inset Flex MenuItem
5025 \begin_layout Plain Layout
5032 \begin_inset Quotes erd
5036 Another way involves using
5037 \begin_inset Flex Code
5040 \begin_layout Plain Layout
5047 \begin_inset Flex Code
5050 \begin_layout Plain Layout
5056 to set up the special
5057 \begin_inset Flex Code
5060 \begin_layout Plain Layout
5068 \begin_inset Flex Code
5071 \begin_layout Plain Layout
5077 acts in some ways just like
5078 \begin_inset Flex MenuItem
5081 \begin_layout Plain Layout
5087 and permits you to bind keys to accented characters.
5088 You can also turn keys into dead-keys by binding them to something like
5090 \begin_inset Flex Code
5093 \begin_layout Plain Layout
5099 and then binding this symbolic key to the corresponding LyX command.
5103 \begin_layout Plain Layout
5108 : This is exactly what I do in my
5109 \begin_inset Flex Code
5112 \begin_layout Plain Layout
5119 \begin_inset Flex Code
5122 \begin_layout Plain Layout
5130 \begin_inset Flex MenuItem
5133 \begin_layout Plain Layout
5135 \begin_inset space ~
5144 \begin_inset Flex Code
5147 \begin_layout Plain Layout
5153 and a bunch of these
5154 \begin_inset Quotes eld
5158 \begin_inset Flex Code
5161 \begin_layout Plain Layout
5168 \begin_inset Quotes erd
5171 symbolic keys bound such things as
5172 \begin_inset Flex MenuItem
5175 \begin_layout Plain Layout
5177 \begin_inset space ~
5186 \begin_inset Flex MenuItem
5189 \begin_layout Plain Layout
5191 \begin_inset space ~
5200 This is how I produce my accented characters.
5205 You can make just about anything into the
5206 \begin_inset Flex Code
5209 \begin_layout Plain Layout
5216 \begin_inset Flex MenuItem
5219 \begin_layout Plain Layout
5225 keys, a spare function key, etc.
5226 As for the LyX commands that produce accents, check the entry for
5227 \begin_inset Flex Code
5230 \begin_layout Plain Layout
5241 You'll find the complete list there.
5244 \begin_layout Subsection
5245 Saving your Language Configuration
5248 \begin_layout Standard
5249 You can edit your preferences so that your desired language environment
5250 is automatically configured when LyX starts up, via the
5251 \begin_inset Flex MenuItem
5254 \begin_layout Plain Layout
5255 Edit\SpecialChar \menuseparator
5264 \begin_layout Chapter
5265 Installing New Document Classes, Layouts, and Templates
5266 \begin_inset CommandInset label
5268 name "cha:Installing-New-Document"
5273 \begin_inset Argument
5276 \begin_layout Plain Layout
5277 Installing New Document Classes
5285 \begin_layout Standard
5286 In this chapter, we describe the procedures for creating and installing
5287 new LyX layout and template files, as well as offer a refresher on correctly
5288 installing new LaTeX document classes.
5292 \begin_layout Standard
5293 First, let us a say a few words about how one ought to think about the relation
5294 between LyX and LaTeX.
5295 The thing to understand is that, in a certain sense, LyX doesn't know anything
5297 Indeed, from LyX's point of view, LaTeX is just one of several
5298 \begin_inset Quotes eld
5302 \begin_inset Quotes erd
5305 in which it is capable of producing output.
5306 Other such formats are DocBook, plaintext, and XHTML.
5307 LaTeX is, of course, a particularly important format, but very little of
5308 the information LyX has about LaTeX is actually contained in the program
5313 \begin_layout Plain Layout
5314 Some commands are sufficiently complex that they are
5315 \begin_inset Quotes eld
5319 \begin_inset Quotes erd
5323 But the developers generally regard this as a Bad Thing.
5328 Rather, that information, even for the standard classes like
5329 \begin_inset Flex Code
5332 \begin_layout Plain Layout
5338 , is contained in `layout files'.
5339 Similarly, LyX itself does not know much about DocBook or XHTML.
5340 What it knows is contained in layout files.
5343 \begin_layout Standard
5344 You can think of the layout file for a given document class as a translation
5345 manual between LyX constructs---paragraphs with their corresponding styles,
5346 certain sorts of insets, etc---and the corresponding LaTeX, DocBook, or
5348 Almost everything LyX knows about
5349 \begin_inset Flex Code
5352 \begin_layout Plain Layout
5358 , for example, is contained in the file
5359 \begin_inset Flex Code
5362 \begin_layout Plain Layout
5368 and in various other files it includes.
5369 For this reason, anyone intending to write layout files should plan to
5370 study the existing files.
5371 A good place to start is with
5372 \begin_inset Flex Code
5375 \begin_layout Plain Layout
5381 , which is included in
5382 \begin_inset Flex Code
5385 \begin_layout Plain Layout
5392 \begin_inset Flex Code
5395 \begin_layout Plain Layout
5401 , and many of the other layout files for document classes.
5402 This file is where sections and the like are defined:
5403 \begin_inset Flex Code
5406 \begin_layout Plain Layout
5412 tells LyX how paragraphs that are marked with the Section, Subsection,
5413 etc, styles can be translated into corresponding LaTeX, DocBook, and XHTML
5416 \begin_inset Flex Code
5419 \begin_layout Plain Layout
5425 file basically just includes several of these
5426 \begin_inset Flex Code
5429 \begin_layout Plain Layout
5438 \begin_layout Standard
5439 Defining the LyX--LaTeX correspondence is not the only thing layout files
5441 Their other job is to define how the LyX constructs themselves will appear
5443 The fact that layout files have these two jobs is often a source of confusion,
5444 because they are completely separate.
5445 Telling LyX how to translate a certain paragraph style into LaTeX does
5446 not tell LyX how to display it; conversely, telling LyX how to display
5447 a certain paragraph style does not tell LyX how to translate it into LaTeX
5448 (let alone tell LaTeX how to display it).
5449 So, in general, when you define a new LyX construct, you must always do
5450 two quite separate things: (i)
5451 \begin_inset space ~
5454 tell LyX how to translate it into LaTeX and (ii)
5455 \begin_inset space ~
5458 tell LyX how to display it.
5461 \begin_layout Standard
5462 Much the same is true, of course, as regards LyX's other backend formats,
5463 though XHTML is in some ways different, because in that case LyX
5467 able, to some extent, to use information about how it should display a
5468 paragraph on the screen to output information (in the form of CSS) about
5469 how the paragraph should be displayed in a browser.
5470 Even in this case, however, the distinction between what LyX does internally
5471 and how things are rendered externally remains in force, and the two can
5472 be controlled separately.
5474 \begin_inset CommandInset ref
5476 reference "sec:Tags-for-XHTML"
5483 \begin_layout Section
5484 Installing new LaTeX files
5487 \begin_layout Standard
5488 Some installations may not include a LaTeX package or class file that you
5489 would like to use within LyX.
5490 For example, you might need FoilTeX, a package for preparing slides for
5491 overhead projectors.
5492 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5493 a user interface for installing such packages.
5494 For example, with MiKTeX, you start the program
5495 \begin_inset Quotes eld
5499 \begin_inset space ~
5503 \begin_inset Quotes erd
5506 to get a list of available packages.
5507 To install one of them, right click on it or use the corresponding toolbar
5511 \begin_layout Standard
5512 If your LaTeX distribution does not provide such a `package manager', or
5513 if the package is not available from your distribution, then follow these
5514 steps to install it manually:
5517 \begin_layout Enumerate
5518 Get the package from
5519 \begin_inset CommandInset href
5522 target "http://www.ctan.org/"
5529 \begin_layout Enumerate
5530 If the package contains a file with the ending
5531 \begin_inset Quotes eld
5535 \begin_inset Flex Code
5538 \begin_layout Plain Layout
5545 \begin_inset Quotes erd
5548 (is the case for FoilTeX) then open a console, change to the folder of
5549 this file and execute the command
5550 \begin_inset Flex Code
5553 \begin_layout Plain Layout
5560 You have now unpacked the package and have all files to install it.
5561 Most LaTeX-packages are not packed and you can skip this step.
5564 \begin_layout Enumerate
5565 Now you need to decide if the package should be available for all users
5570 \begin_layout Enumerate
5571 On *nix systems (Linux, OSX, etc.), if you want the new package to be available
5572 for all users on your system, then install it in your `local' TeX tree,
5573 otherwise install it in your own `user' TeX tree.
5574 Where these trees should be created, if they do not already exist, depends
5576 To find this out, look in the file
5577 \begin_inset Flex Code
5580 \begin_layout Plain Layout
5590 \begin_layout Plain Layout
5591 This is usually in the directory
5592 \begin_inset Flex Code
5595 \begin_layout Plain Layout
5601 , though you can execute the command
5602 \begin_inset Flex Code
5605 \begin_layout Plain Layout
5616 The location of the `local' TeX tree is defined by the
5617 \begin_inset Flex Code
5620 \begin_layout Plain Layout
5626 variable; this is usually somewhere like
5627 \begin_inset Flex Code
5630 \begin_layout Plain Layout
5631 /usr/local/share/texmf
5637 The location of the `user' TeX tree is defined by
5638 \begin_inset Flex Code
5641 \begin_layout Plain Layout
5648 \begin_inset Flex Code
5651 \begin_layout Plain Layout
5658 (If these variables are not predefined, you have to define them.) You'll
5659 probably need root permissions to create or modify the `local' tree, but
5660 not for your `user' tree.
5661 \begin_inset Newline newline
5664 In general, it is recommended to install in the user tree because your user
5665 will not be modified or even overwritten when you upgrade your system.
5666 It will typically also be backed up together with everything else when
5667 you backup your home directory (which, of course, you do on a regular basis).
5670 \begin_layout Enumerate
5671 On Windows, if you want the new package to be available for all users on
5672 your system, change to the folder where LaTeX is installed and then change
5674 \begin_inset Flex Code
5677 \begin_layout Plain Layout
5688 (For MiKTeX, this would be by default the folder
5689 \begin_inset Flex Code
5692 \begin_layout Plain Layout
5710 \begin_layout Plain Layout
5711 Note that this will be the correct path only on English installations.
5712 On a German one, it would be
5713 \begin_inset Flex Code
5716 \begin_layout Plain Layout
5730 , and similarly for other languages.
5735 Create there a new folder
5736 \begin_inset Flex Code
5739 \begin_layout Plain Layout
5745 and copy all files of the package into it.
5747 \begin_inset Newline newline
5750 If the package should only available for you or you don't have admin permissions
5751 , do the same, but in the local LaTeX folder.
5753 \begin_inset space \thinspace{}
5757 \begin_inset space ~
5760 2.8 under Windows XP, this would be the folder:
5761 \begin_inset Newline newline
5767 \begin_inset Flex Code
5770 \begin_layout Plain Layout
5773 Documents and Settings
5785 \begin_inset Newline newline
5791 \begin_inset Phantom HPhantom
5794 \begin_layout Plain Layout
5805 \begin_inset Flex Code
5808 \begin_layout Plain Layout
5821 \begin_inset Newline newline
5824 On Vista, it would be:
5825 \begin_inset Newline newline
5829 \begin_inset Flex Code
5832 \begin_layout Plain Layout
5858 \begin_layout Enumerate
5859 Now one only need to tell LaTeX that there are new files.
5860 This depends on the used LaTeX-Distribution:
5864 \begin_layout Enumerate
5865 For TeXLive execute the command
5866 \begin_inset Flex Code
5869 \begin_layout Plain Layout
5876 If you installed the package for all users, then you will probably need
5877 to have root permissions for that.
5880 \begin_layout Enumerate
5881 For MiKTeX, if you have installed the package for all users, start the program
5883 \begin_inset Quotes eld
5887 \begin_inset space ~
5891 \begin_inset Quotes erd
5894 and press the button marked
5895 \begin_inset Quotes eld
5899 \begin_inset Quotes erd
5903 Otherwise start the program
5904 \begin_inset Quotes eld
5908 \begin_inset Quotes erd
5915 \begin_layout Enumerate
5916 Finally, you need to tell LyX that there are new packages available.
5917 So, in LyX, use the menu
5918 \begin_inset Flex MenuItem
5921 \begin_layout Plain Layout
5924 \SpecialChar \menuseparator
5930 and then restart LyX.
5933 \begin_layout Standard
5934 Now the package is installed.
5935 In our example, the document class
5936 \begin_inset Flex Code
5939 \begin_layout Plain Layout
5941 \begin_inset space ~
5948 \begin_layout Plain Layout
5960 will now be available under
5961 \begin_inset Flex MenuItem
5964 \begin_layout Plain Layout
5965 Document\SpecialChar \menuseparator
5966 Settings\SpecialChar \menuseparator
5976 \begin_layout Standard
5977 If you would like to use a LaTeX document class that is not even listed
5979 \begin_inset Flex MenuItem
5982 \begin_layout Plain Layout
5983 Document\SpecialChar \menuseparator
5984 Settings\SpecialChar \menuseparator
5990 , then you need to create a `layout' file for it.
5991 That is the topic of the next section.
5994 \begin_layout Section
5995 Types of layout files
5998 \begin_layout Standard
5999 This section describes the various sorts of LyX files that contain layout
6001 These files describe various paragraph and character styles, determining
6002 how LyX should display them and how they should be translated into LaTeX,
6003 DocBook, XHTML, or whatever output format is being used.
6007 \begin_layout Standard
6008 We shall try to provide a thorough description of the process of writing
6010 However, there are so many different types of documents supported even
6011 by just LaTeX that we can't hope to cover every different possibility or
6012 problem you might encounter.
6013 The LyX users' list is frequented by people with lots of experience with
6014 layout design who are willing to share what they've learned, so please
6015 feel free to ask questions there.
6018 \begin_layout Standard
6019 As you prepare to write a new layout, it is extremely helpful to look at
6020 the layouts distributed with LyX.
6021 If you write a LyX layout for a LaTeX document class that might also be
6022 used by others, or write a module that might be useful to others, then
6023 you should consider posting your layout to the
6024 \begin_inset CommandInset href
6026 name "layout section on the LyX wiki"
6027 target "http://wiki.lyx.org/Layouts/Layouts"
6031 or even to the LyX developers' list, so that it might be included in LyX
6036 \begin_layout Plain Layout
6037 Note that LyX is licensed under the General Public License, so any material
6038 that is contributed to LyX must be similarly licensed.
6046 \begin_layout Subsection
6048 \begin_inset CommandInset label
6050 name "sub:Layout-modules"
6057 \begin_layout Standard
6058 We have spoken to this point about `layout files'.
6059 But there are different sorts of files that contain layout information.
6060 Layout files, strictly so called, have the
6061 \begin_inset Flex Code
6064 \begin_layout Plain Layout
6070 extension and provide LyX with information about document classes.
6071 As of LyX 1.6, however, layout information can also be contained in layout
6077 \begin_inset Flex Code
6080 \begin_layout Plain Layout
6087 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6088 some modules—such as the
6089 \begin_inset Flex Code
6092 \begin_layout Plain Layout
6098 module—specifically provide support for one package.
6099 In a sense, layout modules are similar to included
6103 \begin_layout Plain Layout
6104 These can have any extension, but by convention have the
6105 \begin_inset Flex Code
6108 \begin_layout Plain Layout
6120 \begin_inset Flex Code
6123 \begin_layout Plain Layout
6129 —in that modules are not specific to a given document class but may be used
6130 with many different classes.
6131 The difference is that using an included file with
6132 \begin_inset Flex Code
6135 \begin_layout Plain Layout
6141 requires editing that file.
6142 Modules, by contrast, are selected in the
6143 \begin_inset Flex MenuItem
6146 \begin_layout Plain Layout
6147 Document\SpecialChar \menuseparator
6156 \begin_layout Standard
6157 Building modules is the easiest way to get started with layout editing,
6158 since it can be as simple as adding a single new paragraph style or flex
6160 But modules may, in principle, contain anything a layout file can contain.
6163 \begin_layout Standard
6164 After creating a new module and copying it to the
6165 \begin_inset Flex Code
6168 \begin_layout Plain Layout
6174 folder, you will need to reconfigure and then restart LyX for the module
6175 to appear in the menu.
6176 However, changes you make to the module will be seen immediately, if you
6178 \begin_inset Flex MenuItem
6181 \begin_layout Plain Layout
6182 Document\SpecialChar \menuseparator
6188 , highlight something, and then hit
6189 \begin_inset Quotes eld
6193 \begin_inset Quotes erd
6199 It is strongly recommended that you save your work before doing this
6204 it is strongly recommended that you not attempt to edit modules while simultaneo
6205 usly working on actual documents
6208 Though of course the developers strive to keep LyX stable in such situations,
6209 syntax errors and the like in your module file could cause strange behavior.
6210 \change_inserted 1414654397 1302962370
6214 \begin_layout Subsubsection
6216 \change_inserted 1414654397 1302962375
6220 \begin_layout Standard
6222 \change_inserted 1414654397 1302962524
6223 Modules are to LyX as packages are to LaTeX.
6224 Sometimes, however, you find yourself wanting a specific inset or character
6225 style just for one document and writing a module that will also be available
6226 to other documents makes little sense.
6227 What you need is LyX's
6228 \begin_inset Quotes eld
6232 \begin_inset Quotes erd
6238 \begin_layout Standard
6240 \change_inserted 1414654397 1302963263
6241 You will find it under
6243 Document\SpecialChar \menuseparator
6244 Settings\SpecialChar \menuseparator
6248 The large text box allows you to enter anything that you might enter in
6249 a layout file or module.
6250 You can think of a document's local layout, in fact, as a module that belongs
6252 So, in particular, you must enter a
6253 \begin_inset Flex Code
6256 \begin_layout Plain Layout
6258 \change_inserted 1414654397 1302962556
6267 Any format is acceptable, but one would normally use the format current
6269 (In LyX 2.0, the current layout format is 35.) You should be aware that local
6270 layout is not supported by versions of LyX prior to 1.6, so you should not
6271 use it if you want to be able to export your document to LyX 1.5 or earlier
6272 (without, that is, losing the local layout information).
6273 If you wish to be able to export to 1.6---local layout is supported in 1.6,
6274 though there is no UI for it---then you should use format 11 and, of course,
6275 use only layout constructs that were available in LyX 1.6.
6278 \begin_layout Standard
6280 \change_inserted 1414654397 1302963275
6281 When you have entered something in the
6282 \begin_inset Flex Code
6285 \begin_layout Plain Layout
6287 \change_inserted 1414654397 1302963275
6295 pane, LyX will enable the
6296 \begin_inset Quotes eld
6300 \begin_inset Quotes erd
6303 button at the bottom.
6304 Clicking this button will cause LyX to determine whether what you have
6305 entered is valid layout information for the chosen format.
6306 LyX will report the result but, unfortunately, will not tell you what errors
6307 there might have been.
6308 These will be written to the terminal, however, if LyX is started from
6310 You will not be permitted to save your local layout until you have entered
6314 \begin_layout Standard
6316 \change_inserted 1414654397 1302963364
6317 The warnings at the end of the previous section apply here, too.
6318 Do not play with local layout while you are actually working, especially
6319 if you have not saved your document.
6320 That said, using local layout with a test document can be a very convenient
6321 way to try out layout ideas, or even to start developing a module.
6326 \begin_layout Subsection
6328 \begin_inset Flex MenuItem
6331 \begin_layout Plain Layout
6340 \begin_layout Standard
6341 There are two situations you are likely to encounter when wanting to support
6342 a new LaTeX document class, involving style (
6343 \begin_inset Flex Code
6346 \begin_layout Plain Layout
6352 ) files and LaTeX2e class (
6353 \begin_inset Flex Code
6356 \begin_layout Plain Layout
6363 Supporting a style file is usually fairly easy.
6364 Supporting a new class file is a bit harder.
6365 We'll discuss the former in this section and the latter in the next.
6366 Similar remarks apply, of course, if you want to support a new DocBook
6370 \begin_layout Standard
6371 The easier case is the one in which your new document class is provided
6372 as a style file that is to be used in conjunction with an already supported
6374 For the sake of the example, we'll assume that the style file is called
6376 \begin_inset Flex MenuItem
6379 \begin_layout Plain Layout
6385 and that it is meant to be used with
6386 \begin_inset Flex MenuItem
6389 \begin_layout Plain Layout
6395 , which is a standard class.
6399 \begin_layout Standard
6400 Start by copying the existing class's layout file into your local directory:
6404 \begin_layout Plain Layout
6405 Of course, which directory is your local directory will vary by platform,
6406 and LyX allows you to specify your local directory on startup, too, using
6408 \begin_inset Flex Code
6411 \begin_layout Plain Layout
6425 \begin_layout LyX-Code
6426 cp report.layout ~/.lyx/layouts/myclass.layout
6429 \begin_layout Standard
6431 \begin_inset Flex Code
6434 \begin_layout Plain Layout
6440 and change the line:
6443 \begin_layout LyX-Code
6446 DeclareLaTeXClass{report}
6449 \begin_layout Standard
6453 \begin_layout LyX-Code
6456 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6459 \begin_layout Standard
6463 \begin_layout LyX-Code
6465 \begin_inset Newline newline
6471 \begin_inset Newline newline
6477 \begin_layout Standard
6478 near the top of the file.
6481 \begin_layout Standard
6482 Start LyX and select
6483 \begin_inset Flex MenuItem
6486 \begin_layout Plain Layout
6487 Tools\SpecialChar \menuseparator
6494 Then restart LyX and try creating a new document.
6496 \begin_inset Flex MenuItem
6499 \begin_layout Plain Layout
6505 " as a document class option in the
6506 \begin_inset Flex MenuItem
6509 \begin_layout Plain Layout
6510 Document\SpecialChar \menuseparator
6517 It is likely that some of the sectioning commands and such in your new
6518 class will work differently from how they worked in the base class—
6519 \begin_inset Flex Code
6522 \begin_layout Plain Layout
6528 in this example—so you can fiddle around with the settings for the different
6529 sections if you wish.
6530 The layout information for sections is contained in
6531 \begin_inset Flex Code
6534 \begin_layout Plain Layout
6540 , but you do not need to copy and change this file.
6541 Instead, you can simply add your changes to your layout file, after the
6543 \begin_inset Flex Code
6546 \begin_layout Plain Layout
6552 , which itself includes
6553 \begin_inset Flex Code
6556 \begin_layout Plain Layout
6563 For example, you might add these lines:
6566 \begin_layout LyX-Code
6570 \begin_layout LyX-Code
6574 \begin_layout LyX-Code
6578 \begin_layout LyX-Code
6582 \begin_layout LyX-Code
6586 \begin_layout Standard
6587 to change the font for chapter headings to sans-serif.
6588 This will override (or, in this case, add to) the existing declaration
6589 for the Chapter style.
6593 \begin_layout Standard
6594 Your new package may also provide commands or environments not present in
6596 In this case, you will want to add these to the layout file.
6598 \begin_inset CommandInset ref
6600 reference "sec:TextClass"
6604 for information on how to do so.
6607 \begin_layout Standard
6609 \begin_inset Flex MenuItem
6612 \begin_layout Plain Layout
6618 can be used with several different document classes, and even if it cannot,
6619 you might find it easiest just to write a module that you can load with
6621 The simplest possible such module would be:
6624 \begin_layout LyX-Code
6627 DeclareLyXModule{My Package}
6630 \begin_layout LyX-Code
6634 \begin_layout LyX-Code
6635 #Support for mypkg.sty.
6638 \begin_layout LyX-Code
6640 \begin_inset Newline newline
6646 \begin_layout LyX-Code
6648 \begin_inset Newline newline
6654 \begin_layout LyX-Code
6656 \begin_inset Newline newline
6662 \begin_inset Newline newline
6668 \begin_layout Standard
6669 A more complex module might modify the behavior of some existing constructs
6670 or define some new ones.
6672 \begin_inset CommandInset ref
6674 reference "sec:TextClass"
6681 \begin_layout Subsection
6683 \begin_inset Flex MenuItem
6686 \begin_layout Plain Layout
6695 \begin_layout Standard
6696 There are two possibilities here.
6697 One is that the class file is itself based upon an existing document class.
6698 For example, many thesis classes are based upon
6699 \begin_inset Flex MenuItem
6702 \begin_layout Plain Layout
6709 To see whether yours is, look for a line like
6712 \begin_layout LyX-Code
6718 \begin_layout Standard
6720 If so, then you may proceed largely as in the previous section, though
6722 \begin_inset Flex Code
6725 \begin_layout Plain Layout
6731 line will be different.
6732 If your new class is
6733 \begin_inset Flex Code
6736 \begin_layout Plain Layout
6742 and it is based upon
6743 \begin_inset Flex Code
6746 \begin_layout Plain Layout
6752 , then the line should read:
6756 \begin_layout Plain Layout
6757 And it will be easiest if you save the file to
6758 \begin_inset Flex Code
6761 \begin_layout Plain Layout
6767 : LyX assumes that the document class has the same name as the layout file.
6776 \begin_layout LyX-Code
6779 DeclareLaTeXClass[thesis,book]{thesis}
6782 \begin_layout Standard
6783 If, on the other hand, the new class is not based upon an existing class,
6784 you will probably have to
6785 \begin_inset Quotes eld
6789 \begin_inset Quotes erd
6793 We strongly suggest copying an existing layout file which uses a similar
6794 LaTeX class and then modifying it, if you can do so.
6795 At least use an existing file as a starting point so you can find out what
6796 items you need to worry about.
6797 Again, the specifics are covered below.
6800 \begin_layout Subsection
6802 \begin_inset CommandInset label
6804 name "sub:Creating-Templates"
6811 \begin_layout Standard
6812 Once you have written a layout file for a new document class, you might
6813 want to consider writing a
6818 A template acts as a kind of tutorial for your layout, showing how it might
6819 be used, though containing dummy content.
6820 You can of course look at the various templates included with LyX for ideas.
6823 \begin_layout Standard
6824 Templates are created just like usual documents: using LyX.
6825 The only difference is that usual documents contain all possible settings,
6826 including the font scheme and the paper size.
6827 Usually a user doesn't want a template to overwrite his preferred settings
6828 for such parameters.
6829 For that reason, the designer of a template should remove the corresponding
6831 \begin_inset Flex Code
6834 \begin_layout Plain Layout
6843 \begin_inset Flex Code
6846 \begin_layout Plain Layout
6854 from the template LyX file.
6855 This can be done with any simple text-editor, for example
6856 \begin_inset Flex Code
6859 \begin_layout Plain Layout
6866 \begin_inset Flex Code
6869 \begin_layout Plain Layout
6879 \begin_layout Standard
6880 Put the edited template files you create in
6881 \begin_inset Flex Code
6884 \begin_layout Plain Layout
6890 , copy the ones you use from the global template directory in
6891 \begin_inset Flex Code
6894 \begin_layout Plain Layout
6900 to the same place, and redefine the template path in the
6901 \begin_inset Flex MenuItem
6904 \begin_layout Plain Layout
6905 Tools\SpecialChar \menuseparator
6906 Preferences\SpecialChar \menuseparator
6915 \begin_layout Standard
6916 Note, by the way, that there is a template which has a particular meaning:
6918 \begin_inset Flex Code
6921 \begin_layout Plain Layout
6928 This template is loaded every time you create a new document with
6929 \begin_inset Flex MenuItem
6932 \begin_layout Plain Layout
6933 File\SpecialChar \menuseparator
6939 in order to provide useful defaults.
6940 To create this template from inside LyX, all you have to do is to open
6941 a document with the correct settings, and use the
6942 \begin_inset Flex MenuItem
6945 \begin_layout Plain Layout
6946 Save as Document Defaults
6954 \begin_layout Subsection
6955 Upgrading old layout files
6958 \begin_layout Standard
6959 The format of layout files changes with each LyX release, so old layout
6960 files need to be converted to the new format.
6961 This process has been automated since LyX 1.4: If LyX reads a layout file
6962 in an older format, it automatically calls the script
6963 \begin_inset Flex Code
6966 \begin_layout Plain Layout
6972 to convert it to a temporary file in current format.
6973 The original file is left untouched.
6974 If you use the layout file often, then, you may want to convert it permanently,
6975 so that LyX does not have to do so itself every time.
6976 To do this, you can call the converter manually:
6979 \begin_layout LyX-Code
6980 mv myclass.layout myclass.old
6983 \begin_layout LyX-Code
6984 python LyXDir/scripts/layout2layout.py myclass.old myclass.layout
6987 \begin_layout Standard
6989 \begin_inset Flex Code
6992 \begin_layout Plain Layout
6998 with the name of your LyX system directory, of course.
7001 \begin_layout Standard
7002 Note that manual conversion does not affect included files, so these will
7003 have to be converted separately.
7006 \begin_layout Section
7007 \begin_inset CommandInset label
7009 name "sec:TextClass"
7013 The layout file format
7016 \begin_layout Standard
7017 When it's finally time to get your hands dirty and create or edit your own
7018 layout file, the following sections describe what you're up against.
7019 Our advice is to go slowly, save and test often, listen to soothing music,
7020 and enjoy one or two of your favorite adult beverages; more if you are
7021 getting particularly stuck.
7022 It's really not that hard, except that the multitude of options can become
7023 overwhelming if you try to do too much in one sitting.
7024 Go have another adult beverage, just for good measure.
7027 \begin_layout Standard
7028 Note that all the tags used in layout files are case-insensitive.
7030 \begin_inset Flex Code
7033 \begin_layout Plain Layout
7040 \begin_inset Flex Code
7043 \begin_layout Plain Layout
7050 \begin_inset Flex Code
7053 \begin_layout Plain Layout
7059 are really the same tag.
7060 The possible values are printed in brackets after the feature's name.
7061 The default value if a feature isn't specified inside a text class-description
7063 \begin_inset Flex Code
7066 \begin_layout Plain Layout
7075 If the argument has a data type like
7076 \begin_inset Quotes eld
7080 \begin_inset Quotes erd
7084 \begin_inset Quotes eld
7088 \begin_inset Quotes erd
7091 , the default is shown like this:
7092 \begin_inset Flex Code
7095 \begin_layout Plain Layout
7106 \begin_layout Subsection
7107 The document class declaration
7110 \begin_layout Standard
7111 Lines in a layout file which begin with
7112 \begin_inset Flex Code
7115 \begin_layout Plain Layout
7122 There is one exception to this rule.
7124 \begin_inset Flex Code
7127 \begin_layout Plain Layout
7133 files should begin with a line like:
7136 \begin_layout LyX-Code
7139 #% Do not delete the line below; configure depends on this
7142 \begin_layout LyX-Code
7147 DeclareLaTeXClass{article}
7150 \begin_layout Standard
7151 The second line is used when you (re)configure LyX.
7152 The layout file is read by the LaTeX script
7153 \begin_inset Flex Code
7156 \begin_layout Plain Layout
7162 , in a special mode where
7163 \begin_inset Flex Code
7166 \begin_layout Plain Layout
7173 The first line is just a LaTeX comment, and the second one contains the
7174 declaration of the text class.
7175 If these lines appear in a file named
7176 \begin_inset Flex Code
7179 \begin_layout Plain Layout
7185 , then they define a text class of name
7186 \begin_inset Flex Code
7189 \begin_layout Plain Layout
7195 (the name of the layout file) which uses the LaTeX document class
7196 \begin_inset Flex Code
7199 \begin_layout Plain Layout
7205 (the default is to use the same name as the layout).
7207 \begin_inset Quotes eld
7211 \begin_inset Quotes erd
7214 that appears above is used as a description of the text class in the
7215 \begin_inset Flex MenuItem
7218 \begin_layout Plain Layout
7219 Document\SpecialChar \menuseparator
7228 \begin_layout Standard
7229 Let's assume that you wrote your own text class that uses the
7230 \begin_inset Flex Code
7233 \begin_layout Plain Layout
7239 document class, but where you changed the appearance of the section headings.
7240 If you put it in a file
7241 \begin_inset Flex Code
7244 \begin_layout Plain Layout
7250 , the header of this file should be:
7253 \begin_layout LyX-Code
7256 #% Do not delete the line below; configure depends on this
7259 \begin_layout LyX-Code
7264 DeclareLaTeXClass[article]{article (with my own headings)}
7267 \begin_layout Standard
7268 This declares a text class
7269 \begin_inset Flex Code
7272 \begin_layout Plain Layout
7278 , associated with the LaTeX document class
7279 \begin_inset Flex Code
7282 \begin_layout Plain Layout
7289 \begin_inset Quotes eld
7292 article (with my own headings)
7293 \begin_inset Quotes erd
7297 If your text class depends on several packages, you can declare it as:
7300 \begin_layout LyX-Code
7303 #% Do not delete the line below; configure depends on this
7306 \begin_layout LyX-Code
7311 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
7314 \begin_layout Standard
7315 This indicates that your text class uses the
7316 \begin_inset Flex Code
7319 \begin_layout Plain Layout
7326 Finally, it is also possible to declare classes for DocBook code.
7327 Typical declarations will look like:
7330 \begin_layout LyX-Code
7333 #% Do not delete the line below; configure depends on this
7336 \begin_layout LyX-Code
7341 DeclareDocBookClass[article]{SGML (DocBook article)}
7344 \begin_layout Standard
7345 Note that these declarations can also be given an optional parameter declaring
7346 the name of the document class (but not a list).
7349 \begin_layout Standard
7350 So, to be as explicit as possible, the form of the layout declaration is:
7353 \begin_layout LyX-Code
7358 DeclareLaTeXClass[class,package.sty]{layout description}
7361 \begin_layout Standard
7362 The class need only be specified if the name of the LaTeX class file and
7363 the name of the layout file are different or if there are packages to load.
7364 If the name of the class file is not specified, then LyX will simply assume
7365 that it is the same as the name of the layout file.
7368 \begin_layout Standard
7369 When the text class has been modified to your taste, all you have to do
7370 is to copy it either to
7371 \begin_inset Flex Code
7374 \begin_layout Plain Layout
7381 \begin_inset Flex Code
7384 \begin_layout Plain Layout
7391 \begin_inset Flex MenuItem
7394 \begin_layout Plain Layout
7395 Tools\SpecialChar \menuseparator
7401 , exit LyX and restart.
7402 Then your new text class should be available along with the others.
7405 \begin_layout Standard
7406 Once the layout file is installed, you can edit it and see your changes
7407 without having to reconfigure or to restart LyX.
7412 \begin_layout Plain Layout
7413 In versions of LyX prior to 1.6, this was not true.
7414 As a result, editing layout files was very time consuming, since you had
7415 constantly to restart LyX to see changes.
7420 You can force a reload of the current layout by using the LyX function
7422 \begin_inset Flex MenuItem
7425 \begin_layout Plain Layout
7432 There is no default binding for this function—though, of course, you can
7433 bind it to a key yourself.
7434 But you will normally use this function simply by entering it in the mini-buffe
7439 \begin_layout Standard
7445 \begin_inset Flex MenuItem
7448 \begin_layout Plain Layout
7454 is very much an `advanced feature'.
7459 recommended that you save your work before using this function.
7464 recommended that you not attempt to edit layout information while simultaneousl
7465 y working on a document that you care about.
7466 Use a test document.
7467 Syntax errors and the like in your layout file could cause peculiar behavior.
7468 In particular, such errors could cause LyX to regard the current layout
7469 as invalid and to attempt to switch to some other layout.
7473 \begin_layout Plain Layout
7474 Really bad syntax errors may even caused LyX to exit.
7475 This is because certain sorts of errors may make LyX unable to read
7485 The LyX team strives to keep LyX stable in such situations, but safe is
7490 \begin_layout Plain Layout
7491 While we're giving advice: make regular backups.
7492 And be nice to your mother.
7500 \begin_layout Subsection
7501 The Module declaration
7504 \begin_layout Standard
7505 A module must begin with a line like the following:
7508 \begin_layout LyX-Code
7511 DeclareLyXModule[endnotes.sty]{Endnotes}
7514 \begin_layout Standard
7515 The mandatory argument, in curly brackets, is the name of the module, as
7517 \begin_inset Flex MenuItem
7520 \begin_layout Plain Layout
7521 Document\SpecialChar \menuseparator
7522 Settings\SpecialChar \menuseparator
7529 The argument in square brackets is optional: It declares any LaTeX packages
7530 on which the module depends.
7531 Please note that only packages about which LyX knows should be listed in
7532 the square brackets.
7536 \begin_layout Plain Layout
7537 The list of such packages is documented only in the source code.
7542 LyX will not check for arbitrary packages.
7543 It is also possible to use the form
7544 \begin_inset Flex MenuItem
7547 \begin_layout Plain Layout
7553 as an optional argument, which declares that the module can only be used
7554 when there exists a conversion chain between the formats `
7555 \begin_inset Flex Code
7558 \begin_layout Plain Layout
7565 \begin_inset Flex Code
7568 \begin_layout Plain Layout
7577 \begin_layout Standard
7578 The module declaration should then be followed by lines like the following
7582 \begin_layout Plain Layout
7583 Preferably in English if the module should be published with LyX.
7584 This description will appear in the list of messages to be translated and
7585 will be thus translated with the next interface update.
7593 \begin_layout LyX-Code
7597 \begin_layout LyX-Code
7598 #Adds an endnote command, in addition to footnotes.
7602 \begin_layout LyX-Code
7603 #You will need to add
7605 theendnotes in TeX code where you
7608 \begin_layout LyX-Code
7609 #want the endnotes to appear.
7613 \begin_layout LyX-Code
7617 \begin_layout LyX-Code
7618 #Requires: somemodule | othermodule
7621 \begin_layout LyX-Code
7622 #Excludes: badmodule
7625 \begin_layout Standard
7626 The description is used in
7627 \begin_inset Flex MenuItem
7630 \begin_layout Plain Layout
7631 Document\SpecialChar \menuseparator
7632 Settings\SpecialChar \menuseparator
7638 to provide the user with information about what the module does.
7640 \begin_inset Flex Code
7643 \begin_layout Plain Layout
7649 line is used to identify other modules with which this one must be used;
7651 \begin_inset Flex Code
7654 \begin_layout Plain Layout
7660 line is used to identify modules with which this one may not be used.
7661 Both are optional, and, as shown, multiple modules should be separated
7662 with the pipe symbol: |.
7663 Note that the required modules are treated disjunctively:
7667 of the required modules must be used.
7672 excluded module may be used.
7673 Note that modules are identified here by their
7678 \begin_inset Flex Code
7681 \begin_layout Plain Layout
7689 \begin_inset Flex Code
7692 \begin_layout Plain Layout
7699 \begin_inset Flex Code
7702 \begin_layout Plain Layout
7711 \begin_layout Subsection
7715 \begin_layout Standard
7716 The first non-comment line of any layout file, included file, or module
7721 contain the file format number:
7724 \begin_layout Description
7725 \begin_inset Flex Code
7728 \begin_layout Plain Layout
7735 \begin_inset Flex Code
7738 \begin_layout Plain Layout
7744 ] The format of the layout file.
7747 \begin_layout Standard
7748 This tag was introduced with LyX 1.4.0.
7749 Layout files from LyX 1.3.x and earlier don't have an explicit file format
7750 and are considered to be of format 1.
7751 The format for the present version of LyX is format 21.
7752 But each version of LyX is capable of reading earlier versions' layout
7753 files, just as they are capable of reading files produced by earlier versions
7755 There is, however, no provision for converting to earlier formats.
7756 So LyX 1.6.x will not read layout files in format 21 but only files in format
7760 \begin_layout Subsection
7761 \begin_inset CommandInset label
7763 name "sub:General-text-class"
7767 General text class parameters
7770 \begin_layout Standard
7771 These are general parameters that govern the behavior of an entire document
7777 mean that they must appear in
7778 \begin_inset Flex Code
7781 \begin_layout Plain Layout
7787 files rather than in modules.
7788 A module can contain any layout tag.)
7791 \begin_layout Description
7792 \begin_inset Flex Code
7795 \begin_layout Plain Layout
7801 Adds information that will be output in the
7802 \begin_inset Flex Code
7805 \begin_layout Plain Layout
7811 block when this document class is output to XHTML.
7812 Typically, this would be used to output CSS style information, but it can
7813 be used for anything that can appear in
7814 \begin_inset Flex Code
7817 \begin_layout Plain Layout
7825 \begin_inset Quotes eld
7829 \begin_inset Flex Code
7832 \begin_layout Plain Layout
7839 \begin_inset Quotes erd
7845 \begin_layout Description
7846 \begin_inset Flex Code
7849 \begin_layout Plain Layout
7855 Adds information to the document preamble.
7857 \begin_inset Quotes eld
7861 \begin_inset Flex Code
7864 \begin_layout Plain Layout
7871 \begin_inset Quotes erd
7877 \begin_layout Description
7878 \begin_inset Flex Code
7881 \begin_layout Plain Layout
7887 Defines formats for use in the display of bibliographic information.
7889 \begin_inset CommandInset ref
7891 reference "sub:Citation-format-description"
7897 \begin_inset Quotes eld
7901 \begin_inset Flex Code
7904 \begin_layout Plain Layout
7911 \begin_inset Quotes erd
7917 \begin_layout Description
7918 \begin_inset Flex Code
7921 \begin_layout Plain Layout
7927 Describes various global options supported by the document class.
7929 \begin_inset space ~
7933 \begin_inset CommandInset ref
7935 reference "sub:ClassOptions"
7941 \begin_inset Quotes eld
7945 \begin_inset Flex Code
7948 \begin_layout Plain Layout
7955 \begin_inset Quotes erd
7961 \begin_layout Description
7962 \begin_inset Flex Code
7965 \begin_layout Plain Layout
7972 \begin_inset Flex Code
7975 \begin_layout Plain Layout
7984 \begin_inset Flex Code
7987 \begin_layout Plain Layout
7993 ] Whether the class should
7997 to having one or two columns.
7998 Can be changed in the
7999 \begin_inset Flex MenuItem
8002 \begin_layout Plain Layout
8003 Document\SpecialChar \menuseparator
8012 \begin_layout Description
8013 \begin_inset Flex Code
8016 \begin_layout Plain Layout
8023 \begin_inset Flex Code
8026 \begin_layout Plain Layout
8032 ] This sequence defines the properties for a counter.
8033 If the counter does not yet exist, it is created; if it does exist, it
8036 \begin_inset Quotes eld
8040 \begin_inset Flex Code
8043 \begin_layout Plain Layout
8050 \begin_inset Quotes erd
8054 \begin_inset Newline newline
8058 \begin_inset space ~
8062 \begin_inset CommandInset ref
8064 reference "sub:Counters"
8068 for details on counters.
8071 \begin_layout Description
8072 \begin_inset Flex Code
8075 \begin_layout Plain Layout
8081 Sets the default font used to display the document.
8083 \begin_inset space ~
8087 \begin_inset CommandInset ref
8089 reference "sub:Font-description"
8093 for how to declare fonts.
8095 \begin_inset Quotes eld
8099 \begin_inset Flex Code
8102 \begin_layout Plain Layout
8109 \begin_inset Quotes erd
8115 \begin_layout Description
8116 \begin_inset Flex Code
8119 \begin_layout Plain Layout
8126 \begin_inset Flex Code
8129 \begin_layout Plain Layout
8135 Specifies a module to be included by default with this document class.
8136 The module should be specified by filename without the
8137 \begin_inset Flex Code
8140 \begin_layout Plain Layout
8147 The user can still remove the module, but it will be active at the outset.
8148 (This applies only when new files are created, or when this class is chosen
8149 for an existing document.)
8152 \begin_layout Description
8153 \begin_inset Flex Code
8156 \begin_layout Plain Layout
8163 \begin_inset Flex Code
8166 \begin_layout Plain Layout
8172 ] This is the style that will be assigned to new paragraphs, usually
8173 \begin_inset Flex MenuItem
8176 \begin_layout Plain Layout
8183 This will default to the first defined style if not given, but you are
8184 encouraged to use this directive.
8187 \begin_layout Description
8188 \begin_inset Flex Code
8191 \begin_layout Plain Layout
8198 \begin_inset Flex Code
8201 \begin_layout Plain Layout
8207 ] This tag indicates that the module in question—which should be specified
8208 by filename without the
8209 \begin_inset Flex Code
8212 \begin_layout Plain Layout
8218 extension—cannot be used with this document class.
8219 This might be used in a journal-specific layout file to prevent, say, the
8221 \begin_inset Flex Code
8224 \begin_layout Plain Layout
8230 module that numbers theorems by section.
8235 be used in a module.
8236 Modules have their own way of excluding other modules (see
8237 \begin_inset CommandInset ref
8239 reference "sub:Layout-modules"
8246 \begin_layout Description
8247 \begin_inset Flex Code
8250 \begin_layout Plain Layout
8256 Defines a new float.
8258 \begin_inset space ~
8262 \begin_inset CommandInset ref
8264 reference "sub:Floats"
8270 \begin_inset Quotes eld
8274 \begin_inset Flex Code
8277 \begin_layout Plain Layout
8284 \begin_inset Quotes erd
8290 \begin_layout Description
8291 \begin_inset Flex Code
8294 \begin_layout Plain Layout
8300 Sets the information that will be output in the
8301 \begin_inset Flex Code
8304 \begin_layout Plain Layout
8310 block when this document class is output to XHTML.
8311 Note that this will completely override any prior
8312 \begin_inset Flex Code
8315 \begin_layout Plain Layout
8322 \begin_inset Flex Code
8325 \begin_layout Plain Layout
8333 \begin_inset Flex Code
8336 \begin_layout Plain Layout
8342 if you just want to add material to the preamble.) Must end with
8343 \begin_inset Quotes eld
8347 \begin_inset Flex Code
8350 \begin_layout Plain Layout
8357 \begin_inset Quotes erd
8363 \begin_layout Description
8364 \begin_inset Flex Code
8367 \begin_layout Plain Layout
8374 \begin_inset Flex Code
8377 \begin_layout Plain Layout
8383 ] The layout to use for the table of contents, bibliography, and so forth,
8384 when the document is output to HTML.
8385 For articles, this should normally be Section; for books, Chapter.
8386 If it is not given, then LyX will attempt to figure out which layout to
8390 \begin_layout Description
8391 \begin_inset Flex Code
8394 \begin_layout Plain Layout
8401 \begin_inset Flex Code
8404 \begin_layout Plain Layout
8410 ] Modifies the properties of the given counter.
8411 If the counter does not exist, the section is ignored.
8413 \begin_inset Quotes eld
8417 \begin_inset Flex Code
8420 \begin_layout Plain Layout
8427 \begin_inset Quotes erd
8431 \begin_inset Newline newline
8435 \begin_inset space ~
8439 \begin_inset CommandInset ref
8441 reference "sub:Counters"
8445 for details on counters.
8448 \begin_layout Description
8449 \begin_inset Flex Code
8452 \begin_layout Plain Layout
8459 \begin_inset Flex Code
8462 \begin_layout Plain Layout
8468 ] Modifies the properties of the given paragraph style.
8469 If the style does not exist, the section is ignored.
8471 \begin_inset Quotes eld
8475 \begin_inset Flex Code
8478 \begin_layout Plain Layout
8485 \begin_inset Quotes erd
8491 \begin_layout Description
8492 \begin_inset Flex Code
8495 \begin_layout Plain Layout
8501 As its name implies, this command allows you to include another layout
8502 definition file within yours to avoid duplicating commands.
8503 Common examples are the standard layout files, for example,
8504 \begin_inset Flex Code
8507 \begin_layout Plain Layout
8513 , which contains most of the basic layouts.
8516 \begin_layout Description
8517 \begin_inset Flex Code
8520 \begin_layout Plain Layout
8526 This section (re-)defines the layout of an inset.
8527 It can be applied to an existing inset or to a new, user-defined inset,
8528 e.g., a new character style.
8530 \begin_inset Quotes eld
8534 \begin_inset Flex Code
8537 \begin_layout Plain Layout
8544 \begin_inset Quotes erd
8548 \begin_inset Newline newline
8552 \begin_inset space ~
8556 \begin_inset CommandInset ref
8558 reference "sub:Flex-insets-and"
8562 for more information.
8566 \begin_layout Description
8567 \begin_inset Flex Code
8570 \begin_layout Plain Layout
8577 \begin_inset Flex Code
8580 \begin_layout Plain Layout
8586 ] A string that indicates the width of the left margin on the screen, for
8588 \begin_inset Quotes eld
8592 \begin_inset Quotes erd
8596 (Note that this is not a `length', like
8597 \begin_inset Quotes eld
8601 \begin_inset Quotes erd
8607 \begin_layout Description
8608 \begin_inset Flex Code
8611 \begin_layout Plain Layout
8618 \begin_inset Flex Code
8621 \begin_layout Plain Layout
8627 ] This command deletes an existing counter, usually one defined in an included
8631 \begin_layout Description
8632 \begin_inset Flex Code
8635 \begin_layout Plain Layout
8641 This command deletes an existing float.
8642 This is particularly useful when you want to suppress a float that has
8643 been defined in an input file.
8646 \begin_layout Description
8647 \begin_inset Flex Code
8650 \begin_layout Plain Layout
8656 This command deletes an existing style.
8657 This is particularly useful when you want to suppress a style that has
8658 be defined in an input file.
8661 \begin_layout Description
8662 \begin_inset Flex Code
8665 \begin_layout Plain Layout
8671 A string indicating the file format (as defined in the Preferences dialog)
8672 produced by this class.
8673 It is mainly useful when
8674 \begin_inset Flex Code
8677 \begin_layout Plain Layout
8683 is `literate' and one wants to define a new type of literate document.
8684 This string is reset to `docbook', `latex', or `literate' when the correspondin
8686 \begin_inset Flex Code
8689 \begin_layout Plain Layout
8695 parameter is encountered.
8698 \begin_layout Description
8699 \begin_inset Flex Code
8702 \begin_layout Plain Layout
8708 A string indicating what sort of output documents using this class will
8710 At present, the options are: `docbook', `latex', and `literate'.
8713 \begin_layout Description
8714 \begin_inset Flex Code
8717 \begin_layout Plain Layout
8724 \begin_inset Flex Code
8727 \begin_layout Plain Layout
8736 \begin_inset Flex Code
8739 \begin_layout Plain Layout
8746 \begin_inset Flex Code
8749 \begin_layout Plain Layout
8755 ] The default pagestyle.
8756 Can be changed in the
8757 \begin_inset Flex MenuItem
8760 \begin_layout Plain Layout
8761 Document\SpecialChar \menuseparator
8770 \begin_layout Description
8771 \begin_inset Flex Code
8774 \begin_layout Plain Layout
8780 Sets the preamble for the LaTeX document.
8781 Note that this will completely override any prior
8782 \begin_inset Flex Code
8785 \begin_layout Plain Layout
8792 \begin_inset Flex Code
8795 \begin_layout Plain Layout
8803 \begin_inset Flex Code
8806 \begin_layout Plain Layout
8812 if you just want to add material to the preamble.) Must end with
8813 \begin_inset Quotes eld
8817 \begin_inset Flex Code
8820 \begin_layout Plain Layout
8827 \begin_inset Quotes erd
8833 \begin_layout Description
8834 \begin_inset Flex Code
8837 \begin_layout Plain Layout
8844 \begin_inset Flex Code
8847 \begin_layout Plain Layout
8854 \begin_inset Flex Code
8857 \begin_layout Plain Layout
8866 \begin_inset Flex Code
8869 \begin_layout Plain Layout
8875 ] Whether the class already provides the feature
8876 \begin_inset Flex Code
8879 \begin_layout Plain Layout
8886 A feature is in general the name of a package (
8887 \begin_inset Flex Code
8890 \begin_layout Plain Layout
8897 \begin_inset Flex Code
8900 \begin_layout Plain Layout
8906 , \SpecialChar \ldots{}
8908 \begin_inset Flex Code
8911 \begin_layout Plain Layout
8918 \begin_inset Flex Code
8921 \begin_layout Plain Layout
8927 ,\SpecialChar \ldots{}
8928 ); the complete list of supported features is unfortunately not documented
8929 outside the LyX source code—but see
8930 \begin_inset Flex Code
8933 \begin_layout Plain Layout
8939 if you're interested.
8941 \begin_inset Flex MenuItem
8944 \begin_layout Plain Layout
8945 Help\SpecialChar \menuseparator
8951 also gives an overview of the supported packages.
8954 \begin_layout Description
8955 \begin_inset Flex Code
8958 \begin_layout Plain Layout
8965 \begin_inset Flex Code
8968 \begin_layout Plain Layout
8974 ] Indicates that this layout provides the functionality of the module mentioned,
8975 which should be specified by the filename without the
8976 \begin_inset Flex Code
8979 \begin_layout Plain Layout
8986 This will typically be used if the layout includes the module directly,
8987 rather than using the
8988 \begin_inset Flex Code
8991 \begin_layout Plain Layout
8997 tag to indicate that it ought to be used.
8998 It could also be used in a module that provided an alternate implementation
8999 of the same functionality.
9002 \begin_layout Description
9003 \begin_inset Flex Code
9006 \begin_layout Plain Layout
9013 \begin_inset Flex Code
9016 \begin_layout Plain Layout
9022 ] Whether the class requires the feature
9023 \begin_inset Flex Code
9026 \begin_layout Plain Layout
9033 Multiple features must be separated by commas.
9034 Note that you can only request supported features.
9036 \begin_inset Flex Code
9039 \begin_layout Plain Layout
9045 for a list of these.)
9048 \begin_layout Description
9049 \begin_inset Flex Code
9052 \begin_layout Plain Layout
9058 A string that indicates the width of the right margin on the screen, for
9060 \begin_inset Quotes eld
9064 \begin_inset Quotes erd
9070 \begin_layout Description
9071 \begin_inset Flex Code
9074 \begin_layout Plain Layout
9080 Sets which divisions get numbered.
9082 \begin_inset Flex Code
9085 \begin_layout Plain Layout
9094 \begin_layout Description
9095 \begin_inset Flex Code
9098 \begin_layout Plain Layout
9105 \begin_inset Flex Code
9108 \begin_layout Plain Layout
9117 \begin_inset Flex Code
9120 \begin_layout Plain Layout
9126 ] Whether the class-default should be printing on one or both sides of the
9128 Can be changed in the
9129 \begin_inset Flex MenuItem
9132 \begin_layout Plain Layout
9133 Document\SpecialChar \menuseparator
9142 \begin_layout Description
9143 \begin_inset Flex Code
9146 \begin_layout Plain Layout
9152 This sequence defines a paragraph style.
9153 If the style does not yet exist, it is created; if it does exist, its parameter
9156 \begin_inset Quotes eld
9160 \begin_inset Flex Code
9163 \begin_layout Plain Layout
9170 \begin_inset Quotes erd
9174 \begin_inset Newline newline
9178 \begin_inset space ~
9182 \begin_inset CommandInset ref
9184 reference "sub:Paragraph-Styles"
9188 for details on paragraph styles.
9191 \begin_layout Description
9192 \begin_inset Flex Code
9195 \begin_layout Plain Layout
9202 \begin_inset Flex Code
9205 \begin_layout Plain Layout
9211 ] The name of the command or environment to be used with
9212 \begin_inset Flex Code
9215 \begin_layout Plain Layout
9224 \begin_layout Description
9225 \begin_inset Flex Code
9228 \begin_layout Plain Layout
9235 \begin_inset Flex Code
9238 \begin_layout Plain Layout
9247 \begin_inset Flex Code
9250 \begin_layout Plain Layout
9256 ] Indicates what kind of markup is used to define the title of a document.
9258 \begin_inset Flex Code
9261 \begin_layout Plain Layout
9267 means that the macro with name
9268 \begin_inset Flex Code
9271 \begin_layout Plain Layout
9277 will be inserted after the last layout which has
9278 \begin_inset Quotes eld
9282 \begin_inset Flex Code
9285 \begin_layout Plain Layout
9292 \begin_inset Quotes erd
9297 \begin_inset Flex Code
9300 \begin_layout Plain Layout
9306 corresponds to the case where the block of paragraphs which have
9307 \begin_inset Quotes eld
9311 \begin_inset Flex Code
9314 \begin_layout Plain Layout
9321 \begin_inset Quotes erd
9324 should be enclosed into the
9325 \begin_inset Flex Code
9328 \begin_layout Plain Layout
9337 \begin_layout Description
9338 \begin_inset Flex Code
9341 \begin_layout Plain Layout
9347 Sets which divisions are included in the table of contents.
9349 \begin_inset Flex Code
9352 \begin_layout Plain Layout
9361 \begin_layout Subsection
9362 \begin_inset Flex Code
9365 \begin_layout Plain Layout
9372 \begin_inset CommandInset label
9374 name "sub:ClassOptions"
9381 \begin_layout Standard
9383 \begin_inset Flex Code
9386 \begin_layout Plain Layout
9392 section can contain the following entries:
9395 \begin_layout Description
9396 \begin_inset Flex Code
9399 \begin_layout Plain Layout
9406 \begin_inset Flex Code
9409 \begin_layout Plain Layout
9415 ] The list of available font sizes for the document's main font, separated
9417 \begin_inset Quotes eld
9421 \begin_inset Flex Code
9424 \begin_layout Plain Layout
9431 \begin_inset Quotes erd
9437 \begin_layout Description
9438 \begin_inset Flex Code
9441 \begin_layout Plain Layout
9447 Used to set the DTD line with XML-based output classes.
9449 \begin_inset space \thinspace{}
9453 \begin_inset Quotes eld
9456 -//OASIS//DTD DocBook V4.2//EN
9457 \begin_inset Quotes erd
9463 \begin_layout Description
9464 \begin_inset Flex Code
9467 \begin_layout Plain Layout
9474 \begin_inset Flex Code
9477 \begin_layout Plain Layout
9478 string="empty|plain|headings|fancy"
9483 ] The list of available page styles, separated by
9484 \begin_inset Quotes eld
9488 \begin_inset Flex Code
9491 \begin_layout Plain Layout
9498 \begin_inset Quotes erd
9504 \begin_layout Description
9505 \begin_inset Flex Code
9508 \begin_layout Plain Layout
9515 \begin_inset Flex Code
9518 \begin_layout Plain Layout
9524 ] Some document class options, separated by a comma, that will be added
9525 to the optional part of the
9526 \begin_inset Flex Code
9529 \begin_layout Plain Layout
9540 \begin_layout Standard
9542 \begin_inset Flex Code
9545 \begin_layout Plain Layout
9551 section must end with
9552 \begin_inset Quotes eld
9556 \begin_inset Flex Code
9559 \begin_layout Plain Layout
9566 \begin_inset Quotes erd
9572 \begin_layout Subsection
9574 \begin_inset CommandInset label
9576 name "sub:Paragraph-Styles"
9583 \begin_layout Standard
9584 A paragraph style description looks like this:
9588 \begin_layout Plain Layout
9589 Note that this will either define a new style or modify an existing one.
9597 \begin_layout LyX-Code
9604 \begin_layout LyX-Code
9608 \begin_layout LyX-Code
9612 \begin_layout Standard
9613 where the following commands are allowed:
9616 \begin_layout Description
9617 \begin_inset Flex Code
9620 \begin_layout Plain Layout
9627 \begin_inset Flex Code
9630 \begin_layout Plain Layout
9635 , left, right, center
9640 ] Paragraph alignment.
9643 \begin_layout Description
9644 \begin_inset Flex Code
9647 \begin_layout Plain Layout
9654 \begin_inset Flex Code
9657 \begin_layout Plain Layout
9662 , left, right, center
9667 ] A comma separated list of permitted alignments.
9668 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
9670 For example a right-aligned or centered enumeration isn't possible.)
9673 \begin_layout Description
9674 \begin_inset Flex Code
9677 \begin_layout Plain Layout
9683 Note that this will completely override any prior
9684 \begin_inset Flex Code
9687 \begin_layout Plain Layout
9693 declaration for this style.
9695 \begin_inset Quotes eld
9699 \begin_inset Flex Code
9702 \begin_layout Plain Layout
9709 \begin_inset Quotes erd
9714 \begin_inset CommandInset ref
9716 reference "sub:I18n"
9720 for details on its use.
9723 \begin_layout Description
9724 \begin_inset Flex Code
9727 \begin_layout Plain Layout
9734 \begin_inset Flex Code
9737 \begin_layout Plain Layout
9747 \begin_layout Plain Layout
9748 Note that a `float' here is a real number, such as: 1.5.
9753 The vertical space with which the last of a chain of paragraphs with this
9754 style is separated from the following paragraph.
9755 If the next paragraph has another style, the separations are not simply
9756 added, but the maximum is taken.
9759 \begin_layout Description
9760 \begin_inset Flex Code
9763 \begin_layout Plain Layout
9770 \begin_inset Flex Code
9773 \begin_layout Plain Layout
9779 The category for this style.
9780 This is used to group related styles in the style combobox on the toolbar.
9781 Any string can be used, but you may want to use existing categories with
9786 \begin_layout Description
9787 \begin_inset Flex Code
9790 \begin_layout Plain Layout
9796 Depth of XML command.
9797 Used only with XML-type formats.
9800 \begin_layout Description
9801 \begin_inset Flex Code
9804 \begin_layout Plain Layout
9811 \begin_inset CommandInset label
9813 name "des:CopyStyle"
9818 \begin_inset Flex Code
9821 \begin_layout Plain Layout
9827 Copies all the features of an existing style into the current one.
9831 \begin_layout Description
9832 \begin_inset Flex Code
9835 \begin_layout Plain Layout
9841 The name of a style whose preamble should be output
9846 This allows to ensure some ordering of the preamble snippets when macros
9847 definitions depend on one another.
9851 \begin_layout Plain Layout
9852 Note that, besides that functionality, there is no way to ensure any ordering
9854 The ordering that you see in a given version of LyX may change without
9855 warning in later versions.
9863 \begin_layout Description
9864 \begin_inset Flex Code
9867 \begin_layout Plain Layout
9874 \begin_inset Flex Code
9877 \begin_layout Plain Layout
9882 , Box, Filled_Box, Static
9887 ] The type of label that stands at the end of the paragraph (or sequence
9889 \begin_inset Flex Code
9892 \begin_layout Plain Layout
9899 \begin_inset Flex Code
9902 \begin_layout Plain Layout
9909 \begin_inset Flex Code
9912 \begin_layout Plain Layout
9919 \begin_inset Flex Code
9922 \begin_layout Plain Layout
9930 \begin_inset Flex Code
9933 \begin_layout Plain Layout
9940 \begin_inset Quotes eld
9944 \begin_inset Quotes erd
9948 \begin_inset Flex Code
9951 \begin_layout Plain Layout
9958 \begin_inset Flex Code
9961 \begin_layout Plain Layout
9962 \begin_inset space ~
9971 \begin_inset space ~
9974 black) square suitable for end of proof markers,
9975 \begin_inset Flex Code
9978 \begin_layout Plain Layout
9984 is an explicit text string.
9987 \begin_layout Description
9988 \begin_inset Flex Code
9991 \begin_layout Plain Layout
9998 \begin_inset Flex Code
10001 \begin_layout Plain Layout
10007 ] The string used for a label with a
10008 \begin_inset Flex Code
10011 \begin_layout Plain Layout
10018 \begin_inset Flex Code
10021 \begin_layout Plain Layout
10031 \begin_layout Description
10032 \begin_inset Flex Code
10035 \begin_layout Plain Layout
10041 The font used for both the text body
10047 \begin_inset space ~
10051 \begin_inset CommandInset ref
10053 reference "sub:Font-description"
10058 Note that defining this font automatically defines the
10059 \begin_inset Flex Code
10062 \begin_layout Plain Layout
10069 So you should define this one first if you also want to define
10070 \begin_inset Flex Code
10073 \begin_layout Plain Layout
10082 \begin_layout Description
10083 \begin_inset Flex Code
10086 \begin_layout Plain Layout
10093 \begin_inset CommandInset label
10095 name "des:FreeSpacing"
10100 \begin_inset Flex Code
10103 \begin_layout Plain Layout
10112 \begin_inset Flex Code
10115 \begin_layout Plain Layout
10121 ] Usually LyX doesn't allow you to insert more than one space between words,
10122 since a space is considered as the separation between two words, not a
10123 character or symbol of its own.
10124 This is a very fine thing but sometimes annoying, for example, when typing
10125 program code or plain LaTeX code.
10127 \begin_inset Flex Code
10130 \begin_layout Plain Layout
10137 Note that LyX will create protected blanks for the additional blanks when
10138 in another mode than LaTeX-mode.
10141 \begin_layout Description
10142 \begin_inset Flex Code
10145 \begin_layout Plain Layout
10151 These tags are used with XHTML output.
10153 \begin_inset CommandInset ref
10155 reference "sub:Paragraph-Style-XHTML"
10162 \begin_layout Description
10163 \begin_inset Flex Code
10166 \begin_layout Plain Layout
10172 [[FIXME]] (Used only with XML-type formats.)
10175 \begin_layout Description
10176 \begin_inset Flex Code
10179 \begin_layout Plain Layout
10186 \begin_inset Flex Code
10189 \begin_layout Plain Layout
10195 If 1, marks the style as to be included in the document preamble rather
10196 than in the document body.
10197 This is useful for document classes that want such information as the title
10198 and author to appear in the preamble.
10199 Note that this works only for styles for which the
10200 \begin_inset Flex Code
10203 \begin_layout Plain Layout
10210 \begin_inset Flex Code
10213 \begin_layout Plain Layout
10220 \begin_inset Flex Code
10223 \begin_layout Plain Layout
10232 \begin_layout Description
10233 \begin_inset Flex Code
10236 \begin_layout Plain Layout
10243 \begin_inset Flex Code
10246 \begin_layout Plain Layout
10252 If 1, marks the style as being part of a title block (see also the
10253 \begin_inset Flex Code
10256 \begin_layout Plain Layout
10263 \begin_inset Flex Code
10266 \begin_layout Plain Layout
10275 \begin_layout Description
10276 \begin_inset Flex Code
10279 \begin_layout Plain Layout
10286 \begin_inset Flex Code
10289 \begin_layout Plain Layout
10295 ] This provides extra space between paragraphs that have the same style.
10296 If you put other styles into an environment, each is separated with the
10298 \begin_inset Flex Code
10301 \begin_layout Plain Layout
10308 But the whole items of the environment are additionally separated with
10310 \begin_inset Flex Code
10313 \begin_layout Plain Layout
10320 Note that this is a
10325 \begin_layout Description
10326 \begin_inset Flex Code
10329 \begin_layout Plain Layout
10335 [[FIXME]] (Used only with XML-type formats.)
10338 \begin_layout Description
10339 \begin_inset Flex Code
10342 \begin_layout Plain Layout
10349 \begin_inset CommandInset label
10351 name "des:KeepEmpty"
10356 \begin_inset Flex Code
10359 \begin_layout Plain Layout
10368 \begin_inset Flex Code
10371 \begin_layout Plain Layout
10377 ] Usually LyX does not allow you to leave a paragraph empty, since it would
10378 lead to empty LaTeX output.
10379 There are some cases where this could be desirable however: in a letter
10380 template, the required fields can be provided as empty fields, so that
10381 people do not forget them; in some special classes, a style can be used
10382 as some kind of break, which does not contain actual text.
10385 \begin_layout Description
10386 \begin_inset Flex Code
10389 \begin_layout Plain Layout
10395 [float=0] The vertical space between the label and the text body.
10396 Only used for labels that are above the text body (
10397 \begin_inset Flex Code
10400 \begin_layout Plain Layout
10407 \begin_inset Flex Code
10410 \begin_layout Plain Layout
10411 Centered_Top_Environment
10419 \begin_layout Description
10420 \begin_inset Flex Code
10423 \begin_layout Plain Layout
10430 \begin_inset Flex Code
10433 \begin_layout Plain Layout
10440 \begin_inset Newline newline
10443 The name of the counter for automatic numbering.
10445 \begin_inset Newline newline
10453 \begin_inset Flex Code
10456 \begin_layout Plain Layout
10463 \begin_inset Flex Code
10466 \begin_layout Plain Layout
10473 In that case, the counter will be stepped each time the style appears.
10475 \begin_inset Newline newline
10483 \begin_inset Flex Code
10486 \begin_layout Plain Layout
10493 \begin_inset Flex Code
10496 \begin_layout Plain Layout
10502 , though this case is a bit complicated.
10503 Suppose you declare
10504 \begin_inset Quotes eld
10508 \begin_inset Flex Code
10511 \begin_layout Plain Layout
10512 LabelCounter myenum
10518 \begin_inset Quotes erd
10522 Then the actual counters used are
10523 \begin_inset Flex Code
10526 \begin_layout Plain Layout
10533 \begin_inset Flex Code
10536 \begin_layout Plain Layout
10543 \begin_inset Flex Code
10546 \begin_layout Plain Layout
10553 \begin_inset Flex Code
10556 \begin_layout Plain Layout
10562 , much as in LaTeX.
10563 These counters must all be declared separately.
10564 \begin_inset Newline newline
10568 \begin_inset CommandInset ref
10570 reference "sub:Counters"
10574 for details on counters.
10577 \begin_layout Description
10578 \begin_inset Flex Code
10581 \begin_layout Plain Layout
10587 The font used for the label.
10589 \begin_inset space ~
10593 \begin_inset CommandInset ref
10595 reference "sub:Font-description"
10602 \begin_layout Description
10603 \begin_inset Flex Code
10606 \begin_layout Plain Layout
10612 Text that indicates how far a label should be indented.
10615 \begin_layout Description
10616 \begin_inset Flex Code
10619 \begin_layout Plain Layout
10626 \begin_inset Flex Code
10629 \begin_layout Plain Layout
10635 ] The horizontal space between the label and the text body.
10636 Only used for labels that are not above the text body.
10639 \begin_layout Description
10640 \begin_inset Flex Code
10643 \begin_layout Plain Layout
10650 \begin_inset Flex Code
10653 \begin_layout Plain Layout
10659 ] The string used for a label with a
10660 \begin_inset Flex Code
10663 \begin_layout Plain Layout
10671 \begin_inset Flex Code
10674 \begin_layout Plain Layout
10680 is set, this string can be contain the special formatting commands described
10682 \begin_inset CommandInset ref
10684 reference "sub:Counters"
10692 \begin_layout Plain Layout
10693 For the sake of backwards compatibility, the string
10694 \begin_inset Flex Code
10697 \begin_layout Plain Layout
10707 will be replaced by the expanded
10708 \begin_inset Flex Code
10711 \begin_layout Plain Layout
10718 \begin_inset Flex Code
10721 \begin_layout Plain Layout
10730 This feature is now obsolete and should be replaced by the mechanisms of
10732 \begin_inset CommandInset ref
10734 reference "sub:Counters"
10746 \begin_layout Description
10747 \begin_inset Flex Code
10750 \begin_layout Plain Layout
10751 LabelStringAppendix
10757 \begin_inset Flex Code
10760 \begin_layout Plain Layout
10766 ] This is used inside the appendix instead of
10767 \begin_inset Flex Code
10770 \begin_layout Plain Layout
10778 \begin_inset Flex Code
10781 \begin_layout Plain Layout
10788 \begin_inset Flex Code
10791 \begin_layout Plain Layout
10792 LabelStringAppendix
10800 \begin_layout Description
10801 \begin_inset Flex Code
10804 \begin_layout Plain Layout
10810 [FIXME] (Used only with XML-type formats.)
10813 \begin_layout Description
10814 \begin_inset Flex Code
10817 \begin_layout Plain Layout
10824 \begin_inset Flex Code
10827 \begin_layout Plain Layout
10832 , Manual, Static, Top_Environment, Centered_Top_Environment, Counter, Sensitive,
10833 Enumerate, Itemize, Bibliography
10842 \begin_layout Itemize
10843 \begin_inset Flex Code
10846 \begin_layout Plain Layout
10852 means the label is the very first word (up to the first real blank).
10853 Use protected spaces (like
10854 \begin_inset space ~
10857 that one) if you want more than one word as the label.
10861 \begin_layout Itemize
10862 \begin_inset Flex Code
10865 \begin_layout Plain Layout
10871 means the label is simply whatever
10872 \begin_inset Flex Code
10875 \begin_layout Plain Layout
10882 Note that this really is `static'.
10885 \begin_layout Itemize
10886 \begin_inset Flex Code
10889 \begin_layout Plain Layout
10896 \begin_inset Flex Code
10899 \begin_layout Plain Layout
10900 Centered_Top_Environment
10905 are special cases of
10906 \begin_inset Flex Code
10909 \begin_layout Plain Layout
10916 The label will be printed above the paragraph, but only at the top of an
10917 environment or the top of a chain of paragraphs with this style.
10918 This might be used with the
10919 \begin_inset Flex MenuItem
10922 \begin_layout Plain Layout
10928 style, for example.
10931 \begin_layout Itemize
10932 \begin_inset Flex Code
10935 \begin_layout Plain Layout
10941 is a special case for the caption-labels
10942 \begin_inset Quotes eld
10946 \begin_inset Quotes erd
10950 \begin_inset Quotes eld
10954 \begin_inset Quotes erd
10959 \begin_inset Flex Code
10962 \begin_layout Plain Layout
10968 means the (hardcoded) label string depends on the kind of float: It is
10969 hardcoded to be `FloatType N', where N is the value of the counter associated
10973 \begin_layout Itemize
10975 \begin_inset Flex Code
10978 \begin_layout Plain Layout
10984 label type defines automatically numbered labels.
10986 \begin_inset Flex Code
10989 \begin_layout Plain Layout
10995 will be expanded to resolve any counter references it contains: For example,
10997 \begin_inset Quotes eld
11001 \begin_inset Flex Code
11004 \begin_layout Plain Layout
11015 \begin_inset Quotes erd
11020 \begin_inset CommandInset ref
11022 reference "sub:Counters"
11026 for more information on counters.
11029 \begin_layout Itemize
11030 \begin_inset Flex Code
11033 \begin_layout Plain Layout
11039 produces the usual sort of enumeration labels.
11040 At present, it is hardcoded to use Arabic numerals, lowercase letters,
11041 small Roman numerals, and uppercase letters for the four possible depths.
11044 \begin_layout Itemize
11045 \begin_inset Flex Code
11048 \begin_layout Plain Layout
11054 produces various bullets at the different levels.
11055 It is also hardcoded.
11058 \begin_layout Itemize
11059 \begin_inset Flex Code
11062 \begin_layout Plain Layout
11068 is used internally by LyX and should be used only with
11069 \begin_inset Flex Code
11072 \begin_layout Plain Layout
11073 LatexType BibEnvironment
11082 \begin_layout Description
11083 \begin_inset Flex Code
11086 \begin_layout Plain Layout
11092 Note that this will completely override any prior
11093 \begin_inset Flex Code
11096 \begin_layout Plain Layout
11102 declaration for this style.
11104 \begin_inset Quotes eld
11108 \begin_inset Flex Code
11111 \begin_layout Plain Layout
11118 \begin_inset Quotes erd
11123 \begin_inset CommandInset ref
11125 reference "sub:I18n"
11129 for details on its use.
11132 \begin_layout Description
11133 \begin_inset Flex Code
11136 \begin_layout Plain Layout
11142 The name of the corresponding LaTeX stuff.
11143 Either the environment or command name.
11146 \begin_layout Description
11147 \begin_inset Flex Code
11150 \begin_layout Plain Layout
11156 An optional parameter for the corresponding
11157 \begin_inset Flex Code
11160 \begin_layout Plain Layout
11167 This parameter cannot be changed from within LyX.
11170 \begin_layout Description
11171 \begin_inset Flex Code
11174 \begin_layout Plain Layout
11181 \begin_inset CommandInset label
11183 name "des:LatexType"
11188 \begin_inset Flex Code
11191 \begin_layout Plain Layout
11196 , Command, Environment, Item_Environment,
11202 \begin_inset Flex Code
11205 \begin_layout Plain Layout
11206 List_Environment, Bib_Environment
11211 ] How the style should be translated into LaTeX.
11215 \begin_layout Plain Layout
11216 \begin_inset Flex Code
11219 \begin_layout Plain Layout
11225 is perhaps a bit misleading, since these rules apply to SGML classes, too.
11226 Visit the SGML class files for specific examples.
11235 \begin_layout Itemize
11236 \begin_inset Flex Code
11239 \begin_layout Plain Layout
11245 means nothing special.
11249 \begin_layout Itemize
11250 \begin_inset Flex Code
11253 \begin_layout Plain Layout
11260 \begin_inset Flex Code
11263 \begin_layout Plain Layout
11270 {\SpecialChar \ldots{}
11279 \begin_layout Itemize
11280 \begin_inset Flex Code
11283 \begin_layout Plain Layout
11290 \begin_inset Flex Code
11293 \begin_layout Plain Layout
11300 }\SpecialChar \ldots{}
11316 \begin_layout Itemize
11317 \begin_inset Flex Code
11320 \begin_layout Plain Layout
11327 \begin_inset Flex Code
11330 \begin_layout Plain Layout
11337 \begin_inset Flex Code
11340 \begin_layout Plain Layout
11348 is generated for each paragraph of this environment.
11352 \begin_layout Itemize
11353 \begin_inset Flex Code
11356 \begin_layout Plain Layout
11363 \begin_inset Flex Code
11366 \begin_layout Plain Layout
11373 \begin_inset Flex Code
11376 \begin_layout Plain Layout
11382 is passed as an argument to the environment.
11384 \begin_inset Flex Code
11387 \begin_layout Plain Layout
11393 can be defined in the
11394 \begin_inset Flex MenuItem
11397 \begin_layout Plain Layout
11402 \SpecialChar \menuseparator
11408 \begin_inset space ~
11420 \begin_layout Standard
11421 Putting the last few things together, the LaTeX output will be either:
11424 \begin_layout LyX-Code
11427 latexname[latexparam]{\SpecialChar \ldots{}
11431 \begin_layout Standard
11435 \begin_layout LyX-Code
11438 begin{latexname}[latexparam] \SpecialChar \ldots{}
11444 \begin_layout Standard
11445 depending upon the LaTeX type.
11449 \begin_layout Description
11450 \begin_inset Flex Code
11453 \begin_layout Plain Layout
11460 \begin_inset Flex Code
11463 \begin_layout Plain Layout
11469 ] If you put styles into environments, the leftmargins are not simply added,
11470 but added with a factor
11471 \begin_inset Formula $\frac{4}{depth+4}$
11475 Note that this parameter is also used when the margin is defined as
11476 \begin_inset Flex Code
11479 \begin_layout Plain Layout
11486 \begin_inset Flex Code
11489 \begin_layout Plain Layout
11496 Then it is added to the manual or dynamic margin.
11498 \begin_inset Newline newline
11501 The argument is passed as a string.
11503 \begin_inset Quotes eld
11507 \begin_inset Flex Code
11510 \begin_layout Plain Layout
11517 \begin_inset Quotes erd
11520 means that the paragraph is indented with the width of
11521 \begin_inset Quotes eld
11525 \begin_inset Flex Code
11528 \begin_layout Plain Layout
11535 \begin_inset Quotes erd
11538 in the normal font.
11539 You can get a negative width by prefixing the string with
11540 \begin_inset Quotes eld
11544 \begin_inset Flex Code
11547 \begin_layout Plain Layout
11554 \begin_inset Quotes erd
11558 This way was chosen so that the look is the same with each used screen
11563 \begin_layout Description
11564 \begin_inset Flex Code
11567 \begin_layout Plain Layout
11574 \begin_inset Flex Code
11577 \begin_layout Plain Layout
11582 , Manual, Dynamic, First_Dynamic, Right_Address_Box
11588 \begin_inset Newline newline
11591 The kind of margin that the style has on the left side.
11593 \begin_inset Flex Code
11596 \begin_layout Plain Layout
11602 just means a fixed margin.
11604 \begin_inset Flex Code
11607 \begin_layout Plain Layout
11613 means that the left margin depends on the string entered in the
11614 \begin_inset Flex MenuItem
11617 \begin_layout Plain Layout
11618 Edit\SpecialChar \menuseparator
11620 \begin_inset space ~
11629 This is used to typeset nice lists without tabulators.
11631 \begin_inset Flex Code
11634 \begin_layout Plain Layout
11640 means that the margin depends on the size of the label.
11641 This is used for automatic enumerated headlines.
11642 It is obvious that the headline
11643 \begin_inset Quotes eld
11646 5.4.3.2.1 Very long headline
11647 \begin_inset Quotes erd
11650 must have a wider left margin (as wide as
11651 \begin_inset Quotes eld
11655 \begin_inset Quotes erd
11658 plus the space) than
11659 \begin_inset Quotes eld
11662 3.2 Very long headline
11663 \begin_inset Quotes erd
11667 \begin_inset Quotes eld
11671 \begin_inset Quotes erd
11674 are not able to do this.
11676 \begin_inset Flex Code
11679 \begin_layout Plain Layout
11685 is similar, but only the very first row of the paragraph is dynamic, while
11686 the others are static; this is used, for example, for descriptions.
11688 \begin_inset Flex Code
11691 \begin_layout Plain Layout
11697 means the margin is chosen in a way that the longest row of this paragraph
11698 fits to the right margin.
11699 This is used to typeset an address on the right edge of the page.
11702 \begin_layout Description
11703 \begin_inset Flex Code
11706 \begin_layout Plain Layout
11713 \begin_inset Flex Code
11716 \begin_layout Plain Layout
11725 \begin_inset Flex Code
11728 \begin_layout Plain Layout
11734 ] Whether fragile commands in this style should be
11735 \begin_inset Flex Code
11738 \begin_layout Plain Layout
11751 whether this command should itself be protected.)
11754 \begin_layout Description
11755 \begin_inset Flex Code
11758 \begin_layout Plain Layout
11765 \begin_inset Flex Code
11768 \begin_layout Plain Layout
11775 \begin_inset Flex Code
11778 \begin_layout Plain Layout
11786 ] Whether newlines are translated into LaTeX newlines (
11787 \begin_inset Flex Code
11790 \begin_layout Plain Layout
11801 The translation can be switched off to allow more comfortable LaTeX editing
11805 \begin_layout Description
11806 \begin_inset Flex Code
11809 \begin_layout Plain Layout
11816 \begin_inset Flex Code
11819 \begin_layout Plain Layout
11826 \begin_inset Flex Code
11829 \begin_layout Plain Layout
11837 ] Whether the following Paragraph is allowed to indent its very first row.
11839 \begin_inset Flex Code
11842 \begin_layout Plain Layout
11848 means that it is not allowed to do so;
11849 \begin_inset Flex Code
11852 \begin_layout Plain Layout
11858 means it could do so if it wants to.
11861 \begin_layout Description
11862 \begin_inset Flex Code
11865 \begin_layout Plain Layout
11871 Name of a style that has replaced this style.
11872 This is used to rename a style, while keeping backward compatibility.
11875 \begin_layout Description
11876 \begin_inset Flex Code
11879 \begin_layout Plain Layout
11886 \begin_inset Flex Code
11889 \begin_layout Plain Layout
11895 ] The number of optional arguments that can be used with this style.
11896 This is useful for things like section headings, and only makes sense with
11898 Note that, on output, the optional arguments will all precede any required
11899 arguments (see below).
11900 So one can have constructs like:
11904 \begin_layout LyX-Code
11907 mycmd[opt1]{req1}{contents of paragraph}
11910 \begin_layout Standard
11911 but one cannot have things like:
11914 \begin_layout LyX-Code
11917 mycmd[opt1]{req1}[opt2]{contents of paragraph}
11920 \begin_layout Standard
11921 at least, not without ERT (with which you can have anything).
11926 \begin_layout Description
11927 \begin_inset Flex Code
11930 \begin_layout Plain Layout
11937 \begin_inset CommandInset label
11939 name "des:ParbreakIsNewline"
11944 \begin_inset Flex Code
11947 \begin_layout Plain Layout
11956 \begin_inset Flex Code
11959 \begin_layout Plain Layout
11965 ] Indicates that paragraphs will not be separated by an empty line in LaTeX
11966 output, but only by a line break; together with
11967 \begin_inset Flex Code
11970 \begin_layout Plain Layout
11976 , this allows to emulate a plain text editor (like the ERT inset).
11979 \begin_layout Description
11980 \begin_inset Flex Code
11983 \begin_layout Plain Layout
11990 \begin_inset Flex Code
11993 \begin_layout Plain Layout
11999 ] The indent of the very first line of a paragraph.
12001 \begin_inset Flex Code
12004 \begin_layout Plain Layout
12010 will be fixed for a certain style.
12011 The exception is the default style, since the indentation for these paragraphs
12012 can be prohibited with
12013 \begin_inset Flex Code
12016 \begin_layout Plain Layout
12024 \begin_inset Flex Code
12027 \begin_layout Plain Layout
12033 style paragraphs inside environments use the
12034 \begin_inset Flex Code
12037 \begin_layout Plain Layout
12043 of the environment, not their native one.
12045 \begin_inset Flex Code
12048 \begin_layout Plain Layout
12054 paragraphs inside an enumeration are not indented.
12057 \begin_layout Description
12058 \begin_inset Flex Code
12061 \begin_layout Plain Layout
12068 \begin_inset Flex Code
12071 \begin_layout Plain Layout
12077 ] The vertical space between two paragraphs of this style.
12080 \begin_layout Description
12081 \begin_inset Flex Code
12084 \begin_layout Plain Layout
12091 \begin_inset Flex Code
12094 \begin_layout Plain Layout
12100 ] LyX allows the user to choose either
12101 \begin_inset Quotes eld
12105 \begin_inset Quotes erd
12109 \begin_inset Quotes eld
12113 \begin_inset Quotes erd
12116 to typeset a document.
12118 \begin_inset Quotes eld
12122 \begin_inset Quotes erd
12125 is chosen, this value is completely ignored.
12127 \begin_inset Quotes eld
12131 \begin_inset Quotes erd
12134 is chosen, the parindent of a LaTeXtype
12135 \begin_inset Quotes eld
12139 \begin_inset Quotes erd
12142 style is ignored and all paragraphs are separated by this parskip argument.
12143 The vertical space is calculated with
12144 \begin_inset Flex Code
12147 \begin_layout Plain Layout
12149 \begin_inset space ~
12158 \begin_inset Flex Code
12161 \begin_layout Plain Layout
12167 is the height of a row with the normal font.
12168 This way, the look stays the same with different screen fonts.
12171 \begin_layout Description
12172 \begin_inset Flex Code
12175 \begin_layout Plain Layout
12182 \begin_inset CommandInset label
12184 name "des:PassThru"
12189 \begin_inset Flex Code
12192 \begin_layout Plain Layout
12201 \begin_inset Flex Code
12204 \begin_layout Plain Layout
12210 ] Whether the contents of this paragraph should be output in raw form, meaning
12211 without special translations that LaTeX would require.
12214 \begin_layout Description
12215 \begin_inset Flex Code
12218 \begin_layout Plain Layout
12225 \begin_inset CommandInset label
12227 name "des:Preamble"
12231 Information to be included in the LaTeX preamble when this style is used.
12232 Used to define macros, load packages, etc., required by this particular
12235 \begin_inset Quotes eld
12239 \begin_inset Flex Code
12242 \begin_layout Plain Layout
12249 \begin_inset Quotes erd
12255 \begin_layout Description
12256 \begin_inset Flex Code
12259 \begin_layout Plain Layout
12266 \begin_inset Flex Code
12269 \begin_layout Plain Layout
12275 ] The prefix to use when creating labels referring to paragraphs of this
12277 This allows the use of formatted references.
12280 \begin_layout Description
12281 \begin_inset Flex Code
12284 \begin_layout Plain Layout
12291 \begin_inset Flex Code
12294 \begin_layout Plain Layout
12300 ] The number of required arguments that the LaTeX command or environment
12301 corresponding to this style expects.
12302 In the case of a command, these are required arguments
12306 that associated with the content of the paragraph itself.
12307 These do not actually have to be provided: LyX will output empty arguments
12309 Note that optional arguments will be output before required arguments.
12310 See the discussion of the
12311 \begin_inset Flex Code
12314 \begin_layout Plain Layout
12320 tag above for more information.
12323 \begin_layout Description
12324 \begin_inset Flex Code
12327 \begin_layout Plain Layout
12334 \begin_inset Flex Code
12337 \begin_layout Plain Layout
12344 \begin_inset CommandInset label
12346 name "des:Requires"
12350 Whether the style requires the feature
12351 \begin_inset Flex Code
12354 \begin_layout Plain Layout
12361 See the description of
12362 \begin_inset Flex Code
12365 \begin_layout Plain Layout
12372 \begin_inset CommandInset ref
12373 LatexCommand pageref
12374 reference "des:FreeSpacing"
12378 ) for information on `features'.
12382 \begin_layout Description
12383 \begin_inset Flex Code
12386 \begin_layout Plain Layout
12393 \begin_inset Flex Code
12396 \begin_layout Plain Layout
12403 \begin_inset Flex Code
12406 \begin_layout Plain Layout
12415 \begin_layout Description
12416 \begin_inset Flex Code
12419 \begin_layout Plain Layout
12426 \begin_inset Flex Code
12429 \begin_layout Plain Layout
12434 , onehalf, double, other
12443 ] This defines what the default spacing should be in the style.
12445 \begin_inset Flex Code
12448 \begin_layout Plain Layout
12455 \begin_inset Flex Code
12458 \begin_layout Plain Layout
12465 \begin_inset Flex Code
12468 \begin_layout Plain Layout
12474 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
12475 If you specify the argument
12476 \begin_inset Flex Code
12479 \begin_layout Plain Layout
12485 , then you should also provide a numerical argument which will be the actual
12487 Note that, contrary to other parameters,
12488 \begin_inset Flex Code
12491 \begin_layout Plain Layout
12497 implies the generation of specific LaTeX code, using the package
12500 \begin_inset Flex Code
12503 \begin_layout Plain Layout
12512 \begin_layout Description
12513 \begin_inset Flex Code
12516 \begin_layout Plain Layout
12523 \begin_inset Flex Code
12526 \begin_layout Plain Layout
12533 \begin_inset Flex Code
12536 \begin_layout Plain Layout
12544 ] Spellcheck paragraphs of this style.
12548 \begin_layout Description
12549 \begin_inset Flex Code
12552 \begin_layout Plain Layout
12558 The font used for the text body .
12560 \begin_inset CommandInset ref
12562 reference "sub:Font-description"
12569 \begin_layout Description
12570 \begin_inset Flex Code
12573 \begin_layout Plain Layout
12582 \begin_inset Flex Code
12585 \begin_layout Plain Layout
12595 The level of the style in the table of contents.
12596 This is used for automatic numbering of section headings.
12599 \begin_layout Description
12600 \begin_inset Flex Code
12603 \begin_layout Plain Layout
12610 \begin_inset Flex Code
12613 \begin_layout Plain Layout
12619 ] The vertical space with which the very first of a chain of paragraphs
12620 with this style is separated from the previous paragraph.
12621 If the previous paragraph has another style, the separations are not simply
12622 added, but the maximum is taken.
12625 \begin_layout Subsection
12626 \begin_inset CommandInset label
12632 Internationalization of Paragraph Styles
12635 \begin_layout Standard
12636 LyX has long supported internationalization of layout information, but,
12637 until version 2.0, this applied only to the user interface and not to, say,
12639 Thus, French authors were forced to resort to ugly hacks if they wanted
12644 1' instead of `Theorem 1'.
12645 Thanks to Georg Baum, that is no longer the case.
12648 \begin_layout Standard
12650 \begin_inset Flex Code
12653 \begin_layout Plain Layout
12659 defines text that is to appear in the typeset document, it may use
12660 \begin_inset Flex Code
12663 \begin_layout Plain Layout
12670 \begin_inset Flex Code
12673 \begin_layout Plain Layout
12679 to support non-English and even multi-language documents correctly.
12680 The following excerpt (from the
12681 \begin_inset Flex Code
12684 \begin_layout Plain Layout
12690 file) shows how this works:
12693 \begin_layout LyX-Code
12698 \begin_layout LyX-Code
12701 theoremstyle{remark}
12704 \begin_layout LyX-Code
12707 newtheorem{claim}[thm]{
12714 \begin_layout LyX-Code
12718 \begin_layout LyX-Code
12722 \begin_layout LyX-Code
12727 claimname}{_(Claim)}
12730 \begin_layout LyX-Code
12734 \begin_layout LyX-Code
12738 \begin_layout LyX-Code
12747 claimname}{_(Claim)}}
12750 \begin_layout LyX-Code
12755 \begin_layout Standard
12756 In principle, any legal LaTeX may appear in the
12757 \begin_inset Flex Code
12760 \begin_layout Plain Layout
12767 \begin_inset Flex Code
12770 \begin_layout Plain Layout
12776 tags, but in practice they will typically look as they do here.
12777 The key to correct translation of the typeset text is the definition of
12779 \begin_inset Flex Code
12782 \begin_layout Plain Layout
12791 \begin_inset Flex Code
12794 \begin_layout Plain Layout
12806 \begin_layout Standard
12808 \begin_inset Flex Code
12811 \begin_layout Plain Layout
12817 tag provides for internationalization based upon the overall language of
12819 The contents of the tag will be included in the preamble, just as with
12821 \begin_inset Flex Code
12824 \begin_layout Plain Layout
12831 What makes it special is the use of the
12832 \begin_inset Quotes eld
12836 \begin_inset Quotes erd
12840 \begin_inset Flex Code
12843 \begin_layout Plain Layout
12849 , which will be replaced, when LyX produces LaTeX output, with the translation
12850 of its argument into the document language.
12853 \begin_layout Standard
12855 \begin_inset Flex Code
12858 \begin_layout Plain Layout
12864 tag is more complex, since it is meant to provide support for multi-language
12865 documents and so offers an interface to the
12866 \begin_inset Flex Code
12869 \begin_layout Plain Layout
12876 Its contents will be added to the preamble once for each language that
12877 appears in the document.
12878 In this case, the argument to
12879 \begin_inset Flex Code
12882 \begin_layout Plain Layout
12888 will be replaced with its translation into the language in question; the
12890 \begin_inset Flex Code
12893 \begin_layout Plain Layout
12899 is replaced by the language name (as used by the babel package).
12902 \begin_layout Standard
12903 A German document that also included a French section would thus have the
12904 following in the preamble:
12907 \begin_layout LyX-Code
12916 claimname}{Affirmation}}
12924 claimname}{Behauptung}}
12928 claimname}{Behauptung}
12931 \begin_layout Standard
12933 \begin_inset Flex Code
12936 \begin_layout Plain Layout
12942 will then conspire to produce the correct text in the output.
12945 \begin_layout Standard
12946 One important point to note here is that the translations are provided by
12947 LyX itself, through the same mechanism it uses for internationalization
12948 of the user interface.
12949 This means, in effect, that
12950 \begin_inset Flex Code
12953 \begin_layout Plain Layout
12960 \begin_inset Flex Code
12963 \begin_layout Plain Layout
12969 are really only of use in layout files that are provided with LyX, since
12970 text entered in user-created layout files will not be seen by LyX's internation
12971 alization routines.
12972 That said, however, any layout created with the intention that it will
12973 be included with LyX should use these tags where appropriate.
12976 \begin_layout Subsection
12978 \begin_inset CommandInset label
12987 \begin_layout Standard
12988 Since version 1.3.0 of LyX, it is has been both possible and necessary to
12989 define the floats (
12990 \begin_inset Flex MenuItem
12993 \begin_layout Plain Layout
13000 \begin_inset Flex MenuItem
13003 \begin_layout Plain Layout
13009 , \SpecialChar \ldots{}
13010 ) in the text class itself.
13011 Standard floats are included in the file
13012 \begin_inset Flex Code
13015 \begin_layout Plain Layout
13021 , so you may have to do no more than add
13024 \begin_layout LyX-Code
13025 Input stdfloats.inc
13028 \begin_layout Standard
13029 to your layout file.
13030 If you want to implement a text class that proposes some other float types
13031 (like the AGU class bundled with LyX), the information below will hopefully
13035 \begin_layout Description
13036 \begin_inset Flex Code
13039 \begin_layout Plain Layout
13046 \begin_inset Flex Code
13049 \begin_layout Plain Layout
13056 \begin_inset Quotes erd
13060 \begin_inset Quotes erd
13063 ] The file name extension of an auxiliary file for the list of figures (or
13065 LaTeX writes the captions to this file.
13068 \begin_layout Description
13069 \begin_inset Flex Code
13072 \begin_layout Plain Layout
13079 \begin_inset Flex Code
13082 \begin_layout Plain Layout
13089 \begin_inset Quotes erd
13093 \begin_inset Quotes erd
13096 ] The string that will be used in the menus and also for the caption.
13097 This is translated to the current language if babel is used.
13100 \begin_layout Description
13101 \begin_inset Flex Code
13104 \begin_layout Plain Layout
13110 These are used for XHTML output.
13112 \begin_inset CommandInset ref
13114 reference "sec:Tags-for-XHTML"
13121 \begin_layout Description
13122 \begin_inset Flex Code
13125 \begin_layout Plain Layout
13134 \begin_inset Flex Code
13137 \begin_layout Plain Layout
13146 \begin_inset Flex Code
13149 \begin_layout Plain Layout
13155 ] Indicates whether the float is already defined in the document class or
13156 if we instead need to load
13157 \begin_inset Flex Code
13160 \begin_layout Plain Layout
13166 and use what it provides to define it on-the-fly.
13168 \begin_inset Flex Code
13171 \begin_layout Plain Layout
13178 \begin_inset Flex Code
13181 \begin_layout Plain Layout
13188 It should be set to
13189 \begin_inset Flex Code
13192 \begin_layout Plain Layout
13198 if the float is already defined by the LaTeX document class.
13201 \begin_layout Description
13202 \begin_inset Flex Code
13205 \begin_layout Plain Layout
13212 \begin_inset Flex Code
13215 \begin_layout Plain Layout
13222 \begin_inset Quotes erd
13226 \begin_inset Quotes erd
13229 ] The command used to generate a list of floats of this type; the leading
13232 ' should be omitted.
13238 \begin_inset Flex Code
13241 \begin_layout Plain Layout
13247 is false, since there is no standard way to generate this command.
13249 \begin_inset Flex Code
13252 \begin_layout Plain Layout
13258 is true, since in that case there is a standard way to define the command.
13261 \begin_layout Description
13262 \begin_inset Flex Code
13265 \begin_layout Plain Layout
13272 \begin_inset Flex Code
13275 \begin_layout Plain Layout
13282 \begin_inset Quotes erd
13286 \begin_inset Quotes erd
13289 ] A title for a list of floats of this kind (list of figures, tables, or
13291 It is used for the screen label within LyX; it is passed to LaTeX for use
13292 as the title there; and it is used as the title in XHTML output.
13293 It will be translated to the document language.
13296 \begin_layout Description
13297 \begin_inset Flex Code
13300 \begin_layout Plain Layout
13307 \begin_inset Flex Code
13310 \begin_layout Plain Layout
13317 \begin_inset Quotes erd
13321 \begin_inset Quotes erd
13324 ] This (optional) argument determines whether floats of this class will
13325 be numbered within some sectional unit of the document.
13326 For example, if within is equal to
13327 \begin_inset Flex Code
13330 \begin_layout Plain Layout
13336 , the floats will be numbered within chapters.
13340 \begin_layout Description
13341 \begin_inset Flex Code
13344 \begin_layout Plain Layout
13351 \begin_inset Flex Code
13354 \begin_layout Plain Layout
13361 \begin_inset Quotes erd
13365 \begin_inset Quotes erd
13368 ] The default placement for the given class of floats.
13369 The string should be as in standard LaTeX:
13370 \begin_inset Flex Code
13373 \begin_layout Plain Layout
13380 \begin_inset Flex Code
13383 \begin_layout Plain Layout
13390 \begin_inset Flex Code
13393 \begin_layout Plain Layout
13400 \begin_inset Flex Code
13403 \begin_layout Plain Layout
13409 for top, bottom, page, and here, respectively.
13413 \begin_layout Plain Layout
13414 Note that the order of these letters in the string is irrelevant, like in
13420 On top of that there is a new type,
13421 \begin_inset Flex Code
13424 \begin_layout Plain Layout
13430 , which does not really correspond to a float, since it means: put it
13431 \begin_inset Quotes eld
13435 \begin_inset Quotes erd
13439 Note however that the
13440 \begin_inset Flex Code
13443 \begin_layout Plain Layout
13449 specifier is special and, because of implementation details, cannot be
13450 used in non-built in float types.
13451 If you do not understand what this means, just use
13452 \begin_inset Quotes eld
13456 \begin_inset Flex Code
13459 \begin_layout Plain Layout
13466 \begin_inset Quotes erd
13472 \begin_layout Description
13473 \begin_inset Flex Code
13476 \begin_layout Plain Layout
13483 \begin_inset Flex Code
13486 \begin_layout Plain Layout
13492 ] The prefix to use when creating labels referring to floats of this type.
13493 This allows the use of formatted references.
13494 Note that you can remove any
13495 \begin_inset Flex Code
13498 \begin_layout Plain Layout
13504 set by a copied style by using the special value
13505 \begin_inset Quotes eld
13509 \begin_inset Quotes erd
13512 , which must be all caps.
13515 \begin_layout Description
13516 \begin_inset Flex Code
13519 \begin_layout Plain Layout
13526 \begin_inset Flex Code
13529 \begin_layout Plain Layout
13536 \begin_inset Quotes erd
13540 \begin_inset Quotes erd
13543 ] The style used when defining the float using
13544 \begin_inset Flex Code
13547 \begin_layout Plain Layout
13558 \begin_layout Description
13559 \begin_inset Flex Code
13562 \begin_layout Plain Layout
13569 \begin_inset Flex Code
13572 \begin_layout Plain Layout
13579 \begin_inset Quotes erd
13583 \begin_inset Quotes erd
13587 \begin_inset Quotes eld
13591 \begin_inset Quotes erd
13594 of the new class of floats, like program or algorithm.
13595 After the appropriate
13596 \begin_inset Flex Code
13599 \begin_layout Plain Layout
13608 \begin_inset Flex Code
13611 \begin_layout Plain Layout
13620 \begin_inset Flex Code
13623 \begin_layout Plain Layout
13634 \begin_layout Description
13635 \begin_inset Flex Code
13638 \begin_layout Plain Layout
13645 \begin_inset Flex Code
13648 \begin_layout Plain Layout
13655 \begin_inset Flex Code
13658 \begin_layout Plain Layout
13666 ] Tells us whether this float is defined using the facilities provided by
13668 \begin_inset Flex Code
13671 \begin_layout Plain Layout
13677 , either by the class file or a package, or on-the-fly by LyX itself.
13680 \begin_layout Standard
13681 Note that defining a float with type
13682 \begin_inset Flex Code
13685 \begin_layout Plain Layout
13693 automatically defines the corresponding counter with name
13694 \begin_inset Flex Code
13697 \begin_layout Plain Layout
13708 \begin_layout Subsection
13709 Flex insets and InsetLayout
13710 \begin_inset CommandInset label
13712 name "sub:Flex-insets-and"
13719 \begin_layout Standard
13720 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
13721 these are called Flex insets.
13725 \begin_layout Standard
13726 Flex insets come in three different kinds:
13729 \begin_layout Itemize
13731 \begin_inset Flex Code
13734 \begin_layout Plain Layout
13740 ): These define semantic markup corresponding to such LaTeX commands as
13742 \begin_inset Flex Code
13745 \begin_layout Plain Layout
13754 \begin_inset Flex Code
13757 \begin_layout Plain Layout
13768 \begin_layout Itemize
13770 \begin_inset Flex Code
13773 \begin_layout Plain Layout
13779 ): These can be used to define custom collapsible insets, similar to TeX
13780 code, footnote, and the like.
13781 An obvious example is an endnote inset, which is defined in the
13782 \begin_inset Flex Code
13785 \begin_layout Plain Layout
13794 \begin_layout Itemize
13796 \begin_inset Flex Code
13799 \begin_layout Plain Layout
13805 ): For use with DocBook classes.
13808 \begin_layout Standard
13809 Flex insets are defined using the
13810 \begin_inset Flex Code
13813 \begin_layout Plain Layout
13819 tag, which shall be explained in a moment.
13822 \begin_layout Standard
13824 \begin_inset Flex Code
13827 \begin_layout Plain Layout
13833 tag also serves another function: It can be used to customize the general
13834 layout of many different types of insets.
13836 \begin_inset Flex Code
13839 \begin_layout Plain Layout
13845 can be used to customize the layout parameters for footnotes, marginal
13846 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
13847 boxes, tables, algorithms, URLs, and optional arguments, as well as to
13848 define Flex insets.
13851 \begin_layout Standard
13853 \begin_inset Flex Code
13856 \begin_layout Plain Layout
13862 definition must begin with a line of the form:
13865 \begin_layout LyX-Code
13869 \begin_layout Standard
13871 \begin_inset Flex Code
13874 \begin_layout Plain Layout
13880 indicates the inset whose layout is being defined, and here there are two
13884 \begin_layout Enumerate
13885 The layout for a pre-existing inset is being modified.
13886 In this case, can be
13887 \begin_inset Flex Code
13890 \begin_layout Plain Layout
13896 any one of the following:
13897 \begin_inset Flex Code
13900 \begin_layout Plain Layout
13907 \begin_inset Flex Code
13910 \begin_layout Plain Layout
13917 \begin_inset Flex Code
13920 \begin_layout Plain Layout
13927 \begin_inset Flex Code
13930 \begin_layout Plain Layout
13937 \begin_inset Flex Code
13940 \begin_layout Plain Layout
13947 \begin_inset Flex Code
13950 \begin_layout Plain Layout
13957 \begin_inset Flex Code
13960 \begin_layout Plain Layout
13967 \begin_inset Flex Code
13970 \begin_layout Plain Layout
13977 \begin_inset Flex Code
13980 \begin_layout Plain Layout
13987 \begin_inset Flex Code
13990 \begin_layout Plain Layout
13997 \begin_inset Flex Code
14000 \begin_layout Plain Layout
14007 \begin_inset Flex Code
14010 \begin_layout Plain Layout
14017 \begin_inset Flex Code
14020 \begin_layout Plain Layout
14027 \begin_inset Flex Code
14030 \begin_layout Plain Layout
14037 \begin_inset Flex Code
14040 \begin_layout Plain Layout
14047 \begin_inset Flex Code
14050 \begin_layout Plain Layout
14057 \begin_inset Flex Code
14060 \begin_layout Plain Layout
14067 \begin_inset Flex Code
14070 \begin_layout Plain Layout
14077 \begin_inset Flex Code
14080 \begin_layout Plain Layout
14087 \begin_inset Flex Code
14090 \begin_layout Plain Layout
14099 \begin_layout Enumerate
14100 The layout for a Flex inset is being defined.
14102 \begin_inset Flex Code
14105 \begin_layout Plain Layout
14111 must be of the form
14112 \begin_inset Quotes eld
14116 \begin_inset Flex Code
14119 \begin_layout Plain Layout
14126 \begin_inset Quotes erd
14130 \begin_inset Flex Code
14133 \begin_layout Plain Layout
14139 may be be any valid identifier not used by a pre-existing Flex inset.
14140 The identifier may include spaces, but in that case the whole thing must
14141 be wrapped in quotes.
14142 Note that the definition of a flex inset
14147 \begin_inset Flex Code
14150 \begin_layout Plain Layout
14156 entry, declaring which type of inset it defines.
14159 \begin_layout Standard
14161 \begin_inset Flex Code
14164 \begin_layout Plain Layout
14170 definition can contain the following entries:
14173 \begin_layout Description
14174 \begin_inset Flex Code
14177 \begin_layout Plain Layout
14183 The color for the inset's background.
14184 The valid colors are defined in
14185 \begin_inset Flex Code
14188 \begin_layout Plain Layout
14197 \begin_layout Description
14198 \begin_inset Flex Code
14201 \begin_layout Plain Layout
14208 \begin_inset Flex Code
14211 \begin_layout Plain Layout
14220 \begin_inset Flex Code
14223 \begin_layout Plain Layout
14229 ] Whether to use the content of the inset as the label, when the inset is
14234 \begin_layout Description
14235 \begin_inset Flex Code
14238 \begin_layout Plain Layout
14244 As with paragraph styles (see page
14245 \begin_inset CommandInset ref
14247 reference "des:CopyStyle"
14254 \begin_layout Description
14255 \begin_inset Flex Code
14258 \begin_layout Plain Layout
14265 \begin_inset Flex Code
14268 \begin_layout Plain Layout
14277 \begin_inset Flex Code
14280 \begin_layout Plain Layout
14286 ] Indicates whether the user may employ the Paragraph Settings dialog to
14287 customize the paragraph.
14290 \begin_layout Description
14291 \begin_inset Flex Code
14294 \begin_layout Plain Layout
14301 \begin_inset Flex Code
14304 \begin_layout Plain Layout
14311 \begin_inset Flex Code
14314 \begin_layout Plain Layout
14321 \begin_inset Flex Code
14324 \begin_layout Plain Layout
14330 , describing the rendering style used for the inset's frame and buttons.
14331 Footnotes generally use
14332 \begin_inset Flex Code
14335 \begin_layout Plain Layout
14341 , ERT insets generally
14342 \begin_inset Flex Code
14345 \begin_layout Plain Layout
14351 , and character styles
14352 \begin_inset Flex Code
14355 \begin_layout Plain Layout
14364 \begin_layout Description
14365 \begin_inset Flex Code
14368 \begin_layout Plain Layout
14375 \begin_inset Flex Code
14378 \begin_layout Plain Layout
14385 \begin_inset Flex Code
14388 \begin_layout Plain Layout
14397 \begin_inset Flex Code
14400 \begin_layout Plain Layout
14407 \begin_inset Flex Code
14410 \begin_layout Plain Layout
14417 Indicates whether the environment will stand on its own in LaTeX output
14418 or will appear inline with the surrounding text.
14419 If set to false, it is supposed that the LaTeX environment ignores white
14420 space (including one newline character) after the
14421 \begin_inset Flex Code
14424 \begin_layout Plain Layout
14437 \begin_inset Flex Code
14440 \begin_layout Plain Layout
14456 \begin_layout Description
14457 \begin_inset Flex Code
14460 \begin_layout Plain Layout
14466 Required at the end of the InsetLayout declarations.
14469 \begin_layout Description
14470 \begin_inset Flex Code
14473 \begin_layout Plain Layout
14479 The font used for both the text body
14485 \begin_inset space ~
14489 \begin_inset CommandInset ref
14491 reference "sub:Font-description"
14496 Note that defining this font automatically defines the
14497 \begin_inset Flex Code
14500 \begin_layout Plain Layout
14506 to the same value, so define this first and define
14507 \begin_inset Flex Code
14510 \begin_layout Plain Layout
14516 later if you want them to be different.
14519 \begin_layout Description
14520 \begin_inset Flex Code
14523 \begin_layout Plain Layout
14530 \begin_inset Quotes eld
14534 \begin_inset Quotes erd
14537 language, leading to Left-to-Right (latin) output, e.
14538 \begin_inset space \thinspace{}
14542 \begin_inset space \space{}
14545 in TeX code or URL.
14549 \begin_layout Description
14550 \begin_inset Flex Code
14553 \begin_layout Plain Layout
14560 \begin_inset Flex Code
14563 \begin_layout Plain Layout
14572 \begin_inset Flex Code
14575 \begin_layout Plain Layout
14581 ] Indicates whether the
14582 \begin_inset Flex Code
14585 \begin_layout Plain Layout
14591 should be used or, instead, the user can change the paragraph style used
14596 \begin_layout Description
14597 \begin_inset Flex Code
14600 \begin_layout Plain Layout
14606 As with paragraph styles (see page
14607 \begin_inset CommandInset ref
14608 LatexCommand pageref
14609 reference "des:FreeSpacing"
14617 \begin_layout Description
14618 \begin_inset Flex Code
14621 \begin_layout Plain Layout
14627 These tags control XHTML output.
14629 \begin_inset CommandInset ref
14631 reference "sec:Tags-for-XHTML"
14638 \begin_layout Description
14639 \begin_inset Flex Code
14642 \begin_layout Plain Layout
14649 \begin_inset Flex Code
14652 \begin_layout Plain Layout
14661 \begin_inset Flex Code
14664 \begin_layout Plain Layout
14670 ] Whether to include the contents of this inset in the strings generated
14671 for the `Outline' pane.
14672 One would not, for example, want the content of a footnote in a section
14673 header to be included in the TOC displayed in the outline, but one would
14674 normally want the content of a character style displayed.
14675 Default is false: not to include.
14678 \begin_layout Description
14679 \begin_inset Flex Code
14682 \begin_layout Plain Layout
14688 As with paragraph styles (see page
14689 \begin_inset CommandInset ref
14690 LatexCommand pageref
14691 reference "des:KeepEmpty"
14699 \begin_layout Description
14700 \begin_inset Flex Code
14703 \begin_layout Plain Layout
14709 The font used for the label.
14711 \begin_inset space ~
14715 \begin_inset CommandInset ref
14717 reference "sub:Font-description"
14722 Note that this definition can never appear before
14723 \begin_inset Flex Code
14726 \begin_layout Plain Layout
14732 , lest it be ineffective.
14735 \begin_layout Description
14736 \begin_inset Flex Code
14739 \begin_layout Plain Layout
14745 What will be displayed on the button or elsewhere as the inset label.
14747 \begin_inset Flex Code
14750 \begin_layout Plain Layout
14757 \begin_inset Flex Code
14760 \begin_layout Plain Layout
14766 ) modify this label on the fly.
14769 \begin_layout Description
14770 \begin_inset Flex Code
14773 \begin_layout Plain Layout
14779 The name of the corresponding LaTeX stuff.
14780 Either the environment or command name.
14783 \begin_layout Description
14784 \begin_inset Flex Code
14787 \begin_layout Plain Layout
14793 The optional parameter for the corresponding
14794 \begin_inset Flex Code
14797 \begin_layout Plain Layout
14803 stuff, including possible bracket pairs like
14804 \begin_inset Flex Code
14807 \begin_layout Plain Layout
14814 This parameter cannot be changed from within LyX.
14817 \begin_layout Description
14818 \begin_inset Flex Code
14821 \begin_layout Plain Layout
14827 As with paragraph styles (see page
14828 \begin_inset CommandInset ref
14829 LatexCommand pageref
14830 reference "des:LatexType"
14837 \begin_layout Description
14838 \begin_inset Flex Code
14841 \begin_layout Plain Layout
14848 \begin_inset Flex Code
14851 \begin_layout Plain Layout
14858 \begin_inset Flex Code
14861 \begin_layout Plain Layout
14868 \begin_inset Flex Code
14871 \begin_layout Plain Layout
14878 \begin_inset Flex Code
14881 \begin_layout Plain Layout
14887 (indicating a dummy definition ending definitions of charstyles, etc).
14888 This entry is required in and is only meaningful for Flex insets.
14889 Among other things, it determines on which menu this inset will appear.
14891 \begin_inset Flex Code
14894 \begin_layout Plain Layout
14901 \begin_inset Flex Code
14904 \begin_layout Plain Layout
14911 \begin_inset Flex Code
14914 \begin_layout Plain Layout
14922 \begin_inset Flex Code
14925 \begin_layout Plain Layout
14931 can be set to true for charstyle insets, if you wish, by setting it
14936 \begin_inset Flex Code
14939 \begin_layout Plain Layout
14948 \begin_layout Description
14949 \begin_inset Flex Code
14952 \begin_layout Plain Layout
14959 \begin_inset Flex Code
14962 \begin_layout Plain Layout
14971 \begin_inset Flex Code
14974 \begin_layout Plain Layout
14980 ] Whether multiple paragraphs are permitted in this inset.
14982 \begin_inset Flex Code
14985 \begin_layout Plain Layout
14991 to the same value and
14992 \begin_inset Flex Code
14995 \begin_layout Plain Layout
15001 to the opposite value.
15002 These can be reset to other values, if they are used
15007 \begin_inset Flex Code
15010 \begin_layout Plain Layout
15020 \begin_layout Description
15021 \begin_inset Flex Code
15024 \begin_layout Plain Layout
15031 \begin_inset Flex Code
15034 \begin_layout Plain Layout
15043 \begin_inset Flex Code
15046 \begin_layout Plain Layout
15052 ] Whether fragile commands in this inset should be
15053 \begin_inset Flex Code
15056 \begin_layout Plain Layout
15069 whether the command should itself be protected.) Default is false.
15072 \begin_layout Description
15073 \begin_inset Flex Code
15076 \begin_layout Plain Layout
15083 \begin_inset Flex Code
15086 \begin_layout Plain Layout
15095 \begin_inset Flex Code
15098 \begin_layout Plain Layout
15104 ] As with paragraph styles (see page
15105 \begin_inset CommandInset ref
15106 LatexCommand pageref
15107 reference "des:ParbreakIsNewline"
15115 \begin_layout Description
15116 \begin_inset Flex Code
15119 \begin_layout Plain Layout
15126 \begin_inset Flex Code
15129 \begin_layout Plain Layout
15138 \begin_inset Flex Code
15141 \begin_layout Plain Layout
15147 ] As with paragraph styles (see page
15148 \begin_inset CommandInset ref
15149 LatexCommand pageref
15150 reference "des:PassThru"
15158 \begin_layout Description
15159 \begin_inset Flex Code
15162 \begin_layout Plain Layout
15168 As with paragraph styles (see page
15169 \begin_inset CommandInset ref
15170 LatexCommand pageref
15171 reference "des:Preamble"
15178 \begin_layout Description
15179 \begin_inset Flex Code
15182 \begin_layout Plain Layout
15189 \begin_inset Flex Code
15192 \begin_layout Plain Layout
15198 ] The prefix to use when creating labels referring to insets of this type.
15199 This allows the use of formatted references.
15202 \begin_layout Description
15203 \begin_inset Flex Code
15206 \begin_layout Plain Layout
15213 \begin_inset Flex Code
15216 \begin_layout Plain Layout
15222 ] As with paragraph styles (see page
15223 \begin_inset CommandInset ref
15224 LatexCommand pageref
15225 reference "des:Requires"
15232 \begin_layout Description
15233 \begin_inset Flex Code
15236 \begin_layout Plain Layout
15243 \begin_inset Flex Code
15246 \begin_layout Plain Layout
15253 \begin_inset Flex Code
15256 \begin_layout Plain Layout
15264 ] Whether this inset should use the font of its surrounding environment
15266 Default is true: uses its own.
15269 \begin_layout Description
15270 \begin_inset Flex Code
15273 \begin_layout Plain Layout
15280 \begin_inset Flex Code
15283 \begin_layout Plain Layout
15290 \begin_inset Flex Code
15293 \begin_layout Plain Layout
15301 ] Spellcheck the contents of this inset.
15305 \begin_layout Subsection
15307 \begin_inset CommandInset label
15309 name "sub:Counters"
15316 \begin_layout Standard
15317 Since version 1.3.0 of LyX, it is both possible and necessary to define the
15319 \begin_inset Flex MenuItem
15322 \begin_layout Plain Layout
15329 \begin_inset Flex MenuItem
15332 \begin_layout Plain Layout
15338 , \SpecialChar \ldots{}
15339 ) in the text class itself.
15340 The standard counters are defined in the file
15341 \begin_inset Flex Code
15344 \begin_layout Plain Layout
15350 , so you may have to do no more than add
15353 \begin_layout LyX-Code
15354 Input stdcounters.inc
15357 \begin_layout Standard
15358 to your layout file to get them to work.
15359 But if you want to define custom counters, then you can do so.
15360 The counter declaration must begin with:
15363 \begin_layout LyX-Code
15364 Counter CounterName
15367 \begin_layout Standard
15369 \begin_inset Flex Code
15372 \begin_layout Plain Layout
15378 ' is replaced by the name of the counter.
15379 And it must end with
15380 \begin_inset Quotes eld
15384 \begin_inset Flex Code
15387 \begin_layout Plain Layout
15394 \begin_inset Quotes erd
15398 The following parameters can also be used:
15401 \begin_layout Description
15402 \begin_inset Flex Code
15405 \begin_layout Plain Layout
15412 \begin_inset Flex Code
15415 \begin_layout Plain Layout
15422 \begin_inset Quotes erd
15426 \begin_inset Quotes erd
15429 ] When defined, this string defines how the counter is displayed.
15430 Setting this value sets
15431 \begin_inset Flex Code
15434 \begin_layout Plain Layout
15435 LabelStringAppendix
15441 The following special constructs can be used in the string:
15445 \begin_layout Itemize
15446 \begin_inset Flex Code
15449 \begin_layout Plain Layout
15457 will be replaced by the expansion of the
15458 \begin_inset Flex Code
15461 \begin_layout Plain Layout
15468 \begin_inset Flex Code
15471 \begin_layout Plain Layout
15472 LabelStringAppendix
15478 \begin_inset Flex Code
15481 \begin_layout Plain Layout
15491 \begin_layout Itemize
15492 counter values can be expressed using LaTeX-like macros
15493 \begin_inset Flex Code
15496 \begin_layout Plain Layout
15513 \begin_inset Flex Code
15516 \begin_layout Plain Layout
15528 \begin_layout Plain Layout
15538 Actually, the situation is a bit more complicated: any
15557 other than those described below will produce arabic numerals.
15558 It would not be surprising to see this change in the future.
15564 \begin_inset Flex Code
15567 \begin_layout Plain Layout
15573 : 1, 2, 3,\SpecialChar \ldots{}
15575 \begin_inset Flex Code
15578 \begin_layout Plain Layout
15584 for lower-case letters: a, b, c, \SpecialChar \ldots{}
15586 \begin_inset Flex Code
15589 \begin_layout Plain Layout
15595 for upper-case letters: A, B, C, \SpecialChar \ldots{}
15597 \begin_inset Flex Code
15600 \begin_layout Plain Layout
15606 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
15608 \begin_inset Flex Code
15611 \begin_layout Plain Layout
15617 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
15619 \begin_inset Flex Code
15622 \begin_layout Plain Layout
15628 for hebrew numerals.
15632 \begin_layout Standard
15633 If LabelString is not defined, a default value is constructed as follows:
15634 if the counter has a master counter
15635 \begin_inset Flex Code
15638 \begin_layout Plain Layout
15645 \begin_inset Flex Code
15648 \begin_layout Plain Layout
15655 \begin_inset Flex Code
15658 \begin_layout Plain Layout
15668 is used; otherwise the string
15669 \begin_inset Flex Code
15672 \begin_layout Plain Layout
15683 \begin_layout Description
15684 \begin_inset Flex Code
15687 \begin_layout Plain Layout
15688 LabelStringAppendix
15694 \begin_inset Flex Code
15697 \begin_layout Plain Layout
15704 \begin_inset Quotes erd
15708 \begin_inset Quotes erd
15712 \begin_inset Flex Code
15715 \begin_layout Plain Layout
15721 , but for use in the Appendix.
15724 \begin_layout Description
15725 \begin_inset Flex Code
15728 \begin_layout Plain Layout
15735 \begin_inset Flex Code
15738 \begin_layout Plain Layout
15745 \begin_inset Quotes erd
15749 \begin_inset Quotes erd
15752 ] A format for use with formatted references to this counter.
15753 For example, one might want to have references to section numbers appear
15755 \begin_inset Quotes eld
15759 \begin_inset Quotes erd
15763 The string should contain
15764 \begin_inset Quotes eld
15768 \begin_inset Quotes erd
15772 This will be replaced by the counter number itself.
15773 So, for sections, it would be: Section ##.
15776 \begin_layout Description
15777 \begin_inset Flex Code
15780 \begin_layout Plain Layout
15787 \begin_inset Flex Code
15790 \begin_layout Plain Layout
15797 \begin_inset Quotes erd
15801 \begin_inset Quotes erd
15804 ] If this is set to the name of another counter, the present counter will
15805 be reset every time the other one is increased.
15807 \begin_inset Flex Code
15810 \begin_layout Plain Layout
15817 \begin_inset Flex Code
15820 \begin_layout Plain Layout
15829 \begin_layout Subsection
15831 \begin_inset CommandInset label
15833 name "sub:Font-description"
15840 \begin_layout Standard
15841 A font description looks like this:
15844 \begin_layout LyX-Code
15854 \begin_layout LyX-Code
15858 \begin_layout LyX-Code
15862 \begin_layout Standard
15863 The following commands are available:
15866 \begin_layout Description
15867 \begin_inset Flex Code
15870 \begin_layout Plain Layout
15877 \begin_inset Flex Code
15880 \begin_layout Plain Layout
15889 \begin_inset Flex Code
15892 \begin_layout Plain Layout
15899 \begin_inset Flex Code
15902 \begin_layout Plain Layout
15909 \begin_inset Flex Code
15912 \begin_layout Plain Layout
15919 \begin_inset Flex Code
15922 \begin_layout Plain Layout
15929 \begin_inset Flex Code
15932 \begin_layout Plain Layout
15939 \begin_inset Flex Code
15942 \begin_layout Plain Layout
15949 \begin_inset Flex Code
15952 \begin_layout Plain Layout
15959 \begin_inset Flex Code
15962 \begin_layout Plain Layout
15971 \begin_layout Description
15972 \begin_inset Flex Code
15975 \begin_layout Plain Layout
15982 \begin_inset Flex Code
15985 \begin_layout Plain Layout
15994 \begin_inset Flex Code
15997 \begin_layout Plain Layout
16004 \begin_inset Flex Code
16007 \begin_layout Plain Layout
16016 \begin_layout Description
16017 \begin_inset Flex Code
16020 \begin_layout Plain Layout
16027 \begin_inset Flex Code
16030 \begin_layout Plain Layout
16036 ] Valid arguments are:
16037 \begin_inset Flex Code
16040 \begin_layout Plain Layout
16047 \begin_inset Flex Code
16050 \begin_layout Plain Layout
16057 \begin_inset Flex Code
16060 \begin_layout Plain Layout
16067 \begin_inset Flex Code
16070 \begin_layout Plain Layout
16077 \begin_inset Flex Code
16080 \begin_layout Plain Layout
16087 \begin_inset Flex Code
16090 \begin_layout Plain Layout
16097 Each of these turns on or off the corresponding attribute.
16099 \begin_inset Flex Code
16102 \begin_layout Plain Layout
16108 turns on emphasis, and
16109 \begin_inset Flex Code
16112 \begin_layout Plain Layout
16120 \begin_inset Newline newline
16123 If the latter seems puzzling, remember that the font settings for the present
16124 context are generally inherited from the surrounding context.
16126 \begin_inset Flex Code
16129 \begin_layout Plain Layout
16135 would turn off the emphasis that was anyway in effect, say, in a theorem
16139 \begin_layout Description
16140 \begin_inset Flex Code
16143 \begin_layout Plain Layout
16150 \begin_inset Flex Code
16153 \begin_layout Plain Layout
16162 \begin_inset Flex Code
16165 \begin_layout Plain Layout
16174 \begin_layout Description
16175 \begin_inset Flex Code
16178 \begin_layout Plain Layout
16185 \begin_inset Flex Code
16188 \begin_layout Plain Layout
16197 \begin_inset Flex Code
16200 \begin_layout Plain Layout
16207 \begin_inset Flex Code
16210 \begin_layout Plain Layout
16217 \begin_inset Flex Code
16220 \begin_layout Plain Layout
16229 \begin_layout Description
16230 \begin_inset Flex Code
16233 \begin_layout Plain Layout
16240 \begin_inset Flex Code
16243 \begin_layout Plain Layout
16250 \begin_inset Flex Code
16253 \begin_layout Plain Layout
16260 \begin_inset Flex Code
16263 \begin_layout Plain Layout
16272 \begin_inset Flex Code
16275 \begin_layout Plain Layout
16282 \begin_inset Flex Code
16285 \begin_layout Plain Layout
16292 \begin_inset Flex Code
16295 \begin_layout Plain Layout
16302 \begin_inset Flex Code
16305 \begin_layout Plain Layout
16312 \begin_inset Flex Code
16315 \begin_layout Plain Layout
16324 \begin_layout Subsection
16325 \begin_inset CommandInset label
16327 name "sub:Citation-format-description"
16331 Citation format description
16334 \begin_layout Standard
16336 \begin_inset Flex Code
16339 \begin_layout Plain Layout
16345 blocks are used to describe how bibliographic information should be displayed,
16346 both within LyX itself (in the citation dialog and in tooltips, for example)
16347 and in XHTML output.
16348 Such a block might look like this:
16351 \begin_layout LyX-Code
16355 \begin_layout LyX-Code
16359 \begin_layout LyX-Code
16363 \begin_layout LyX-Code
16367 \begin_layout Standard
16368 The individual lines define how the bibliographic information associated
16369 with an article or book, respectively, is to be displayed, and such a definitio
16370 n can be given for any `entry type' that might be present in a BibTeX file.
16371 LyX defines a default format in the source code that will be used if no
16372 specific definition has been given.
16373 LyX predefines several formats in the file
16374 \begin_inset Flex Code
16377 \begin_layout Plain Layout
16383 , which is included in most of LyX's document classes.
16386 \begin_layout Standard
16387 The definitions use a simple language that allows BibTeX keys to be replaced
16389 Keys should be enclosed in
16390 \begin_inset Flex Code
16393 \begin_layout Plain Layout
16400 \begin_inset Flex Code
16403 \begin_layout Plain Layout
16410 So a simple definition might look like this:
16413 \begin_layout LyX-Code
16415 \begin_inset Quotes eld
16419 \begin_inset Quotes erd
16425 \begin_layout Standard
16426 This would print the author, followed by a comma, followed by the title,
16427 in quotes, followed by a period.
16430 \begin_layout Standard
16431 Of course, sometimes you may want to print a key only if it exists.
16432 This can be done by using a conditional construction, such as:
16433 \begin_inset Flex Code
16436 \begin_layout Plain Layout
16438 \begin_inset space ~
16448 \begin_inset Flex Code
16451 \begin_layout Plain Layout
16457 key exists, then print
16458 \begin_inset Quotes eld
16462 \begin_inset space ~
16466 \begin_inset Quotes erd
16469 followed by the volume key.
16470 It is also possible to have an else clause in the conditional, such as:
16472 \begin_inset Flex Code
16475 \begin_layout Plain Layout
16476 {%author%[[%author%]][[%editor%, ed.]]}
16483 \begin_inset Flex Code
16486 \begin_layout Plain Layout
16492 key is printed if it exists; otherwise, the editor key is printed, followed
16494 \begin_inset Quotes eld
16498 \begin_inset space ~
16502 \begin_inset Quotes erd
16505 Note that the key is again enclosed in
16506 \begin_inset Flex Code
16509 \begin_layout Plain Layout
16515 signs; the entire conditional is enclosed in braces; and the if and else
16516 clauses are enclosed in double brackets,
16517 \begin_inset Quotes eld
16521 \begin_inset Flex Code
16524 \begin_layout Plain Layout
16531 \begin_inset Quotes eld
16535 \begin_inset Quotes eld
16539 \begin_inset Flex Code
16542 \begin_layout Plain Layout
16549 \begin_inset Quotes erd
16553 There must be no space between any of these.
16556 \begin_layout Standard
16557 There is one other piece of syntax available in definitions, which looks
16559 \begin_inset Flex Code
16562 \begin_layout Plain Layout
16569 This defines a piece of formatting information that is to be used when
16571 \begin_inset Quotes eld
16575 \begin_inset Quotes erd
16579 Obviously, we do not want to output HTML tags when writing plain text,
16580 so they should be wrapped in
16581 \begin_inset Quotes eld
16585 \begin_inset Quotes erd
16589 \begin_inset Quotes eld
16593 \begin_inset Quotes erd
16599 \begin_layout Standard
16600 Two special sorts of definitions are also possible in a
16601 \begin_inset Flex Code
16604 \begin_layout Plain Layout
16611 An example of the first would be:
16614 \begin_layout LyX-Code
16616 \begin_inset Quotes eld
16620 \begin_inset Quotes erd
16626 \begin_layout Standard
16627 This is an abbreviation, or macro, and it can be used by treating it as
16629 \begin_inset Flex Code
16632 \begin_layout Plain Layout
16640 \begin_inset Flex Code
16643 \begin_layout Plain Layout
16649 exactly as it would treat its definition.
16650 So, let us issue the obvious
16658 \begin_layout LyX-Code
16662 \begin_layout Standard
16663 or anything like it.
16664 LyX shouldn't go into an infinite loop, but it may go into a long one before
16668 \begin_layout Standard
16669 The second sort of special definition might look like this:
16672 \begin_layout LyX-Code
16676 \begin_layout Standard
16677 This defines a translatable piece of text, which allows relevant parts of
16678 the bibliography to be translated.
16679 It can be included in a definition by treating it as a key:
16680 \begin_inset Flex Code
16683 \begin_layout Plain Layout
16690 Several of these are predefined in
16691 \begin_inset Flex Code
16694 \begin_layout Plain Layout
16701 Note that these are not macros, in the sense just defined.
16702 They will not be expanded.
16705 \begin_layout Standard
16706 So here then is an example that use all these features:
16709 \begin_layout LyX-Code
16710 !authoredit {%author%[[%author%, ]][[{%editor%[[%editor%, %_edtext%, ]]}]]}
16713 \begin_layout Standard
16714 This defines a macro that prints the author, followed by a comma, if the
16716 \begin_inset Flex Code
16719 \begin_layout Plain Layout
16725 key is defined, or else prints the name of the editor, followed by the
16727 \begin_inset Flex Code
16730 \begin_layout Plain Layout
16736 or its translation (it is by default
16737 \begin_inset Quotes eld
16741 \begin_inset Quotes erd
16745 \begin_inset Flex Code
16748 \begin_layout Plain Layout
16755 Note that this is in fact defined in
16756 \begin_inset Flex Code
16759 \begin_layout Plain Layout
16765 , so you can use it in your own definitions, or re-definitions, if you load
16769 \begin_layout Section
16770 \begin_inset CommandInset label
16772 name "sec:Tags-for-XHTML"
16776 Tags for XHTML output
16779 \begin_layout Standard
16780 As with LaTeX or DocBook, the format of LyX's XHTML output is also controlled
16781 by layout information.
16782 In general, LyX provides sensible defaults and, as mentioned earlier, it
16783 will even construct default CSS style rules from the other layout tags.
16784 For example, LyX will attempt to use the information provided in the
16785 \begin_inset Flex Code
16788 \begin_layout Plain Layout
16794 declaration for the Chapter style to write CSS that will appropriately
16795 format chapter headings.
16798 \begin_layout Standard
16799 In many cases, then, you may not have to do anything at all to get acceptable
16800 XHTML output for your own environments, custom insets, and so forth.
16801 But in some cases you will, and so LyX provides a number of layout tags
16802 that can be used to customize the XHTML and CSS that are generated.
16805 \begin_layout Standard
16806 Note that there are two tags,
16807 \begin_inset Flex Code
16810 \begin_layout Plain Layout
16817 \begin_inset Flex Code
16820 \begin_layout Plain Layout
16826 that may appear outside style and inset declarations.
16828 \begin_inset CommandInset ref
16830 reference "sub:General-text-class"
16834 for details on these.
16837 \begin_layout Subsection
16838 \begin_inset CommandInset label
16840 name "sub:Paragraph-Style-XHTML"
16847 \begin_layout Standard
16848 The sort of XHTML LyX outputs for a paragraph depends upon whether we are
16849 dealing with a normal paragraph, a command, or an environment, where this
16850 is itself determined by the contents of the corresponding
16851 \begin_inset Flex Code
16854 \begin_layout Plain Layout
16864 \begin_layout Standard
16865 For a command or normal paragraph, the output XHTML has the following form:
16868 \begin_layout LyX-Code
16870 \begin_inset Quotes erd
16874 \begin_inset Quotes erd
16880 \begin_layout LyX-Code
16882 \begin_inset Quotes erd
16886 \begin_inset Quotes erd
16892 \begin_layout LyX-Code
16893 Contents of the paragraph.
16896 \begin_layout LyX-Code
16900 \begin_layout Standard
16901 The label tags are of course omitted if the paragraph does not have a label.
16904 \begin_layout Standard
16905 For an environment that is not some sort of list, the XHTML takes this form:
16908 \begin_layout LyX-Code
16910 \begin_inset Quotes erd
16914 \begin_inset Quotes erd
16920 \begin_layout LyX-Code
16922 \begin_inset Quotes erd
16926 \begin_inset Quotes erd
16930 \begin_inset Quotes erd
16934 \begin_inset Quotes erd
16937 >Environment Label</labeltag>First paragraph.</itemtag>
16940 \begin_layout LyX-Code
16941 <itemtag>Second paragraph.</itemtag>
16944 \begin_layout LyX-Code
16948 \begin_layout Standard
16949 Note that the label is output only for the first paragraph, as it should
16950 be for a theorem, for example.
16954 \begin_layout Standard
16955 For a list, we have one of these forms:
16958 \begin_layout LyX-Code
16960 \begin_inset Quotes erd
16964 \begin_inset Quotes erd
16970 \begin_layout LyX-Code
16972 \begin_inset Quotes erd
16976 \begin_inset Quotes erd
16980 \begin_inset Quotes erd
16984 \begin_inset Quotes erd
16987 >List Label</labeltag>First item.</itemtag>
16990 \begin_layout LyX-Code
16992 \begin_inset Quotes erd
16996 \begin_inset Quotes erd
17000 \begin_inset Quotes erd
17004 \begin_inset Quotes erd
17007 >List Label</labeltag>Second item.</itemtag>
17010 \begin_layout LyX-Code
17014 \begin_layout LyX-Code
17018 \begin_layout LyX-Code
17020 \begin_inset Quotes erd
17024 \begin_inset Quotes erd
17030 \begin_layout LyX-Code
17032 \begin_inset Quotes erd
17036 \begin_inset Quotes erd
17039 >List Label</labeltag><itemtag attr=
17040 \begin_inset Quotes erd
17044 \begin_inset Quotes erd
17047 >First item.</itemtag>
17050 \begin_layout LyX-Code
17052 \begin_inset Quotes erd
17056 \begin_inset Quotes erd
17059 >List Label</labeltag><itemtag attr=
17060 \begin_inset Quotes erd
17064 \begin_inset Quotes erd
17067 >Second item.</itemtag>
17070 \begin_layout LyX-Code
17074 \begin_layout Standard
17075 Note the different orders of
17076 \begin_inset Flex Code
17079 \begin_layout Plain Layout
17086 \begin_inset Flex Code
17089 \begin_layout Plain Layout
17096 Which order we get depends upon the setting of
17097 \begin_inset Flex Code
17100 \begin_layout Plain Layout
17107 \begin_inset Flex Code
17110 \begin_layout Plain Layout
17116 is false (the default), you get the first of these, with the label within
17117 the item; if true, you get the second, with the label outside the item.
17120 \begin_layout Standard
17121 The specific tags and attributes output for each paragraph type can be controlle
17122 d by means of the layout tags we are about to describe.
17123 As mentioned earlier, however, LyX uses sensible defaults for many of these,
17124 so you often may not need to do very much to get good XHTML output.
17125 Think of the available tags as there so you can tweak things to your liking.
17128 \begin_layout Description
17129 \begin_inset Flex Code
17132 \begin_layout Plain Layout
17139 \begin_inset Flex Code
17142 \begin_layout Plain Layout
17148 ] Specifies attribute information to be output with the main tag.
17150 \begin_inset Quotes eld
17154 \begin_inset Flex Code
17157 \begin_layout Plain Layout
17164 \begin_inset Quotes erd
17168 By default, LyX will output
17169 \begin_inset Quotes eld
17173 \begin_inset Flex Code
17176 \begin_layout Plain Layout
17183 \begin_inset Quotes erd
17187 \begin_inset Flex Code
17190 \begin_layout Plain Layout
17196 is the LyX name of the layout, made lowercase, for example: chapter.
17201 contain any style information.
17203 \begin_inset Flex Code
17206 \begin_layout Plain Layout
17215 \begin_layout Description
17216 \begin_inset Flex Code
17219 \begin_layout Plain Layout
17226 \begin_inset Flex Code
17229 \begin_layout Plain Layout
17239 ] Whether to output the default CSS information LyX generates for this layout,
17240 even if additional information is explicitly provided via
17241 \begin_inset Flex Code
17244 \begin_layout Plain Layout
17252 \begin_inset Flex Code
17255 \begin_layout Plain Layout
17261 allows you to alter or augment the generated CSS, rather than to override
17264 \begin_inset Flex Code
17267 \begin_layout Plain Layout
17276 \begin_layout Description
17277 \begin_inset Flex Code
17280 \begin_layout Plain Layout
17287 \begin_inset Flex Code
17290 \begin_layout Plain Layout
17296 ] The tag to be used for individual paragraphs of environments, replacing
17298 \begin_inset Flex Code
17301 \begin_layout Plain Layout
17307 in the examples above.
17309 \begin_inset Flex Code
17312 \begin_layout Plain Layout
17321 \begin_layout Description
17322 \begin_inset Flex Code
17325 \begin_layout Plain Layout
17332 \begin_inset Flex Code
17335 \begin_layout Plain Layout
17341 ] Attributes for the item tag.
17343 \begin_inset Quotes eld
17347 \begin_inset Flex Code
17350 \begin_layout Plain Layout
17351 class=`layoutname_item'
17357 \begin_inset Quotes erd
17365 contain any style information.
17367 \begin_inset Flex Code
17370 \begin_layout Plain Layout
17379 \begin_layout Description
17380 \begin_inset Flex Code
17383 \begin_layout Plain Layout
17390 \begin_inset Flex Code
17393 \begin_layout Plain Layout
17399 ] The tag to be used for paragraph and item labels, replacing
17400 \begin_inset Flex Code
17403 \begin_layout Plain Layout
17409 in the examples above.
17411 \begin_inset Flex Code
17414 \begin_layout Plain Layout
17421 \begin_inset Flex Code
17424 \begin_layout Plain Layout
17431 \begin_inset Flex Code
17434 \begin_layout Plain Layout
17441 \begin_inset Flex Code
17444 \begin_layout Plain Layout
17445 Centered_Top_Environment
17450 , in which case it defaults to
17451 \begin_inset Flex Code
17454 \begin_layout Plain Layout
17463 \begin_layout Description
17464 \begin_inset Flex Code
17467 \begin_layout Plain Layout
17474 \begin_inset Flex Code
17477 \begin_layout Plain Layout
17483 ] Attributes for the label tag.
17485 \begin_inset Quotes eld
17489 \begin_inset Flex Code
17492 \begin_layout Plain Layout
17493 class=`layoutname_label'
17499 \begin_inset Quotes erd
17507 contain any style information.
17509 \begin_inset Flex Code
17512 \begin_layout Plain Layout
17521 \begin_layout Description
17522 \begin_inset Flex Code
17525 \begin_layout Plain Layout
17532 \begin_inset Flex Code
17535 \begin_layout Plain Layout
17545 ] Meaningful only for list-like environments, this tag controls whether
17546 the label tag is output before or inside the item tag.
17547 This is used, for example, in the description environment, where we want
17549 \begin_inset Flex Code
17552 \begin_layout Plain Layout
17553 <dt>\SpecialChar \ldots{}
17554 </dt><dd>\SpecialChar \ldots{}
17562 \begin_inset Flex Code
17565 \begin_layout Plain Layout
17571 : The label tag is output inside the item tag.
17574 \begin_layout Description
17575 \begin_inset Flex Code
17578 \begin_layout Plain Layout
17584 Information to be output in the
17585 \begin_inset Flex Code
17588 \begin_layout Plain Layout
17594 section when this style is used.
17595 This might, for example, be used to include a
17596 \begin_inset Flex Code
17599 \begin_layout Plain Layout
17606 \begin_inset Flex Code
17609 \begin_layout Plain Layout
17618 \begin_layout Description
17619 \begin_inset Flex Code
17622 \begin_layout Plain Layout
17628 CSS style information to be included when this style is used.
17629 Note that this will automatically be wrapped in a layout-generated
17630 \begin_inset Flex Code
17633 \begin_layout Plain Layout
17639 block, so only the CSS itself need be included.
17642 \begin_layout Description
17643 \begin_inset Flex Code
17646 \begin_layout Plain Layout
17653 \begin_inset Flex Code
17656 \begin_layout Plain Layout
17662 ] The tag to be used for the main label, replacing
17663 \begin_inset Flex Code
17666 \begin_layout Plain Layout
17672 in the examples above.
17674 \begin_inset Flex Code
17677 \begin_layout Plain Layout
17686 \begin_layout Description
17687 \begin_inset Flex Code
17690 \begin_layout Plain Layout
17697 \begin_inset Flex Code
17700 \begin_layout Plain Layout
17710 ] Marks this style as the one to be used to generate the
17711 \begin_inset Flex Code
17714 \begin_layout Plain Layout
17720 tag for the XHTML file.
17721 By default, it is false.
17723 \begin_inset Flex Code
17726 \begin_layout Plain Layout
17732 file sets it to true for the
17733 \begin_inset Flex Code
17736 \begin_layout Plain Layout
17746 \begin_layout Subsection
17750 \begin_layout Standard
17751 The XHTML output of insets can also be controlled by information in layout
17756 \begin_layout Plain Layout
17757 At present, this is true only for
17758 \begin_inset Quotes eld
17762 \begin_inset Quotes erd
17765 insets (insets you can type into) and is not true for
17766 \begin_inset Quotes eld
17770 \begin_inset Quotes erd
17773 insets (insets that are associated with dialog boxes).
17778 Here, too, LyX tries to provide sensible defaults, and it constructs default
17780 But everything can be customized.
17783 \begin_layout Standard
17784 The XHTML LyX outputs for an inset has the following form:
17787 \begin_layout LyX-Code
17789 \begin_inset Quotes erd
17793 \begin_inset Quotes erd
17799 \begin_layout LyX-Code
17800 <labeltag>Label</labeltag>
17803 \begin_layout LyX-Code
17805 \begin_inset Quotes erd
17809 \begin_inset Quotes erd
17812 >Contents of the inset.</innertag>
17815 \begin_layout LyX-Code
17819 \begin_layout Standard
17820 If the inset permits multiple paragraphs---that is, if
17821 \begin_inset Flex Code
17824 \begin_layout Plain Layout
17830 is true---then the contents of the inset will itself be output as paragraphs
17831 formatted according to the styles used for those paragraphs (standard,
17832 quote, and the like).
17833 The label tag is of course omitted if the paragraph does not have a label
17834 and, at present, is always
17835 \begin_inset Flex Code
17838 \begin_layout Plain Layout
17845 The inner tag is optional and, by default, does not appear.
17848 \begin_layout Standard
17849 The specific tags and attributes output for each inset can be controlled
17850 by means of the following layout tags.
17853 \begin_layout Description
17854 \begin_inset Flex Code
17857 \begin_layout Plain Layout
17864 \begin_inset Flex Code
17867 \begin_layout Plain Layout
17873 ] Specifies attribute information to be output with the main tag.
17875 \begin_inset Quotes eld
17879 \begin_inset Flex Code
17882 \begin_layout Plain Layout
17883 class=`myinset' onclick=`\SpecialChar \ldots{}
17890 \begin_inset Quotes erd
17894 By default, LyX will output
17895 \begin_inset Quotes eld
17899 \begin_inset Flex Code
17902 \begin_layout Plain Layout
17909 \begin_inset Quotes erd
17913 \begin_inset Flex Code
17916 \begin_layout Plain Layout
17922 is the LyX name of the inset, made lowercase and with non-alphanumeric
17923 characters converted to underscores, for example: footnote.
17926 \begin_layout Description
17927 \begin_inset Flex Code
17930 \begin_layout Plain Layout
17937 \begin_inset Flex Code
17940 \begin_layout Plain Layout
17950 ] Whether to output the default CSS information LyX generates for this layout,
17951 even if additional information is explicitly provided via
17952 \begin_inset Flex Code
17955 \begin_layout Plain Layout
17963 \begin_inset Flex Code
17966 \begin_layout Plain Layout
17972 allows you to alter or augment the generated CSS, rather than to override
17977 \begin_layout Description
17978 \begin_inset Flex Code
17981 \begin_layout Plain Layout
17988 \begin_inset Flex Code
17991 \begin_layout Plain Layout
17997 ] Attributes for the inner tag.
17999 \begin_inset Quotes eld
18003 \begin_inset Flex Code
18006 \begin_layout Plain Layout
18007 class=`insetname_inner'
18013 \begin_inset Quotes erd
18019 \begin_layout Description
18020 \begin_inset Flex Code
18023 \begin_layout Plain Layout
18030 \begin_inset Flex Code
18033 \begin_layout Plain Layout
18039 ] The inner tag, replacing
18040 \begin_inset Flex Code
18043 \begin_layout Plain Layout
18049 in the examples above.
18050 By default, there is none.
18053 \begin_layout Description
18054 \begin_inset Flex Code
18057 \begin_layout Plain Layout
18064 \begin_inset Flex Code
18067 \begin_layout Plain Layout
18075 ] Whether this inset represents a standalone block of text (such as a footnote)
18076 or instead represents material that is included in the surrounding text
18077 (such as a branch).
18081 \begin_layout Description
18082 \begin_inset Flex Code
18085 \begin_layout Plain Layout
18092 \begin_inset Flex Code
18095 \begin_layout Plain Layout
18101 ] A label for this inset, possibly including a reference to a counter.
18102 For example, for footnote, it might be:
18103 \begin_inset Flex Code
18106 \begin_layout Plain Layout
18115 This is optional, and there is no default.
18118 \begin_layout Description
18119 \begin_inset Flex Code
18122 \begin_layout Plain Layout
18128 Information to be output in the
18129 \begin_inset Flex Code
18132 \begin_layout Plain Layout
18138 section when this style is used.
18139 This might, for example, be used to include a
18140 \begin_inset Flex Code
18143 \begin_layout Plain Layout
18150 \begin_inset Flex Code
18153 \begin_layout Plain Layout
18162 \begin_layout Description
18163 \begin_inset Flex Code
18166 \begin_layout Plain Layout
18172 CSS style information to be included when this style is used.
18173 Note that this will automatically be wrapped in a layout-generated
18174 \begin_inset Flex Code
18177 \begin_layout Plain Layout
18183 block, so only the CSS itself need be included.
18186 \begin_layout Description
18187 \begin_inset Flex Code
18190 \begin_layout Plain Layout
18197 \begin_inset Flex Code
18200 \begin_layout Plain Layout
18206 ] The tag to be used for the main label, replacing
18207 \begin_inset Flex Code
18210 \begin_layout Plain Layout
18216 in the examples above.
18217 The default depends upon the setting of
18218 \begin_inset Flex Code
18221 \begin_layout Plain Layout
18228 \begin_inset Flex Code
18231 \begin_layout Plain Layout
18237 is true, the default is
18238 \begin_inset Flex Code
18241 \begin_layout Plain Layout
18247 ; if it is false, the default is
18248 \begin_inset Flex Code
18251 \begin_layout Plain Layout
18260 \begin_layout Subsection
18264 \begin_layout Standard
18265 The XHTML output for floats too can be controlled by layout information.
18266 The output has the following form:
18269 \begin_layout LyX-Code
18271 \begin_inset Quotes erd
18275 \begin_inset Quotes erd
18281 \begin_layout LyX-Code
18282 Contents of the float.
18285 \begin_layout LyX-Code
18289 \begin_layout Standard
18290 The caption, if there is one, is a separate inset and will be output as
18292 Its appearance can be controlled via the InsetLayout for caption insets.
18296 \begin_layout Description
18297 \begin_inset Flex Code
18300 \begin_layout Plain Layout
18307 \begin_inset Flex Code
18310 \begin_layout Plain Layout
18316 ] Specifies attribute information to be output with the main tag.
18318 \begin_inset Quotes eld
18322 \begin_inset Flex Code
18325 \begin_layout Plain Layout
18326 class=`myfloat' onclick=`\SpecialChar \ldots{}
18333 \begin_inset Quotes erd
18337 By default, LyX will output
18338 \begin_inset Quotes eld
18342 \begin_inset Flex Code
18345 \begin_layout Plain Layout
18346 class=`float float-floattype'
18352 \begin_inset Quotes erd
18356 \begin_inset Flex Code
18359 \begin_layout Plain Layout
18365 is LyX's name for this type of float, as determined by the float declaration
18367 \begin_inset CommandInset ref
18369 reference "sub:Floats"
18373 ), though made lowercase and with non-alphanumeric characters converted
18374 to underscores, for example: float-table.
18377 \begin_layout Description
18378 \begin_inset Flex Code
18381 \begin_layout Plain Layout
18387 CSS style information to be included when this float is used.
18388 Note that this will automatically be wrapped in a layout-generated
18389 \begin_inset Flex Code
18392 \begin_layout Plain Layout
18398 block, so only the CSS itself need be included.
18401 \begin_layout Description
18402 \begin_inset Flex Code
18405 \begin_layout Plain Layout
18412 \begin_inset Flex Code
18415 \begin_layout Plain Layout
18421 ] The tag to be used for this float, replacing
18422 \begin_inset Quotes eld
18426 \begin_inset Flex Code
18429 \begin_layout Plain Layout
18436 \begin_inset Quotes erd
18439 in the example above.
18441 \begin_inset Flex Code
18444 \begin_layout Plain Layout
18450 and will rarely need changing.
18453 \begin_layout Subsection
18454 Bibliography formatting
18457 \begin_layout Standard
18458 The bibliography can be formatted using
18459 \begin_inset Flex Code
18462 \begin_layout Plain Layout
18470 \begin_inset CommandInset ref
18472 reference "sub:Citation-format-description"
18479 \begin_layout Subsection
18483 \begin_layout Standard
18484 We have several times mentioned that LyX will generate default CSS style
18485 rules for both insets and paragraph styles, based upon the other layout
18486 information that is provided.
18487 In this section, we shall say a word about which layout information LyX
18491 \begin_layout Standard
18492 At present, LyX auto-generates CSS only for font information, making use
18494 \begin_inset Flex Code
18497 \begin_layout Plain Layout
18504 \begin_inset Flex Code
18507 \begin_layout Plain Layout
18514 \begin_inset Flex Code
18517 \begin_layout Plain Layout
18524 \begin_inset Flex Code
18527 \begin_layout Plain Layout
18534 \begin_inset Flex Code
18537 \begin_layout Plain Layout
18545 \begin_inset CommandInset ref
18547 reference "sub:Font-description"
18551 .) The translation is mostly straightforward and obvious.
18553 \begin_inset Quotes eld
18557 \begin_inset Flex Code
18560 \begin_layout Plain Layout
18567 \begin_inset Quotes erd
18571 \begin_inset Quotes eld
18575 \begin_inset Flex Code
18578 \begin_layout Plain Layout
18579 font-family: sans-serif;
18585 \begin_inset Quotes erd
18589 The correspondence of LyX sizes and CSS sizes is a little less obvious
18590 but nonetheless intuitive.
18592 \begin_inset Flex Code
18595 \begin_layout Plain Layout
18602 \begin_inset Flex URL
18605 \begin_layout Plain Layout
18616 \begin_layout Chapter
18617 Including External Material
18620 \begin_layout Standard
18621 \begin_inset Box Shadowbox
18631 height_special "totalheight"
18634 \begin_layout Plain Layout
18635 WARNING: This portion of the documentation has not been updated for some
18637 We certainly hope that it is still accurate, but there are no guarantees.
18645 \begin_layout Standard
18646 The use of material from sources external to LyX is covered in detail in
18652 This part of the manual covers what needs to happen behind the scenes for
18653 new sorts of material to be included.
18656 \begin_layout Section
18660 \begin_layout Standard
18661 The external material feature is based on the concept of a
18666 A template is a specification of how LyX should interface with a certain
18668 As bundled, LyX comes with predefined templates for Xfig figures, various
18669 raster format images, chess diagrams, and LilyPond music notation.
18670 You can check the actual list by using the menu
18671 \begin_inset Flex MenuItem
18674 \begin_layout Plain Layout
18675 Insert\SpecialChar \menuseparator
18676 File\SpecialChar \menuseparator
18683 Furthermore, it is possible to roll your own template to support a specific
18685 Later we'll describe in more detail what is involved, and hopefully you
18686 will submit all the templates you create so we can include them in a later
18690 \begin_layout Standard
18691 Another basic idea of the external material feature is to distinguish between
18692 the original file that serves as a base for final material and the produced
18693 file that is included in your exported or printed document.
18694 For example, consider the case of a figure produced with
18695 \begin_inset Flex Code
18698 \begin_layout Plain Layout
18705 The Xfig application itself works on an original file with the
18706 \begin_inset Flex Code
18709 \begin_layout Plain Layout
18716 Within Xfig, you create and change your figure, and when you are done,
18718 \begin_inset Flex Code
18721 \begin_layout Plain Layout
18728 When you want to include the figure in your document, you invoke
18729 \begin_inset Flex Code
18732 \begin_layout Plain Layout
18738 in order to create a PostScript file that can readily be included in your
18741 \begin_inset Flex Code
18744 \begin_layout Plain Layout
18750 file is the original file, and the PostScript file is the produced file.
18753 \begin_layout Standard
18754 This distinction is important in order to allow updating of the material
18755 while you are in the process of writing the document.
18756 Furthermore, it provides us with the flexibility that is needed to support
18757 multiple export formats.
18758 For instance, in the case of a plain text file, it is not exactly an award-winn
18759 ing idea to include the figure as raw PostScript.
18760 Instead, you'd either prefer to just include a reference to the figure
18761 or try to invoke some graphics to ASCII converter to make the final result
18762 look similar to the real graphics.
18763 The external material management allows you to do this, because it is parametri
18764 zed on the different export formats that LyX supports.
18767 \begin_layout Standard
18768 Besides supporting the production of different products according to the
18769 exported format, it supports tight integration with editing and viewing
18771 In the case of an Xfig figure, you are able to invoke Xfig on the original
18772 file with a single click from within the external material dialog in LyX,
18773 and also preview the produced PostScript file with Ghostview with another
18775 No more fiddling around with the command line and/or file browsers to locate
18776 and manipulate the original or produced files.
18777 In this way, you are finally able to take full advantage of the many different
18778 applications that are relevant to use when you write your documents, and
18779 ultimately be more productive.
18782 \begin_layout Section
18783 The external template configuration file
18786 \begin_layout Standard
18787 It is relatively easy to add custom external template definitions to LyX.
18788 However, be aware that doing this in an careless manner most probably
18792 introduce an easily exploitable security hole.
18793 So before you do this, please read the discussion about security in section
18795 \begin_inset CommandInset ref
18797 reference "sec:Security-discussion"
18804 \begin_layout Standard
18805 Having said that, we encourage you to submit any interesting templates that
18810 \begin_layout Standard
18811 The external templates are defined in the
18812 \begin_inset Flex Code
18815 \begin_layout Plain Layout
18816 LyXDir/lib/external_templates
18822 You can place your own version in
18823 \begin_inset Flex Code
18826 \begin_layout Plain Layout
18827 UserDir/external_templates
18835 \begin_layout Standard
18836 A typical template looks like this:
18839 \begin_layout LyX-Code
18843 \begin_layout LyX-Code
18844 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
18847 \begin_layout LyX-Code
18851 \begin_layout LyX-Code
18855 \begin_layout LyX-Code
18859 \begin_layout LyX-Code
18863 \begin_layout LyX-Code
18867 \begin_layout LyX-Code
18868 AutomaticProduction true
18871 \begin_layout LyX-Code
18875 \begin_layout LyX-Code
18879 \begin_layout LyX-Code
18883 \begin_layout LyX-Code
18884 TransformCommand Rotate RotationLatexCommand
18887 \begin_layout LyX-Code
18888 TransformCommand Resize ResizeLatexCommand
18891 \begin_layout LyX-Code
18892 Product "$$RotateFront$$ResizeFront
18895 \begin_layout LyX-Code
18900 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
18903 \begin_layout LyX-Code
18904 $$ResizeBack$$RotateBack"
18907 \begin_layout LyX-Code
18911 \begin_layout LyX-Code
18912 UpdateResult "$$AbsPath$$Basename.pstex_t"
18915 \begin_layout LyX-Code
18916 Requirement "graphicx"
18919 \begin_layout LyX-Code
18920 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
18923 \begin_layout LyX-Code
18924 ReferencedFile latex "$$AbsPath$$Basename.eps"
18927 \begin_layout LyX-Code
18928 ReferencedFile dvi "$$AbsPath$$Basename.eps"
18931 \begin_layout LyX-Code
18935 \begin_layout LyX-Code
18939 \begin_layout LyX-Code
18940 TransformCommand Rotate RotationLatexCommand
18943 \begin_layout LyX-Code
18944 TransformCommand Resize ResizeLatexCommand
18947 \begin_layout LyX-Code
18948 Product "$$RotateFront$$ResizeFront
18951 \begin_layout LyX-Code
18956 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
18959 \begin_layout LyX-Code
18960 $$ResizeBack$$RotateBack"
18963 \begin_layout LyX-Code
18964 UpdateFormat pdftex
18967 \begin_layout LyX-Code
18968 UpdateResult "$$AbsPath$$Basename.pdftex_t"
18971 \begin_layout LyX-Code
18972 Requirement "graphicx"
18975 \begin_layout LyX-Code
18976 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
18979 \begin_layout LyX-Code
18980 ReferencedFile latex "$$AbsPath$$Basename.pdf"
18983 \begin_layout LyX-Code
18987 \begin_layout LyX-Code
18991 \begin_layout LyX-Code
18992 Product "$$Contents(
18994 "$$AbsPath$$Basename.asc
18999 \begin_layout LyX-Code
19000 UpdateFormat asciixfig
19003 \begin_layout LyX-Code
19004 UpdateResult "$$AbsPath$$Basename.asc"
19007 \begin_layout LyX-Code
19011 \begin_layout LyX-Code
19015 \begin_layout LyX-Code
19016 Product "<graphic fileref=
19018 "$$AbsOrRelPathMaster$$Basename.eps
19023 \begin_layout LyX-Code
19027 \begin_layout LyX-Code
19031 \begin_layout LyX-Code
19032 UpdateResult "$$AbsPath$$Basename.eps"
19035 \begin_layout LyX-Code
19036 ReferencedFile docbook "$$AbsPath$$Basename.eps"
19039 \begin_layout LyX-Code
19040 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
19043 \begin_layout LyX-Code
19047 \begin_layout LyX-Code
19048 Product "[XFig: $$FName]"
19051 \begin_layout LyX-Code
19055 \begin_layout LyX-Code
19059 \begin_layout Standard
19060 As you can see, the template is enclosed in
19061 \begin_inset Flex Code
19064 \begin_layout Plain Layout
19070 \SpecialChar \ldots{}
19072 \begin_inset Flex Code
19075 \begin_layout Plain Layout
19082 It contains a header specifying some general settings and, for each supported
19083 primary document file format, a section
19084 \begin_inset Flex Code
19087 \begin_layout Plain Layout
19093 \SpecialChar \ldots{}
19095 \begin_inset Flex Code
19098 \begin_layout Plain Layout
19107 \begin_layout Subsection
19108 The template header
19111 \begin_layout Description
19112 \begin_inset Flex Code
19115 \begin_layout Plain Layout
19116 AutomaticProduction
19117 \begin_inset space ~
19125 Whether the file represented by the template must be generated by LyX.
19126 This command must occur exactly once.
19129 \begin_layout Description
19130 \begin_inset Flex Code
19133 \begin_layout Plain Layout
19135 \begin_inset space ~
19143 A glob pattern that is used in the file dialog to filter out the desired
19145 If there is more than one possible file extension (e.
19146 \begin_inset space \thinspace{}
19150 \begin_inset space \space{}
19154 \begin_inset Flex Code
19157 \begin_layout Plain Layout
19164 \begin_inset Flex Code
19167 \begin_layout Plain Layout
19173 ), use something like
19174 \begin_inset Flex Code
19177 \begin_layout Plain Layout
19184 This command must occur exactly once.
19187 \begin_layout Description
19188 \begin_inset Flex Code
19191 \begin_layout Plain Layout
19193 \begin_inset space ~
19201 The text that is displayed on the button.
19202 This command must occur exactly once.
19205 \begin_layout Description
19206 \begin_inset Flex Code
19209 \begin_layout Plain Layout
19211 \begin_inset space ~
19215 \begin_inset space ~
19223 The help text that is used in the External dialog.
19224 Provide enough information to explain to the user just what the template
19225 can provide him with.
19226 This command must occur exactly once.
19229 \begin_layout Description
19230 \begin_inset Flex Code
19233 \begin_layout Plain Layout
19235 \begin_inset space ~
19243 The file format of the original file.
19244 This must be the name of a format that is known to LyX (see section
19245 \begin_inset space ~
19249 \begin_inset CommandInset ref
19251 reference "sec:Formats"
19257 \begin_inset Quotes eld
19261 \begin_inset Flex Code
19264 \begin_layout Plain Layout
19271 \begin_inset Quotes erd
19274 if the template can handle original files of more than one format.
19275 LyX will attempt to interrogate the file itself in order to deduce its
19276 format in this case.
19277 This command must occur exactly once.
19280 \begin_layout Description
19281 \begin_inset Flex Code
19284 \begin_layout Plain Layout
19286 \begin_inset space ~
19294 A unique name for the template.
19295 It must not contain substitution macros (see below).
19298 \begin_layout Description
19299 \begin_inset Flex Code
19302 \begin_layout Plain Layout
19304 \begin_inset space ~
19307 Rotate|Resize|Clip|Extra
19312 This command specifies which transformations are supported by this template.
19313 It may occur zero or more times.
19314 This command enables the corresponding tabs in the external dialog.
19316 \begin_inset Flex Code
19319 \begin_layout Plain Layout
19325 command must have either a corresponding
19326 \begin_inset Flex Code
19329 \begin_layout Plain Layout
19336 \begin_inset Flex Code
19339 \begin_layout Plain Layout
19346 \begin_inset Flex Code
19349 \begin_layout Plain Layout
19356 Otherwise the transformation will not be supported by that format.
19359 \begin_layout Subsection
19363 \begin_layout Description
19364 \begin_inset Flex Code
19367 \begin_layout Plain Layout
19369 \begin_inset space ~
19372 LaTeX|PDFLaTeX|PlainText|DocBook
19377 The primary document file format that this format definition is for.
19378 Not every template has a sensible representation in all document file formats.
19379 Please define nevertheless a
19380 \begin_inset Flex Code
19383 \begin_layout Plain Layout
19389 section for all templates.
19390 Use a dummy text when no representation is available.
19391 Then you can at least see a reference to the external material in the exported
19395 \begin_layout Description
19396 \begin_inset Flex Code
19399 \begin_layout Plain Layout
19401 \begin_inset space ~
19405 \begin_inset space ~
19413 This command defines an additional macro
19414 \begin_inset Flex Code
19417 \begin_layout Plain Layout
19423 for substitution in
19424 \begin_inset Flex Code
19427 \begin_layout Plain Layout
19435 \begin_inset Flex Code
19438 \begin_layout Plain Layout
19444 itself may contain substitution macros.
19445 The advantage over using
19446 \begin_inset Flex Code
19449 \begin_layout Plain Layout
19456 \begin_inset Flex Code
19459 \begin_layout Plain Layout
19465 is that the substituted value of
19466 \begin_inset Flex Code
19469 \begin_layout Plain Layout
19475 is sanitized so that it is a valid optional argument in the document format.
19476 This command may occur zero or more times.
19479 \begin_layout Description
19480 \begin_inset Flex Code
19483 \begin_layout Plain Layout
19485 \begin_inset space ~
19493 The text that is inserted in the exported document.
19494 This is actually the most important command and can be quite complex.
19495 This command must occur exactly once.
19498 \begin_layout Description
19499 \begin_inset Flex Code
19502 \begin_layout Plain Layout
19504 \begin_inset space ~
19512 This command specifies a preamble snippet that will be included in the
19514 It has to be defined using
19515 \begin_inset Flex Code
19518 \begin_layout Plain Layout
19524 \SpecialChar \ldots{}
19526 \begin_inset Flex Code
19529 \begin_layout Plain Layout
19536 This command may occur zero or more times.
19539 \begin_layout Description
19540 \begin_inset Flex Code
19543 \begin_layout Plain Layout
19545 \begin_inset space ~
19549 \begin_inset space ~
19557 This command denotes files that are created by the conversion process and
19558 are needed for a particular export format.
19559 If the filename is relative, it is interpreted relative to the master document.
19560 This command may be given zero or more times.
19563 \begin_layout Description
19564 \begin_inset Flex Code
19567 \begin_layout Plain Layout
19569 \begin_inset space ~
19577 The name of a required LaTeX package.
19578 The package is included via
19579 \begin_inset Flex Code
19582 \begin_layout Plain Layout
19590 in the LaTeX preamble.
19591 This command may occur zero or more times.
19594 \begin_layout Description
19595 \begin_inset Flex Code
19598 \begin_layout Plain Layout
19600 \begin_inset space ~
19604 \begin_inset space ~
19607 RotationLatexCommand
19612 This command specifies that the built in LaTeX command should be used for
19614 This command may occur once or not at all.
19617 \begin_layout Description
19618 \begin_inset Flex Code
19621 \begin_layout Plain Layout
19623 \begin_inset space ~
19627 \begin_inset space ~
19635 This command specifies that the built in LaTeX command should be used for
19637 This command may occur once or not at all.
19640 \begin_layout Description
19641 \begin_inset Flex Code
19644 \begin_layout Plain Layout
19646 \begin_inset space ~
19650 \begin_inset space ~
19653 RotationLatexOption
19658 This command specifies that rotation is done via an optional argument.
19659 This command may occur once or not at all.
19662 \begin_layout Description
19663 \begin_inset Flex Code
19666 \begin_layout Plain Layout
19668 \begin_inset space ~
19672 \begin_inset space ~
19680 This command specifies that resizing is done via an optional argument.
19681 This command may occur once or not at all.
19684 \begin_layout Description
19685 \begin_inset Flex Code
19688 \begin_layout Plain Layout
19690 \begin_inset space ~
19694 \begin_inset space ~
19702 This command specifies that clipping is done via an optional argument.
19703 This command may occur once or not at all.
19706 \begin_layout Description
19707 \begin_inset Flex Code
19710 \begin_layout Plain Layout
19712 \begin_inset space ~
19716 \begin_inset space ~
19724 This command specifies that an extra optional argument is used.
19725 This command may occur once or not at all.
19728 \begin_layout Description
19729 \begin_inset Flex Code
19732 \begin_layout Plain Layout
19734 \begin_inset space ~
19742 The file format of the converted file.
19743 This must be the name of a format that is known to LyX (see the
19744 \begin_inset Flex MenuItem
19747 \begin_layout Plain Layout
19752 ools\SpecialChar \menuseparator
19757 references\SpecialChar \menuseparator
19758 File Handling\SpecialChar \menuseparator
19765 This command must occur exactly once.
19768 \begin_layout Description
19769 \begin_inset Flex Code
19772 \begin_layout Plain Layout
19774 \begin_inset space ~
19782 The file name of the converted file.
19783 The file name must be absolute.
19784 This command must occur exactly once.
19787 \begin_layout Subsection
19788 Preamble definitions
19791 \begin_layout Standard
19792 The external template configuration file may contain additional preamble
19793 definitions enclosed by
19794 \begin_inset Flex Code
19797 \begin_layout Plain Layout
19803 \SpecialChar \ldots{}
19805 \begin_inset Flex Code
19808 \begin_layout Plain Layout
19815 They can be used by the templates in the
19816 \begin_inset Flex Code
19819 \begin_layout Plain Layout
19828 \begin_layout Section
19829 The substitution mechanism
19832 \begin_layout Standard
19833 When the external material facility invokes an external program, it is done
19834 on the basis of a command defined in the template configuration file.
19835 These commands can contain various macros that are expanded before execution.
19836 Execution always take place in the directory of the containing document.
19839 \begin_layout Standard
19840 Also, whenever external material is to be displayed, the name will be produced
19841 by the substitution mechanism, and most other commands in the template
19842 definition support substitution as well.
19845 \begin_layout Standard
19846 The available macros are the following:
19849 \begin_layout Description
19850 \begin_inset Flex Code
19853 \begin_layout Plain Layout
19854 $$AbsOrRelPathMaster
19859 The file path, absolute or relative to the master LyX document.
19862 \begin_layout Description
19863 \begin_inset Flex Code
19866 \begin_layout Plain Layout
19867 $$AbsOrRelPathParent
19872 The file path, absolute or relative to the LyX document.
19875 \begin_layout Description
19876 \begin_inset Flex Code
19879 \begin_layout Plain Layout
19885 The absolute file path.
19888 \begin_layout Description
19889 \begin_inset Flex Code
19892 \begin_layout Plain Layout
19898 The filename without path and without the extension.
19901 \begin_layout Description
19902 \begin_inset Flex Code
19905 \begin_layout Plain Layout
19907 \begin_inset Quotes eld
19911 \begin_inset Quotes erd
19919 This macro will expand to the contents of the file with the name
19920 \begin_inset Flex Code
19923 \begin_layout Plain Layout
19932 \begin_layout Description
19933 \begin_inset Flex Code
19936 \begin_layout Plain Layout
19942 The file extension (including the dot).
19945 \begin_layout Description
19946 \begin_inset Flex Code
19949 \begin_layout Plain Layout
19955 The filename of the file specified in the external material dialog.
19956 This is either an absolute name, or it is relative to the LyX document.
19959 \begin_layout Description
19960 \begin_inset Flex Code
19963 \begin_layout Plain Layout
19970 \begin_inset Flex Code
19973 \begin_layout Plain Layout
19979 (absolute name or relative to the LyX document).
19982 \begin_layout Description
19983 \begin_inset Flex Code
19986 \begin_layout Plain Layout
19992 The file path, relative to the master LyX document.
19995 \begin_layout Description
19996 \begin_inset Flex Code
19999 \begin_layout Plain Layout
20005 The file path, relative to the LyX document.
20008 \begin_layout Description
20009 \begin_inset Flex Code
20012 \begin_layout Plain Layout
20018 This macro will expand to the absolute path of the system directory.
20019 This is typically used to point to the various helper scripts that are
20023 \begin_layout Description
20024 \begin_inset Flex Code
20027 \begin_layout Plain Layout
20033 A name and full path to a temporary file which will be automatically deleted
20034 whenever the containing document is closed, or the external material insertion
20038 \begin_layout Standard
20039 All path macros contain a trailing directory separator, so you can construct
20041 \begin_inset space \thinspace{}
20045 \begin_inset space \space{}
20048 the absolute filename with
20049 \begin_inset Flex Code
20052 \begin_layout Plain Layout
20053 $$AbsPath$$Basename$$Extension
20061 \begin_layout Standard
20062 The macros above are substituted in all commands unless otherwise noted.
20064 \begin_inset Flex Code
20067 \begin_layout Plain Layout
20073 supports additionally the following substitutions if they are enabled by
20075 \begin_inset Flex Code
20078 \begin_layout Plain Layout
20085 \begin_inset Flex Code
20088 \begin_layout Plain Layout
20097 \begin_layout Description
20098 \begin_inset Flex Code
20101 \begin_layout Plain Layout
20107 The front part of the resize command.
20110 \begin_layout Description
20111 \begin_inset Flex Code
20114 \begin_layout Plain Layout
20120 The back part of the resize command.
20123 \begin_layout Description
20124 \begin_inset Flex Code
20127 \begin_layout Plain Layout
20133 The front part of the rotation command.
20136 \begin_layout Description
20137 \begin_inset Flex Code
20140 \begin_layout Plain Layout
20146 The back part of the rotation command.
20149 \begin_layout Standard
20150 The value string of the
20151 \begin_inset Flex Code
20154 \begin_layout Plain Layout
20160 command supports additionally the following substitutions if they are enabled
20162 \begin_inset Flex Code
20165 \begin_layout Plain Layout
20172 \begin_inset Flex Code
20175 \begin_layout Plain Layout
20184 \begin_layout Description
20185 \begin_inset Flex Code
20188 \begin_layout Plain Layout
20197 \begin_layout Description
20198 \begin_inset Flex Code
20201 \begin_layout Plain Layout
20210 \begin_layout Description
20211 \begin_inset Flex Code
20214 \begin_layout Plain Layout
20223 \begin_layout Description
20224 \begin_inset Flex Code
20227 \begin_layout Plain Layout
20233 The rotation option.
20236 \begin_layout Standard
20237 You may ask why there are so many path macros.
20238 There are mainly two reasons:
20241 \begin_layout Enumerate
20242 Relative and absolute file names should remain relative or absolute, respectivel
20244 Users may have reasons to prefer either form.
20245 Relative names are useful for portable documents that should work on different
20246 machines, for example.
20247 Absolute names may be required by some programs.
20250 \begin_layout Enumerate
20251 LaTeX treats relative file names differently than LyX and other programs
20252 in nested included files.
20253 For LyX, a relative file name is always relative to the document that contains
20255 For LaTeX, it is always relative to the master document.
20256 These two definitions are identical if you have only one document, but
20257 differ if you have a master document that includes part documents.
20258 That means that relative filenames must be transformed when presented to
20260 Fortunately LyX does this automatically for you if you choose the right
20264 \begin_layout Standard
20265 So which path macro should be used in new template definitions? The rule
20269 \begin_layout Itemize
20271 \begin_inset Flex Code
20274 \begin_layout Plain Layout
20280 if an absolute path is required.
20283 \begin_layout Itemize
20285 \begin_inset Flex Code
20288 \begin_layout Plain Layout
20289 $$AbsOrRelPathMaster
20294 if the substituted string is some kind of LaTeX input.
20297 \begin_layout Itemize
20299 \begin_inset Flex Code
20302 \begin_layout Plain Layout
20303 $$AbsOrRelPathParent
20308 in order to preserve the user's choice.
20311 \begin_layout Standard
20312 There are special cases where this rule does not work and e.
20313 \begin_inset space \thinspace{}
20317 \begin_inset space \space{}
20320 relative names are needed, but normally it will work just fine.
20321 One example for such a case is the command
20322 \begin_inset Flex Code
20325 \begin_layout Plain Layout
20326 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
20331 in the XFig template above: We can't use the absolute name because the
20333 \begin_inset Flex Code
20336 \begin_layout Plain Layout
20342 files needs the relative name in order to rewrite the file content.
20345 \begin_layout Section
20346 Security discussion
20347 \begin_inset CommandInset label
20349 name "sec:Security-discussion"
20356 \begin_layout Standard
20357 The external material feature interfaces with a lot of external programs
20358 and does so automatically, so we have to consider the security implications
20360 In particular, since you have the option of including your own filenames
20361 and/or parameter strings and those are expanded into a command, it seems
20362 that it would be possible to create a malicious document which executes
20363 arbitrary commands when a user views or prints the document.
20364 This is something we definitely want to avoid.
20367 \begin_layout Standard
20368 However, since the external program commands are specified in the template
20369 configuration file only, there are no security issues if LyX is properly
20370 configured with safe templates only.
20371 This is so because the external programs are invoked with the
20372 \begin_inset Flex Code
20375 \begin_layout Plain Layout
20381 -system call rather than the
20382 \begin_inset Flex Code
20385 \begin_layout Plain Layout
20391 system-call, so it's not possible to execute arbitrary commands from the
20392 filename or parameter section via the shell.
20395 \begin_layout Standard
20396 This also implies that you are restricted in what command strings you can
20397 use in the external material templates.
20398 In particular, pipes and redirection are not readily available.
20399 This has to be so if LyX should remain safe.
20400 If you want to use some of the shell features, you should write a safe
20401 script to do this in a controlled manner, and then invoke the script from
20402 the command string.
20406 \begin_layout Standard
20407 It is possible to design a template that interacts directly with the shell,
20408 but since this would allow a malicious user to execute arbitrary commands
20409 by writing clever filenames and/or parameters, we generally recommend that
20410 you only use safe scripts that work with the
20411 \begin_inset Flex Code
20414 \begin_layout Plain Layout
20420 system call in a controlled manner.
20421 Of course, for use in a controlled environment, it can be tempting to just
20422 fall back to use ordinary shell scripts.
20423 If you do so, be aware that you
20427 provide an easily exploitable security hole in your system.
20428 Of course it stands to reason that such unsafe templates will never be
20429 included in the standard LyX distribution, although we do encourage people
20430 to submit new templates in the open source tradition.
20431 But LyX as shipped from the official distribution channels will never have
20435 \begin_layout Standard
20436 Including external material provides a lot of power, and you have to be
20437 careful not to introduce security hazards with this power.
20438 A subtle error in a single line in an innocent looking script can open
20439 the door to huge security problems.
20440 So if you do not fully understand the issues, we recommend that you consult
20441 a knowledgeable security professional or the LyX development team if you
20442 have any questions about whether a given template is safe or not.
20443 And do this before you use it in an uncontrolled environment.