1 #LyX 2.1 created this file. For more info see http://www.lyx.org/
7 % DO NOT ALTER THIS PREAMBLE!!!
9 % This preamble is designed to ensure that this document prints
10 % out as advertised. If you mess with this preamble,
11 % parts of this document may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 \options fleqn,bibliography=totoc,index=totoc,BCOR7.5mm,titlepage,captions=tableheading
35 \use_default_options false
39 \maintain_unincluded_children false
42 InsetLayout Flex:MenuItem
51 \newcommand*{\menuitem}[1]{{\sffamily #1}}
54 # In case we need to do with sans...
55 #InsetLayout CharStyle:Code
60 #\renewcommand{\code}[1]{{\sffamily #1}}
65 \language_package default
70 \font_typewriter default
72 \font_default_family default
73 \use_non_tex_fonts false
79 \default_output_format default
81 \bibtex_command default
82 \index_command default
86 \pdf_title "LyX Configuration Manual"
87 \pdf_author "LyX Team"
88 \pdf_subject "LyX-documentation Customization"
89 \pdf_keywords "LyX, documentation, customization"
91 \pdf_bookmarksnumbered true
92 \pdf_bookmarksopen true
93 \pdf_bookmarksopenlevel 1
98 \pdf_pdfusetitle false
99 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
102 \use_package amsmath 0
103 \use_package amssymb 0
105 \use_package mathdots 1
106 \use_package mathtools 0
107 \use_package mhchem 0
108 \use_package stackrel 0
109 \use_package stmaryrd 0
110 \use_package undertilde 0
112 \cite_engine_type numerical
116 \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 -712698321 "Jürgen Spitzmüller"
143 \author -195340706 "Georg Baum"
145 \author 155139281 "Jrgen Spitzmller"
146 \author 1082167584 "Kayvan Sylvan" kayvan@sylvan.com
147 \author 1414654397 "Richard Heck"
148 \author 2090807402 "usti"
154 Customizing LyX: Features for the Advanced User
162 \begin_layout Plain Layout
164 If you have comments or error corrections, please send them to the LyX Documenta
166 \begin_inset CommandInset href
168 target "lyx-docs@lists.lyx.org"
175 \begin_inset Quotes eld
179 \begin_inset Quotes erd
182 in the subject header, and please cc the current maintainer of this file,
183 Richard Heck <rgheck@comcast.net>.
189 \begin_inset Newline newline
193 \begin_inset Newline newline
199 \begin_layout Standard
200 \begin_inset CommandInset toc
201 LatexCommand tableofcontents
208 \begin_layout Standard
209 \begin_inset Note Note
212 \begin_layout Plain Layout
213 Please use change tracking when modifying this document.
214 This makes it easier for our translators to recognize things that have
215 been changed, and it helps the maintainer keep up-to-date with what's been
224 \begin_layout Chapter
228 \begin_layout Standard
229 This manual covers the customization features present in LyX.
230 In it, we discuss issues like keyboard shortcuts, screen previewing options,
231 printer options, sending commands to LyX via the LyX Server, internationalizati
232 on, installing new LaTeX classes and LyX layouts, etc.
233 We can't possibly hope to touch on everything you can change—our developers
234 add new features faster than we can document them—but we will explain the
235 most common customizations and hopefully point you in the right direction
236 for some of the more obscure ones.
239 \begin_layout Standard
240 \begin_inset Branch OutDated
243 \begin_layout Standard
244 Information from previous versions of this document that now seems to be
245 outdated is contained in the OutDated branch of this document.
246 By default, this information will not appear in the LaTeX output.
254 \begin_layout Chapter
255 LyX configuration files
258 \begin_layout Standard
259 This chapter aims to help you to find your way through the LyX configuration
261 Before continuing to read this chapter, you should find out where your
262 LyX library and user directories are by using
263 \begin_inset Flex MenuItem
266 \begin_layout Plain Layout
267 Help\SpecialChar \menuseparator
278 The library directory is the place where LyX places its system-wide configurati
279 on files; the user directory is where you can place your modified versions.
280 We will call the former
281 \begin_inset Flex Code
284 \begin_layout Plain Layout
291 \begin_inset Flex MenuItem
294 \begin_layout Plain Layout
300 in the remainder of this document.
304 \begin_layout Section
306 \begin_inset Flex Code
309 \begin_layout Plain Layout
318 \begin_layout Standard
319 \begin_inset Flex Code
322 \begin_layout Plain Layout
328 and its sub-directories contain a number of files and that can be used
329 to customize LyX's behavior.
330 You can change many of these files from within LyX itself through the
331 \begin_inset Flex MenuItem
334 \begin_layout Plain Layout
335 Tools\SpecialChar \menuseparator
342 Most customization that you will want to do in LyX is possible through
344 However, many other inner aspects of LyX can be customized by modifying
346 \begin_inset Flex Code
349 \begin_layout Plain Layout
356 These files fall in different categories, described in the following subsection
360 \begin_layout Subsection
361 Automatically generated files
364 \begin_layout Standard
365 The files, which are to be found in
366 \begin_inset Flex MenuItem
369 \begin_layout Plain Layout
375 , are generated when you configure LyX.
376 They contain various default values that are guessed by inspection.
377 In general, it is not a good idea to modify them, since they might be overwritt
381 \begin_layout Labeling
382 \labelwidthstring 00.00.0000
383 \begin_inset Flex Code
386 \begin_layout Plain Layout
392 contains defaults for various commands.
395 \begin_layout Labeling
396 \labelwidthstring 00.00.0000
397 \begin_inset Flex Code
400 \begin_layout Plain Layout
406 contains the list of packages that have been recognized by LyX.
407 It is currently unused by the LyX program itself, but the information extracted
408 , and more, is made available with
409 \begin_inset Flex MenuItem
412 \begin_layout Plain Layout
413 Help\SpecialChar \menuseparator
426 \begin_layout Labeling
427 \labelwidthstring 00.00.0000
428 \begin_inset Flex Code
431 \begin_layout Plain Layout
437 the list of text classes that have been found in your
438 \begin_inset Flex Code
441 \begin_layout Plain Layout
447 directories, along with the associated LaTeX document class and their descripti
451 \begin_layout Labeling
452 \labelwidthstring 00.00.0000
453 \begin_inset Flex Code
456 \begin_layout Plain Layout
462 the list of layout modules found in your
463 \begin_inset Flex Code
466 \begin_layout Plain Layout
475 \begin_layout Labeling
476 \labelwidthstring 00.00.0000
477 \begin_inset Flex Code
480 \begin_layout Plain Layout
486 lists of various sorts of LaTeX-related files found on your system
489 \begin_layout Labeling
490 \labelwidthstring 00.00.0000
491 \begin_inset Flex Code
494 \begin_layout Plain Layout
500 is automatically generated during configuration from the file
501 \begin_inset Flex Code
504 \begin_layout Plain Layout
511 It contains information on your LaTeX configuration.
514 \begin_layout Subsection
518 \begin_layout Standard
519 These directories are duplicated between
520 \begin_inset Flex Code
523 \begin_layout Plain Layout
530 \begin_inset Flex Code
533 \begin_layout Plain Layout
540 If a particular files exists in both places, the one in
541 \begin_inset Flex Code
544 \begin_layout Plain Layout
553 \begin_layout Labeling
554 \labelwidthstring 00.00.0000
555 \begin_inset Flex Code
558 \begin_layout Plain Layout
564 this directory contains files with the extension
565 \begin_inset Flex Code
568 \begin_layout Plain Layout
574 that define the keybindings used in LyX.
575 If there exists an internationalized version of the bind file named
576 \begin_inset Flex Code
579 \begin_layout Plain Layout
585 , that will be used first.
588 \begin_layout Labeling
589 \labelwidthstring 00.00.0000
590 \begin_inset Flex Code
593 \begin_layout Plain Layout
599 contains graphics files that can be included in documents.
603 \begin_layout Labeling
604 \labelwidthstring 00.00.0000
605 \begin_inset Flex Code
608 \begin_layout Plain Layout
614 contains LyX documentation files (including the one you are currently reading).
616 \begin_inset Flex Code
619 \begin_layout Plain Layout
625 deserves special attention, as noted above.
626 The internationalized help docs are in subdirectories
627 \begin_inset Flex Code
630 \begin_layout Plain Layout
637 \begin_inset Quotes eld
641 \begin_inset Quotes erd
644 is the ISO language code.
650 \begin_inset CommandInset ref
652 reference "cha:Internationalizing-LyX"
659 \begin_layout Labeling
660 \labelwidthstring 00.00.0000
661 \begin_inset Flex Code
664 \begin_layout Plain Layout
670 contains example files that explain how to use some features.
671 In the file browser, press the
672 \begin_inset Flex MenuItem
675 \begin_layout Plain Layout
684 \begin_layout Labeling
685 \labelwidthstring 00.00.0000
686 \begin_inset Flex Code
689 \begin_layout Plain Layout
695 contains image files that are used by the
696 \begin_inset Flex MenuItem
699 \begin_layout Plain Layout
706 In addition, it also contains the individual icons used in the toolbar
707 and the banners that can be shown when LyX is launched.
710 \begin_layout Labeling
711 \labelwidthstring 00.00.0000
712 \begin_inset Flex Code
715 \begin_layout Plain Layout
721 contains keyboard keymapping files.
727 \begin_inset CommandInset ref
729 reference "sec:International-Keymap-Stuff"
736 \begin_layout Labeling
737 \labelwidthstring 00.00.0000
738 \begin_inset Flex Code
741 \begin_layout Plain Layout
747 contains the text class and module files described in Chapter
752 \begin_inset CommandInset ref
754 reference "cha:Installing-New-Document"
761 \begin_layout Labeling
762 \labelwidthstring 00.00.0000
763 \begin_inset Flex Code
766 \begin_layout Plain Layout
773 \begin_inset Flex Code
776 \begin_layout Plain Layout
782 Python scripts used to convert between LyX versions.
783 These can be run from the command line if, say, you want to batch-convert
787 \begin_layout Labeling
788 \labelwidthstring 00.00.0000
789 \begin_inset Flex Code
792 \begin_layout Plain Layout
798 contains some files that demonstrate the capabilities of the
799 \begin_inset Flex MenuItem
802 \begin_layout Plain Layout
813 Also contains some scripts used by LyX itself.
816 \begin_layout Labeling
817 \labelwidthstring 00.00.0000
818 \begin_inset Flex Code
821 \begin_layout Plain Layout
827 contains the standard LyX template files described in Chapter
832 \begin_inset CommandInset ref
834 reference "sub:Creating-Templates"
841 \begin_layout Labeling
842 \labelwidthstring 00.00.0000
843 \begin_inset Flex Code
846 \begin_layout Plain Layout
852 contains files with the extension
853 \begin_inset Flex Code
856 \begin_layout Plain Layout
862 that define the user interface to LyX.
863 That is, the files define which items appear in which menus and the items
864 appearing on the toolbar.
867 \begin_layout Subsection
868 Files you don't want to modify
871 \begin_layout Standard
872 These files are used internally by LyX and you generally do not need to
873 modify them unless you are a developer.
876 \begin_layout Labeling
877 \labelwidthstring 00.00.0000
878 \begin_inset Flex Code
881 \begin_layout Plain Layout
887 this file contains the list of LyX developers.
888 The contents are displayed with the menu entry
889 \begin_inset Flex MenuItem
892 \begin_layout Plain Layout
893 Help\SpecialChar \menuseparator
906 \begin_layout Labeling
907 \labelwidthstring 00.00.0000
908 \begin_inset Flex Code
911 \begin_layout Plain Layout
917 this is a LaTeX script used during the configuration process.
921 \begin_layout Labeling
922 \labelwidthstring 00.00.0000
923 \begin_inset Flex Code
926 \begin_layout Plain Layout
932 this is the script that is used to re-configure LyX.
933 It creates configuration files in the directory it was run from.
936 \begin_layout Subsection
937 Other files needing a line or two...
940 \begin_layout Labeling
941 \labelwidthstring 00.00.0000
942 \begin_inset Flex Code
945 \begin_layout Plain Layout
951 this contains tables describing how different character encodings can be
955 \begin_layout Labeling
956 \labelwidthstring 00.00.0000
957 \begin_inset Flex Code
960 \begin_layout Plain Layout
966 this file contains the templates available to the new
967 \begin_inset Flex MenuItem
970 \begin_layout Plain Layout
983 \begin_layout Labeling
984 \labelwidthstring 00.00.0000
985 \begin_inset Flex Code
988 \begin_layout Plain Layout
994 this file contains a list of all the languages currently supported by LyX.
995 \change_inserted -195340706 1334775793
999 \begin_layout Labeling
1000 \labelwidthstring 00.00.0000
1002 \change_inserted -195340706 1334775793
1003 \begin_inset Flex Code
1006 \begin_layout Plain Layout
1008 \change_inserted -195340706 1334775793
1014 this file contains translations for internationalized paragraph styles
1016 \begin_inset space \thinspace{}
1020 \begin_inset CommandInset ref
1022 reference "sub:I18n"
1031 \begin_layout Section
1032 Your local configuration directory
1035 \begin_layout Standard
1036 Even if you are using LyX as an unprivileged user, you might want to change
1037 LyX configuration for your own use.
1039 \begin_inset Flex Code
1042 \begin_layout Plain Layout
1048 directory contains all your personal configuration files.
1049 This is the directory described as
1050 \begin_inset Quotes eld
1054 \begin_inset Quotes erd
1058 \begin_inset Flex MenuItem
1061 \begin_layout Plain Layout
1062 Help\SpecialChar \menuseparator
1064 \begin_inset space ~
1073 This directory is used as a mirror of
1074 \begin_inset Flex Code
1077 \begin_layout Plain Layout
1083 , which means that every file in
1084 \begin_inset Flex Code
1087 \begin_layout Plain Layout
1093 is a replacement for the corresponding file in
1094 \begin_inset Flex Code
1097 \begin_layout Plain Layout
1104 Any configuration file described in the above sections can be placed either
1105 in the system-wide directory, in which case it will affect all users, or
1106 in your local directory for your own use.
1109 \begin_layout Standard
1110 To make things clearer, let's provide a few examples:
1113 \begin_layout Itemize
1114 The preferences set in the
1115 \begin_inset Flex MenuItem
1118 \begin_layout Plain Layout
1119 Tools\SpecialChar \menuseparator
1125 dialog are saved to a file
1126 \begin_inset Flex Code
1129 \begin_layout Plain Layout
1136 \begin_inset Flex Code
1139 \begin_layout Plain Layout
1148 \begin_layout Itemize
1149 When you reconfigure using
1150 \begin_inset Flex MenuItem
1153 \begin_layout Plain Layout
1154 Tools\SpecialChar \menuseparator
1161 \begin_inset Flex Code
1164 \begin_layout Plain Layout
1170 script, and the resulting files are written in your local configuration
1172 This means that any additional text class file that you might have added
1174 \begin_inset Flex Code
1177 \begin_layout Plain Layout
1183 will be added to the list of classes in the
1184 \begin_inset Flex MenuItem
1187 \begin_layout Plain Layout
1188 Document\SpecialChar \menuseparator
1197 \begin_layout Itemize
1198 If you get some updated documentation from LyX ftp site and cannot install
1199 it because you do not have sysadmin rights on your system, you can just
1201 \begin_inset Flex Code
1204 \begin_layout Plain Layout
1210 and the items in the
1211 \begin_inset Flex MenuItem
1214 \begin_layout Plain Layout
1220 menu will open them!
1223 \begin_layout Section
1224 Running LyX with multiple configurations
1227 \begin_layout Standard
1228 The configuration freedom of the local configuration directory may not suffice
1229 if you want to have more than one configuration at your disposal.
1230 For example, you may want to be use different key bindings or printer settings
1232 You can achieve this by having several such directories.
1233 You then specify which directory to use at run-time.
1236 \begin_layout Standard
1237 Invoking LyX with the command line switch
1238 \begin_inset Flex Code
1241 \begin_layout Plain Layout
1251 instructs the program to read the configuration from that directory, and
1252 not from the default directory.
1253 (You can determine the default directory by running LyX without the
1254 \begin_inset Flex Code
1257 \begin_layout Plain Layout
1263 switch.) If the specified directory does not exist, LyX offers to create
1264 it for you, just like it does for the default directory on the first time
1265 you run the program.
1266 You can modify the configuration options in this additional user directory
1267 exactly as you would for the default directory.
1268 These directories are completely independent (but read on).
1269 Note that setting the environment variable
1270 \begin_inset Flex Code
1273 \begin_layout Plain Layout
1279 to some value has exactly the same effect.
1282 \begin_layout Standard
1283 Having several configurations also requires more maintenance: if you want
1284 to add a new layout to
1285 \begin_inset Flex Code
1288 \begin_layout Plain Layout
1294 which you want available from all your configurations, you must add it
1295 to each directory separately.
1296 You can avoid this with the following trick: after LyX creates the additional
1297 directory, most of the subdirectories (see above) are empty.
1298 If you want the new configuration to mirror an existing one, replace the
1299 empty subdirectory with a symbolic link to the matching subdirectory in
1300 the existing configuration.
1302 \begin_inset Flex Code
1305 \begin_layout Plain Layout
1311 subdirectory, however, since it contains a file written by the configuration
1312 script (also accessible through
1313 \begin_inset Flex MenuItem
1316 \begin_layout Plain Layout
1317 Tools\SpecialChar \menuseparator
1323 ) which is configuration-specific.
1326 \begin_layout Chapter
1327 The Preferences dialog
1330 \begin_layout Standard
1331 All options of the preferences dialog are described in the Appendix
1333 The Preferences Dialog
1340 For some options you might find here more details.
1343 \begin_layout Section
1345 \begin_inset CommandInset label
1354 \begin_layout Standard
1355 The first step is to define your file formats if they are not already defined.
1357 \begin_inset Flex MenuItem
1360 \begin_layout Plain Layout
1361 Tools\SpecialChar \menuseparator
1369 \begin_inset Flex MenuItem
1372 \begin_layout Plain Layout
1373 File Handling\SpecialChar \menuseparator
1380 \begin_inset Flex MenuItem
1383 \begin_layout Plain Layout
1384 New\SpecialChar \ldots{}
1390 button to define your new format.
1392 \begin_inset Flex MenuItem
1395 \begin_layout Plain Layout
1401 field contains the name used to identify the format in the GUI.
1403 \begin_inset Flex MenuItem
1406 \begin_layout Plain Layout
1412 is used to identify the format internally.
1413 You will also need to enter a file extension.
1414 These are all required.
1416 \begin_inset Flex MenuItem
1419 \begin_layout Plain Layout
1425 field is used to provide a keyboard shortcut on the menus.
1426 (For example, pressing
1427 \begin_inset Flex MenuItem
1430 \begin_layout Plain Layout
1437 \begin_inset Flex MenuItem
1440 \begin_layout Plain Layout
1441 View\SpecialChar \menuseparator
1442 View (Other Formats)\SpecialChar \menuseparator
1451 \begin_layout Standard
1453 \begin_inset Flex MenuItem
1456 \begin_layout Plain Layout
1463 \begin_inset Flex MenuItem
1466 \begin_layout Plain Layout
1473 For example, you might want to use
1474 \begin_inset Flex MenuItem
1477 \begin_layout Plain Layout
1483 to view PostScript files.
1484 You can enter the command needed to start the program in the corresponding
1486 In defining this command, you can use the four variables listed in the
1488 The viewer is launched when you view an image in LyX or use the
1489 \begin_inset Flex MenuItem
1492 \begin_layout Plain Layout
1499 The editor is for example launched when you right-click on an image and
1501 \begin_inset Flex MenuItem
1504 \begin_layout Plain Layout
1510 in the appearing context menu.
1513 \begin_layout Standard
1515 \change_inserted -195340706 1329851811
1517 \begin_inset Flex MenuItem
1520 \begin_layout Plain Layout
1526 type of a format is optional, but if it is specified, it must be unique
1528 It is used to detect files of this format from the file contents.
1529 For some important file formats there is no MIME type officially registered
1531 \begin_inset CommandInset href
1534 target "http://www.iana.org/assignments/media-types/"
1539 Therefore LyX uses the extended list of MIME types as specified by
1540 \begin_inset CommandInset href
1542 name "freedesktop.org"
1543 target "http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec"
1550 \begin_layout Standard
1552 \begin_inset Flex MenuItem
1555 \begin_layout Plain Layout
1561 option tells LyX that a format is suitable for document export.
1562 If this is set and if a suitable conversion route exists (see sec.
1563 \begin_inset space \thinspace{}
1567 \begin_inset CommandInset ref
1569 reference "sec:Converters"
1573 ), the format will appear in the
1574 \begin_inset Flex MenuItem
1577 \begin_layout Plain Layout
1578 File\SpecialChar \menuseparator
1585 The format will also appear in the
1586 \begin_inset Flex MenuItem
1589 \begin_layout Plain Layout
1595 menu if a viewer is specified for the format.
1596 Pure image formats, such as
1597 \begin_inset Flex Code
1600 \begin_layout Plain Layout
1606 , should not use this option.
1607 Formats that can both represent vector graphics and documents like
1608 \begin_inset Flex Code
1611 \begin_layout Plain Layout
1620 \begin_layout Standard
1622 \begin_inset Flex MenuItem
1625 \begin_layout Plain Layout
1626 Vector graphics format
1631 tells LyX that a format can contain vector graphics.
1632 This information is used to determine the target format of included graphics
1634 \begin_inset Flex MenuItem
1637 \begin_layout Plain Layout
1644 Included graphics may need to be converted to either
1645 \begin_inset Flex MenuItem
1648 \begin_layout Plain Layout
1655 \begin_inset Flex MenuItem
1658 \begin_layout Plain Layout
1665 \begin_inset Flex MenuItem
1668 \begin_layout Plain Layout
1675 \begin_inset Flex MenuItem
1678 \begin_layout Plain Layout
1684 cannot handle other image formats.
1685 If an included graphic is not already in
1686 \begin_inset Flex MenuItem
1689 \begin_layout Plain Layout
1696 \begin_inset Flex MenuItem
1699 \begin_layout Plain Layout
1706 \begin_inset Flex MenuItem
1709 \begin_layout Plain Layout
1715 format, it is converted to
1716 \begin_inset Flex MenuItem
1719 \begin_layout Plain Layout
1725 if the vector format option is set, and otherwise to
1726 \begin_inset Flex MenuItem
1729 \begin_layout Plain Layout
1738 \begin_layout Section
1742 \begin_layout Standard
1743 Since all conversions from one format to another take place in LyX's temporary
1744 directory, it is sometimes necessary to modify a file before copying it
1745 to the temporary directory in order that the conversion may be performed.
1749 \begin_layout Plain Layout
1750 For example, the file may refer to other files—images, for example—using
1751 relative file names, and these may become invalid when the file is copied
1752 to the temporary directory.
1757 This is done by a Copier: It copies a file to (or from) the temporary directory
1758 and may modify it in the process.
1761 \begin_layout Standard
1762 The definitions of the copiers may use four variables:
1765 \begin_layout Labeling
1766 \labelwidthstring 00.00.0000
1767 \begin_inset Flex Code
1770 \begin_layout Plain Layout
1776 The LyX system directory (e.
1777 \begin_inset space \thinspace{}
1781 \begin_inset space \space{}
1785 \begin_inset Flex MenuItem
1788 \begin_layout Plain Layout
1797 \begin_layout Labeling
1798 \labelwidthstring 00.00.0000
1799 \begin_inset Flex Code
1802 \begin_layout Plain Layout
1811 \begin_layout Labeling
1812 \labelwidthstring 00.00.0000
1813 \begin_inset Flex Code
1816 \begin_layout Plain Layout
1823 \change_inserted 1082167584 1348453985
1827 \begin_layout Labeling
1828 \labelwidthstring 00.00.0000
1830 \change_inserted 1082167584 1348453986
1831 $$b The base name (without filename extension) in the LyX temporary directory
1834 \begin_layout Labeling
1835 \labelwidthstring 00.00.0000
1837 \change_inserted 1082167584 1348453986
1838 $$p The full directory path of the LyX temporary directory
1841 \begin_layout Labeling
1842 \labelwidthstring 00.00.0000
1844 \change_inserted 1082167584 1348453986
1845 $$r The full pathname to the original LyX file being processed
1848 \begin_layout Labeling
1849 \labelwidthstring 00.00.0000
1851 \change_inserted 1082167584 1348453986
1852 $$f The filename (without any directory path) of the LyX file.
1855 \begin_layout Labeling
1856 \labelwidthstring 00.00.0000
1857 \begin_inset Flex Code
1860 \begin_layout Plain Layout
1867 \change_inserted 1082167584 1348453720
1871 \begin_layout Standard
1872 The latter should be the filename as it would be used in a LaTeX's
1879 It is relevant only when exporting files suitable for such inclusion.
1882 \begin_layout Standard
1883 Copiers can be used to do almost anything with output files.
1884 For example, suppose you want generated pdf files to be copied to a special
1886 \begin_inset Flex Code
1889 \begin_layout Plain Layout
1896 Then you could write a shell script such as this one:
1899 \begin_layout Standard
1900 \begin_inset listings
1904 \begin_layout Plain Layout
1909 \begin_layout Plain Layout
1914 \begin_layout Plain Layout
1916 TOFILE=`basename $2`
1919 \begin_layout Plain Layout
1921 cp $FROMFILE /home/you/pdf/$TOFILE
1926 Save it in your local LyX directory—say,
1927 \begin_inset Flex Code
1930 \begin_layout Plain Layout
1931 /home/you/.lyx/scripts/pdfcopier.sh
1936 —and make it executable, if you need to do so on your platform.
1938 \begin_inset Flex MenuItem
1941 \begin_layout Plain Layout
1942 Tools\SpecialChar \menuseparator
1948 dialog, select under
1949 \begin_inset Flex MenuItem
1952 \begin_layout Plain Layout
1953 File Handling\SpecialChar \menuseparator
1960 \begin_inset Flex MenuItem
1963 \begin_layout Plain Layout
1969 format—or one of the other pdf formats—and enter
1970 \begin_inset Flex Code
1973 \begin_layout Plain Layout
1974 pdfcopier.sh $$i $$o
1980 \begin_inset Flex MenuItem
1983 \begin_layout Plain Layout
1993 \begin_layout Standard
1994 Copiers are used by LyX in various of its own conversions.
1995 For example, if appropriate programs are found, LyX will automatically
1996 install copiers for the
1997 \begin_inset Flex MenuItem
2000 \begin_layout Plain Layout
2007 \begin_inset Flex MenuItem
2010 \begin_layout Plain Layout
2012 \begin_inset space ~
2021 When these formats are exported, the copier sees that not just the main
2022 HTML file but various associated files (style files, images, etc.) are also
2024 All these files are written to a subdirectory of the directory in which
2025 the original LyX file was found.
2029 \begin_layout Plain Layout
2030 This copier can be customized.
2032 \begin_inset Quotes eld
2036 \begin_inset Quotes erd
2039 argument takes a comma-separated list of extensions to be copied; if it
2040 is omitted, all files will be copied.
2042 \begin_inset Quotes eld
2046 \begin_inset Quotes erd
2049 argument determines the extension added to the generated directory.
2051 \begin_inset Quotes eld
2055 \begin_inset Flex MenuItem
2058 \begin_layout Plain Layout
2065 \begin_inset Quotes erd
2068 , so HTML generated from
2069 \begin_inset Flex MenuItem
2072 \begin_layout Plain Layout
2073 /path/to/filename.lyx
2079 \begin_inset Flex MenuItem
2082 \begin_layout Plain Layout
2083 /path/to/filename.html.LyXconv
2097 \begin_layout Section
2099 \begin_inset CommandInset label
2101 name "sec:Converters"
2108 \begin_layout Standard
2109 You can define your own Converters to convert files between different formats.
2111 \begin_inset Flex MenuItem
2114 \begin_layout Plain Layout
2115 Tools\SpecialChar \menuseparator
2116 Preferences\SpecialChar \menuseparator
2117 File Handling\SpecialChar \menuseparator
2126 \begin_layout Standard
2127 To define a new converter, select the
2128 \begin_inset Flex MenuItem
2131 \begin_layout Plain Layout
2133 \begin_inset space ~
2142 \begin_inset Flex MenuItem
2145 \begin_layout Plain Layout
2147 \begin_inset space ~
2155 from the drop-down lists, enter the command needed for the conversion,
2157 \begin_inset Flex MenuItem
2160 \begin_layout Plain Layout
2167 Several variables can be used in the definition of converters:
2170 \begin_layout Labeling
2171 \labelwidthstring 00.00.0000
2172 \begin_inset Flex Code
2175 \begin_layout Plain Layout
2181 The LyX system directory
2184 \begin_layout Labeling
2185 \labelwidthstring 00.00.0000
2186 \begin_inset Flex Code
2189 \begin_layout Plain Layout
2198 \begin_layout Labeling
2199 \labelwidthstring 00.00.0000
2200 \begin_inset Flex Code
2203 \begin_layout Plain Layout
2212 \begin_layout Labeling
2213 \labelwidthstring 00.00.0000
2214 \begin_inset Flex Code
2217 \begin_layout Plain Layout
2223 The base filename of the input file (i.
2224 \begin_inset space \thinspace{}
2227 g., without the extension)
2230 \begin_layout Labeling
2231 \labelwidthstring 00.00.0000
2232 \begin_inset Flex Code
2235 \begin_layout Plain Layout
2241 The path to the input file
2244 \begin_layout Labeling
2245 \labelwidthstring 00.00.0000
2246 \begin_inset Flex Code
2249 \begin_layout Plain Layout
2255 The path to the original input file (this is different from $$p when a
2256 chain of converters is called)
2259 \begin_layout Labeling
2260 \labelwidthstring 00.00.0000
2261 \begin_inset Flex Code
2264 \begin_layout Plain Layout
2270 The iconv name for the encoding of the document.
2273 \begin_layout Standard
2275 \begin_inset Flex MenuItem
2278 \begin_layout Plain Layout
2280 \begin_inset space ~
2288 field you can enter the following flags, separated by commas:
2291 \begin_layout Labeling
2292 \labelwidthstring 00.00.0000
2293 \begin_inset Flex Code
2296 \begin_layout Plain Layout
2302 This converter runs some form of LaTeX.
2303 This will make LyX's LaTeX error logs available.
2306 \begin_layout Labeling
2307 \labelwidthstring 00.00.0000
2308 \begin_inset Flex Code
2311 \begin_layout Plain Layout
2318 \begin_inset Flex MenuItem
2321 \begin_layout Plain Layout
2327 file for the conversion.
2328 \change_inserted 1414654397 1337693117
2332 \begin_layout Labeling
2333 \labelwidthstring 00.00.0000
2335 \change_inserted 1414654397 1337693188
2336 \begin_inset Flex Code
2339 \begin_layout Plain Layout
2341 \change_inserted 1414654397 1337693129
2350 \begin_inset Quotes eld
2354 \begin_inset Quotes erd
2357 file from the backend, which in practice means a LaTeX file like the one
2358 we would export, without
2359 \begin_inset Flex Code
2362 \begin_layout Plain Layout
2364 \change_inserted 1414654397 1337693184
2377 \begin_layout Labeling
2378 \labelwidthstring 00.00.0000
2379 \begin_inset Flex Code
2382 \begin_layout Plain Layout
2391 \begin_layout Standard
2392 The following three flags are not really flags at all because they take
2394 \begin_inset Flex MenuItem
2397 \begin_layout Plain Layout
2399 \begin_inset space ~
2403 \begin_inset space ~
2414 \begin_layout Labeling
2415 \labelwidthstring 00.00.0000
2416 \begin_inset Flex Code
2419 \begin_layout Plain Layout
2425 If set, the converter's standard error will be redirected to a file
2426 \begin_inset Flex Code
2429 \begin_layout Plain Layout
2435 , and the script given as argument will be run as:
2436 \begin_inset Flex Code
2439 \begin_layout Plain Layout
2440 script < infile.out > infile.log
2446 The argument may contain
2447 \begin_inset Flex Code
2450 \begin_layout Plain Layout
2459 \begin_layout Labeling
2460 \labelwidthstring 00.00.0000
2461 \begin_inset Flex Code
2464 \begin_layout Plain Layout
2470 The name of the directory in which the converter will dump the generated
2472 LyX will not create this directory, and it does not copy anything into
2473 it, though it will copy this directory to the destination.
2474 The argument may contain
2475 \begin_inset Flex Code
2478 \begin_layout Plain Layout
2484 , which will be replaced by the base name of the input and output files,
2485 respectively, when the directory is copied.
2486 \begin_inset Newline newline
2489 Note that resultdir and usetempdir make no sense together.
2490 The latter will be ignored if the former is given.
2493 \begin_layout Labeling
2494 \labelwidthstring 00.00.0000
2495 \begin_inset Flex Code
2498 \begin_layout Plain Layout
2504 Determines the output file name and may, contain
2505 \begin_inset Flex Code
2508 \begin_layout Plain Layout
2515 Sensible only with resultdir and optional even then; if not given, it defaults
2519 \begin_layout Standard
2520 None of these last three are presently used in any of the converters that
2521 are installed with LyX.
2525 \begin_layout Standard
2526 You do not have to define converters for all formats between which you want
2528 For example, you will note that there is no `LyX to PostScript' converter,
2529 but LyX will export PostScript.
2530 It does so by first creating a LaTeX file (no converter needs to be defined
2531 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2532 and finally converting the resulting DVI file to PostScript.
2533 LyX finds such `chains' of converters automatically, and it will always
2534 choose the shortest possible chain.
2535 You can, though, still define multiple conversion methods between file
2537 For example, the standard LyX configuration provides three ways to convert
2538 LaTeX to PDF: Directly, using
2539 \begin_inset Flex MenuItem
2542 \begin_layout Plain Layout
2548 ; via (DVI and) PostScript, using
2549 \begin_inset Flex MenuItem
2552 \begin_layout Plain Layout
2559 \begin_inset Flex MenuItem
2562 \begin_layout Plain Layout
2569 To define such alternate chains, you must define multiple target `file
2570 formats', as described in section
2571 \begin_inset CommandInset ref
2573 reference "sec:Formats"
2578 For example, in the standard configuration, the formats named
2579 \begin_inset Flex MenuItem
2582 \begin_layout Plain Layout
2589 \begin_inset Flex MenuItem
2592 \begin_layout Plain Layout
2599 \begin_inset Flex MenuItem
2602 \begin_layout Plain Layout
2608 are defined, all of which share the extension
2609 \begin_inset Flex MenuItem
2612 \begin_layout Plain Layout
2618 , and which correspond to the conversion methods just mentioned.
2621 \begin_layout Chapter
2622 Internationalizing LyX
2623 \begin_inset CommandInset label
2625 name "cha:Internationalizing-LyX"
2632 \begin_layout Standard
2633 LyX supports using a translated interface.
2634 Last time we checked, LyX provided text in thirty languages.
2635 The language of choice is called your
2640 (For further reading on locale settings, see also the documentation for
2641 locale that comes with your operating system.
2642 For Linux, the manual page for
2643 \begin_inset Flex Code
2646 \begin_layout Plain Layout
2652 could be a good place to start).
2655 \begin_layout Standard
2656 Notice that these translations will work, but do contain a few flaws.
2657 In particular, all dialogs have been designed with the English text in
2658 mind, which means that some of the translated text will be too large to
2659 fit within the space allocated.
2660 This is only a display problem and will not cause any harm.
2661 Also, you will find that some of the translations do not define shortcut
2662 keys for everything.
2663 Sometimes, there are simply not enough free letters to do it.
2664 Other times, the translator just hasn't got around to doing it yet.
2665 Our localization team, which you may wish to join,
2669 \begin_layout Plain Layout
2670 If you are a fluent speaker of a language other than English, joining these
2671 teams is a great way to give back to the LyX community!
2676 will of course try to fix these shortcomings in future versions of LyX.
2679 \begin_layout Section
2683 \begin_layout Subsection
2684 Translating the graphical user interface (text messages).
2687 \begin_layout Standard
2689 \begin_inset Flex Code
2692 \begin_layout Plain Layout
2698 library to handle the internationalization of the interface.
2699 To have LyX speak your favorite language in all menus and dialogs, you
2701 \begin_inset Flex Code
2704 \begin_layout Plain Layout
2710 -file for that language.
2711 When this is available, you'll have to generate a
2712 \begin_inset Flex Code
2715 \begin_layout Plain Layout
2721 -file from it and install the
2722 \begin_inset Flex Code
2725 \begin_layout Plain Layout
2732 The process of doing all of this is explained in the documentation for
2734 \begin_inset Flex Code
2737 \begin_layout Plain Layout
2744 It is possible to do this just for yourself, but if you're going to do
2745 it, you might as well share the results of your labors with the rest of
2747 Send a message to the LyX developers' list for more information about how
2751 \begin_layout Standard
2752 In short, this is what you should do (xx denotes the language code):
2755 \begin_layout Itemize
2756 Check out the LyX source code.
2758 \begin_inset CommandInset href
2760 name "information on the web"
2761 target "http://www.lyx.org/HowToUseSVN"
2768 \begin_layout Itemize
2770 \begin_inset Flex Code
2773 \begin_layout Plain Layout
2779 to the folder of the
2780 \begin_inset Flex Code
2783 \begin_layout Plain Layout
2791 \begin_inset Flex Code
2794 \begin_layout Plain Layout
2802 \begin_inset Flex Code
2805 \begin_layout Plain Layout
2811 doesn't exist anywhere, it can be remade with the console command
2812 \begin_inset Flex Code
2815 \begin_layout Plain Layout
2821 in that directory, or you can use an existing po-file for some other language
2825 \begin_layout Itemize
2827 \begin_inset Flex Code
2830 \begin_layout Plain Layout
2840 \begin_layout Plain Layout
2841 This is just a text file, so it can be edited in any text editor.
2842 But there are also specialized programs that support such editing, such
2847 (for all platforms) or
2856 contains a `mode' for editing
2857 \begin_inset Flex Code
2860 \begin_layout Plain Layout
2871 For some menu- and widget-labels, there are also shortcut keys that should
2873 Those keys are marked after a `|', and should be translated according to
2874 the words and phrases of the language.
2875 You should also fill also out the information at the beginning of the new
2877 \begin_inset Flex Code
2880 \begin_layout Plain Layout
2886 -file with your email-address, etc., so people know where to reach you with
2887 suggestions and entertaining flames.
2890 \begin_layout Standard
2891 If you are just doing this on your own, then:
2894 \begin_layout Itemize
2896 \begin_inset Flex Code
2899 \begin_layout Plain Layout
2906 This can be done with
2907 \begin_inset Flex Code
2910 \begin_layout Plain Layout
2911 msgfmt -o xx.mo < xx.po
2919 \begin_layout Itemize
2921 \begin_inset Flex Code
2924 \begin_layout Plain Layout
2930 -file to your locale-tree, at the correct directory for application messages
2935 xx, and under the name
2936 \begin_inset Flex Code
2939 \begin_layout Plain Layout
2946 \begin_inset space \thinspace{}
2950 \begin_inset space \space{}
2954 \begin_inset Flex Code
2957 \begin_layout Plain Layout
2958 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2968 \begin_layout Standard
2969 As said, however, it would be best if the new
2970 \begin_inset Flex Code
2973 \begin_layout Plain Layout
2979 -file could be added to the LyX distribution, so others can use it.
2980 Adding it involves making additional changes to LyX.
2981 So send an email to the developers' mailing list if you're interested in
2985 \begin_layout Subsubsection
2989 \begin_layout Standard
2990 Sometimes it turns out that one English message needs to be translated into
2991 different messages in the target language.
2992 One example is the message
2993 \begin_inset Flex Code
2996 \begin_layout Plain Layout
3002 which has the German translation
3010 , depending upon exactly what the English
3011 \begin_inset Quotes eld
3015 \begin_inset Quotes erd
3020 \begin_inset Flex Code
3023 \begin_layout Plain Layout
3029 does not handle such ambiguous translations.
3030 Therefore you have to add some context information to the message: Instead
3032 \begin_inset Flex Code
3035 \begin_layout Plain Layout
3042 \begin_inset Flex Code
3045 \begin_layout Plain Layout
3046 To[[as in 'From format x to format y']]
3052 \begin_inset Flex Code
3055 \begin_layout Plain Layout
3056 To[[as in 'From page x to page y']].
3061 Now the two occurrences of
3062 \begin_inset Flex Code
3065 \begin_layout Plain Layout
3072 \begin_inset Flex Code
3075 \begin_layout Plain Layout
3081 and can be translated correctly to
3092 \begin_layout Standard
3093 Of course the context information needs to be stripped off the original
3094 message when no translation is used.
3095 Therefore you have to put it in double square brackets at the end of the
3096 message (see the example above).
3097 The translation mechanism of LyX ensures that everything in double square
3098 brackets at the end of messages is removed before displaying the message.
3101 \begin_layout Subsection
3102 Translating the documentation.
3105 \begin_layout Standard
3106 The online documentation (in the
3107 \begin_inset Flex MenuItem
3110 \begin_layout Plain Layout
3116 -menu) can (and should!) be translated.
3117 If there are translated versions of the documentation available
3121 \begin_layout Plain Layout
3122 As of March 2008, at least some of the documents have been translated into
3123 fourteen languages, with the Tutorial available in a few more.
3128 and the locale is set accordingly, these will be used automagically by
3130 LyX looks for translated versions as
3131 \begin_inset Flex Code
3134 \begin_layout Plain Layout
3135 LyXDir/doc/xx/DocName.lyx
3141 \begin_inset Flex Code
3144 \begin_layout Plain Layout
3150 is the code for the language currently in use.
3151 If there are no translated documents, the default English versions will
3153 Note that the translated versions must have the same filenames (
3154 \begin_inset Flex Code
3157 \begin_layout Plain Layout
3163 above) as the original.
3164 If you feel up to translating the documentation (an excellent way to proof-read
3165 the original documentation by the way!), there are a few things you should
3169 \begin_layout Itemize
3170 Check out the documentation translation web page at
3171 \begin_inset CommandInset href
3173 name "http://www.lyx.org/Translation"
3174 target "http://www.lyx.org/Translation"
3179 That way, you can find out which (if any) documents have already been translate
3180 d into your language.
3181 You can also find out who (if anyone) is organizing the effort to translate
3182 the documentation into your language.
3183 If no one is organizing the effort, please let us know that you're interested.
3186 \begin_layout Standard
3187 Once you get to actually translating, here's a few hints for you that may
3191 \begin_layout Itemize
3192 Join the documentation team! There is information on how to do that in
3193 \begin_inset Flex Code
3196 \begin_layout Plain Layout
3203 \begin_inset Flex MenuItem
3206 \begin_layout Plain Layout
3207 Help\SpecialChar \menuseparator
3213 ), which by the way is the first document you should translate.
3216 \begin_layout Itemize
3217 Learn the typographic conventions for the language you are translating to.
3218 Typography is an ancient art and over the centuries, a great variety of
3219 conventions have developed throughout different parts of the world.
3220 Also study the professional terminology amongst typographers in your country.
3221 Inventing your own terminology will only confuse the users.
3224 (Warning! Typography is addictive!)
3227 \begin_layout Itemize
3228 Make a copy of the document.
3229 This will be your working copy.
3230 You can use this as your personal translated help-file by placing it in
3232 \begin_inset Flex Code
3235 \begin_layout Plain Layout
3244 \begin_layout Itemize
3245 Sometimes the original document (from the LyX-team) will be updated.
3246 Use the source viewer at
3247 \begin_inset CommandInset href
3249 name "http://www.lyx.org/trac/timeline"
3250 target "http://www.lyx.org/trac/timeline"
3254 to see what has been changed.
3255 That way you can easily see which parts of the translated document need
3259 \begin_layout Standard
3260 If you ever find an error in the original document, fix it and notify the
3261 rest of the documentation team of the changes! (You didn't forget to join
3262 the documentation team, did you?)
3265 \begin_layout Standard
3266 \begin_inset Branch OutDated
3269 \begin_layout Section
3270 International Keyboard Support
3273 \begin_layout Standard
3276 [Editor's Note: The following section is by
3284 It needs to be fixed to conform to the new Documentation Style sheet and
3285 to make use of the new v1.0 features.
3286 The whole thing also needs to be merged with the section following it.-jw
3287 It may also be badly out of date.-rh (2008)]
3290 \begin_layout Subsection
3291 Defining Own Keymaps: Keymap File Format
3294 \begin_layout Standard
3295 Let's look at a keyboard definition file a little closer.
3296 It is a plain text file defining
3299 \begin_layout Itemize
3300 key-to-key or key-to-string translations
3303 \begin_layout Itemize
3307 \begin_layout Itemize
3308 dead keys exceptions
3311 \begin_layout Standard
3312 To define key-to-key or key-to-string translation, use this command:
3315 \begin_layout Quotation
3316 \begin_inset Flex Code
3319 \begin_layout Plain Layout
3328 \begin_inset Flex Code
3331 \begin_layout Plain Layout
3340 \begin_layout Standard
3342 \begin_inset Flex Code
3345 \begin_layout Plain Layout
3351 is the key to be translated and
3352 \begin_inset Flex Code
3355 \begin_layout Plain Layout
3361 is the string to be inserted into the document.
3362 To define dead keys, use:
3365 \begin_layout Quotation
3366 \begin_inset Flex Code
3369 \begin_layout Plain Layout
3378 \begin_inset Flex Code
3381 \begin_layout Plain Layout
3390 \begin_layout Standard
3392 \begin_inset Flex Code
3395 \begin_layout Plain Layout
3401 is a keyboard key and
3402 \begin_inset Flex Code
3405 \begin_layout Plain Layout
3412 The following dead keys are supported (shortcut name is in parentheses):
3415 \begin_layout Quotation
3419 \begin_inset space \hfill{}
3425 \begin_layout Quotation
3427 \begin_inset space \hfill{}
3433 \begin_layout Quotation
3435 \begin_inset space \hfill{}
3441 \begin_layout Quotation
3443 \begin_inset space \hfill{}
3449 \begin_layout Quotation
3451 \begin_inset space \hfill{}
3457 \begin_layout Quotation
3459 \begin_inset space \hfill{}
3466 \begin_layout Plain Layout
3478 \begin_layout Quotation
3480 \begin_inset space \hfill{}
3486 \begin_layout Quotation
3488 \begin_inset space \hfill{}
3495 \begin_layout Plain Layout
3507 \begin_layout Quotation
3509 \begin_inset space \hfill{}
3515 \begin_layout Quotation
3517 \begin_inset space \hfill{}
3523 \begin_layout Quotation
3525 \begin_inset space \hfill{}
3532 \begin_layout Plain Layout
3544 \begin_layout Quotation
3546 \begin_inset space \hfill{}
3553 \begin_layout Plain Layout
3565 \begin_layout Quotation
3567 \begin_inset space \hfill{}
3573 \begin_layout Quotation
3574 hungarian umlaut (hug)
3575 \begin_inset space \hfill{}
3581 \begin_layout Quotation
3583 \begin_inset space \hfill{}
3589 \begin_layout Quotation
3591 \begin_inset space \hfill{}
3598 \begin_layout Plain Layout
3610 \begin_layout Standard
3611 Since in many international keyboards there are exceptions to what some
3612 dead keys should do, you can define them using
3615 \begin_layout Quotation
3616 \begin_inset Flex Code
3619 \begin_layout Plain Layout
3627 deadkey key outstring
3630 \begin_layout Standard
3631 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3635 \begin_layout Quotation
3636 \begin_inset Flex Code
3639 \begin_layout Plain Layout
3652 \begin_layout Standard
3653 to make it work correctly.
3654 Also, you have to define as exceptions dead keys over i and j, to remove
3655 the dot from them before inserting an accent mark.
3656 I will change this when the time comes, but so far I haven't had time.
3659 \begin_layout Standard
3660 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3663 \begin_inset Flex Code
3666 \begin_layout Plain Layout
3672 have different meaning.
3674 \begin_inset Flex Code
3677 \begin_layout Plain Layout
3683 marks comments, quotes start and end LaTeX-style commands.
3684 To enter quote, you'll need to use
3685 \begin_inset Flex Code
3688 \begin_layout Plain Layout
3697 \begin_inset Flex Code
3700 \begin_layout Plain Layout
3707 \begin_inset Flex Code
3710 \begin_layout Plain Layout
3721 \begin_layout Standard
3722 If you make a keyboard description file that works for your language, please
3723 mail it to me, so I can include it in the next keymap distribution.
3726 \begin_layout Standard
3727 More keywords will be supported in keymap configuration file in future,
3731 \begin_layout Itemize
3732 \begin_inset Flex Code
3735 \begin_layout Plain Layout
3746 \begin_inset space \hfill{}
3750 \begin_inset Flex Code
3753 \begin_layout Plain Layout
3762 \begin_layout Itemize
3763 \begin_inset Flex Code
3766 \begin_layout Plain Layout
3777 \begin_inset space \hfill{}
3781 \begin_inset Flex Code
3784 \begin_layout Plain Layout
3790 an external keymap translation program
3793 \begin_layout Standard
3794 Also, it should look into
3795 \begin_inset Flex Code
3798 \begin_layout Plain Layout
3804 file for defaults, too (for example, a
3805 \begin_inset Flex Code
3808 \begin_layout Plain Layout
3816 option to include default keyboard).
3824 \begin_layout Section
3825 International Keymap Stuff
3826 \begin_inset CommandInset label
3828 name "sec:International-Keymap-Stuff"
3835 \begin_layout Standard
3836 \begin_inset Note Note
3839 \begin_layout Plain Layout
3840 In doing the revisions on this document in March 2008, I did not look over
3841 this stuff, as I do not understand it.
3842 It would be good if someone else could do so.
3851 \begin_layout Standard
3852 The next two sections describe the
3853 \begin_inset Flex Code
3856 \begin_layout Plain Layout
3865 \begin_inset Flex Code
3868 \begin_layout Plain Layout
3876 file syntax in detail.
3877 These sections should help you design your own key map if the ones provided
3878 do not meet your needs.
3881 \begin_layout Subsection
3885 \begin_layout Standard
3889 \begin_inset Flex Code
3892 \begin_layout Plain Layout
3898 file maps keystrokes to characters or strings.
3899 As the name suggests, it sets a keyboard mapping.
3901 \begin_inset Flex Code
3904 \begin_layout Plain Layout
3915 \begin_inset Flex Code
3918 \begin_layout Plain Layout
3933 \begin_inset Flex Code
3936 \begin_layout Plain Layout
3949 \begin_inset Flex Code
3952 \begin_layout Plain Layout
3961 \begin_inset Flex Code
3964 \begin_layout Plain Layout
3972 are described in this section.
3975 \begin_layout Labeling
3976 \labelwidthstring 00.00.0000
3977 \begin_inset Flex Code
3980 \begin_layout Plain Layout
3988 Map a character to a string
3991 \begin_layout LyX-Code
4006 \begin_layout Standard
4039 the double-quote (")
4056 must be escaped with a preceding backslash (
4067 \begin_layout Standard
4069 \begin_inset Flex MenuItem
4072 \begin_layout Plain Layout
4080 statement to cause the symbol
4081 \begin_inset Flex MenuItem
4084 \begin_layout Plain Layout
4092 to be output for the keystroke
4093 \begin_inset Flex MenuItem
4096 \begin_layout Plain Layout
4107 \begin_layout LyX-Code
4113 \begin_layout Labeling
4114 \labelwidthstring 00.00.0000
4115 \begin_inset Flex Code
4118 \begin_layout Plain Layout
4126 Specify an accent character
4129 \begin_layout LyX-Code
4138 \begin_layout Standard
4139 This will make the cha
4177 This is the dead key
4181 \begin_layout Plain Layout
4188 refers to a key that does not produce a character by itself, but when followed
4189 with another key, produces the desired accent character.
4190 For example, a German characte
4192 r with an umlaut like
4202 can be produced in this manner.
4211 \begin_layout Standard
4224 and then another key not in
4241 followed by the other, not allowed key, as output.
4245 \begin_inset Flex MenuItem
4248 \begin_layout Plain Layout
4256 cancels a dead key, so if
4267 \begin_inset Flex MenuItem
4270 \begin_layout Plain Layout
4279 , the cursor will not go one position backwards but will instead cancel
4295 might have had on the next keystroke.
4299 \begin_layout Standard
4300 The following example specifies that the character ' is to be an acute accent,
4301 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4304 \begin_layout LyX-Code
4307 kmod ' acute aeiouAEIOU
4310 \begin_layout Labeling
4311 \labelwidthstring 00.00.0000
4312 \begin_inset Flex Code
4315 \begin_layout Plain Layout
4321 Specify an exception to the accent character
4324 \begin_layout LyX-Code
4333 \begin_layout Standard
4334 This defines an exce
4375 have been assigned a keystroke with a previous
4378 \begin_inset Flex Code
4381 \begin_layout Plain Layout
4405 must not belong in the
4452 If such a declaration does not exist in
4460 \begin_inset Flex Code
4463 \begin_layout Plain Layout
4497 \begin_inset Flex Code
4500 \begin_layout Plain Layout
4514 \begin_layout Standard
4515 The following command produces causes äi to be produced when you enter acute-i
4519 \begin_layout LyX-Code
4533 \begin_layout Labeling
4534 \labelwidthstring 00.00.0000
4535 \begin_inset Flex Code
4538 \begin_layout Plain Layout
4544 Combine two accent characters
4547 \begin_layout LyX-Code
4553 accent1 accent2 allowed
4556 \begin_layout Standard
4557 This one is getting pretty esoteric.
4558 It allows you to combine the effect
4614 \begin_inset Flex Code
4617 \begin_layout Plain Layout
4645 \begin_layout Standard
4646 Consider this example from the
4647 \begin_inset Flex Code
4650 \begin_layout Plain Layout
4661 \begin_layout LyX-Code
4664 kmod ; acute aeioyvhAEIOYVH
4668 kcomb acute umlaut iyIY
4671 \begin_layout Standard
4672 This allows you to press
4673 \begin_inset Flex MenuItem
4676 \begin_layout Plain Layout
4684 and get the effect of
4685 \begin_inset Flex Code
4688 \begin_layout Plain Layout
4707 in this case cancels the last dead key, so if you press
4708 \begin_inset Flex MenuItem
4711 \begin_layout Plain Layout
4720 \begin_inset Flex Code
4723 \begin_layout Plain Layout
4736 \begin_layout Subsection
4740 \begin_layout Standard
4742 \begin_inset Flex Code
4745 \begin_layout Plain Layout
4753 mapping is performed, a
4754 \begin_inset Flex Code
4757 \begin_layout Plain Layout
4767 file maps the strings that the symbols generate to characters in the current
4769 The LyX distribution currently includes at least the
4770 \begin_inset Flex Code
4773 \begin_layout Plain Layout
4782 \begin_inset Flex Code
4785 \begin_layout Plain Layout
4796 \begin_layout Standard
4798 \begin_inset Flex Code
4801 \begin_layout Plain Layout
4809 file is a sequence of declarations of the form
4812 \begin_layout LyX-Code
4825 \begin_layout Standard
4826 For example, in order to map
4827 \begin_inset Flex MenuItem
4830 \begin_layout Plain Layout
4840 to the corresponding character in the iso-8859-1 set (233), the following
4844 \begin_layout LyX-Code
4852 \begin_layout Standard
4854 \begin_inset Flex Code
4857 \begin_layout Plain Layout
4866 \begin_inset Flex Code
4869 \begin_layout Plain Layout
4887 the same character can apply to more than one string.
4889 \begin_inset Flex Code
4892 \begin_layout Plain Layout
4903 \begin_layout LyX-Code
4915 \begin_inset Newline newline
4931 \begin_layout Standard
4932 If LyX cannot find a mapping for the string produced by the keystroke or
4933 a deadkey sequence, it will check if it looks like an accented char and
4934 try to draw an accent over the character on screen.
4937 \begin_layout Subsection
4941 \begin_layout Standard
4942 There is a second way to add support for international characters through
4943 so-called dead-keys.
4944 A dead-key works in combination with a letter to produce an accented character.
4945 Here, we'll explain how to create a really simple dead-key to illustrate
4949 \begin_layout Standard
4950 Suppose you happen to need the circumflex character,
4951 \begin_inset Quotes eld
4955 \begin_inset Quotes erd
4960 \begin_inset Flex MenuItem
4963 \begin_layout Plain Layout
4970 \begin_inset space ~
4974 \begin_inset Flex MenuItem
4977 \begin_layout Plain Layout
4983 ] to the LyX command
4984 \begin_inset Flex Code
4987 \begin_layout Plain Layout
4994 \begin_inset Flex Code
4997 \begin_layout Plain Layout
5004 Now, whenever you type the
5005 \begin_inset Flex MenuItem
5008 \begin_layout Plain Layout
5014 -key followed by a letter, that letter will have a circumflex accent on
5016 For example, the sequence
5017 \begin_inset Quotes eld
5021 \begin_inset Flex MenuItem
5024 \begin_layout Plain Layout
5031 \begin_inset Quotes erd
5034 produces the letter:
5035 \begin_inset Quotes eld
5039 \begin_inset Quotes erd
5043 If you tried to type
5044 \begin_inset Quotes eld
5048 \begin_inset Flex MenuItem
5051 \begin_layout Plain Layout
5058 \begin_inset Quotes erd
5061 , however, LyX will complain with a beep, since a
5062 \begin_inset Quotes eld
5066 \begin_inset Flex MenuItem
5069 \begin_layout Plain Layout
5076 \begin_inset Quotes erd
5079 never takes a circumflex accent.
5081 \begin_inset Flex MenuItem
5084 \begin_layout Plain Layout
5090 after a dead-key produces the bare-accent.
5091 Please note this last point! If you bind a key to a dead-key, you'll need
5092 to rebind the character on that key to yet another key.
5094 \begin_inset Flex MenuItem
5097 \begin_layout Plain Layout
5103 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5106 \begin_layout Standard
5107 One common way to bind dead-keys is to use
5108 \begin_inset Flex MenuItem
5111 \begin_layout Plain Layout
5118 \begin_inset Flex MenuItem
5121 \begin_layout Plain Layout
5128 \begin_inset Flex MenuItem
5131 \begin_layout Plain Layout
5137 in combination with an accent, like
5138 \begin_inset Quotes eld
5142 \begin_inset Flex MenuItem
5145 \begin_layout Plain Layout
5152 \begin_inset Quotes erd
5156 \begin_inset Quotes eld
5160 \begin_inset Flex MenuItem
5163 \begin_layout Plain Layout
5170 \begin_inset Quotes erd
5174 \begin_inset Quotes eld
5178 \begin_inset Flex MenuItem
5181 \begin_layout Plain Layout
5188 \begin_inset Quotes erd
5192 Another way involves using
5193 \begin_inset Flex Code
5196 \begin_layout Plain Layout
5203 \begin_inset Flex Code
5206 \begin_layout Plain Layout
5212 to set up the special
5213 \begin_inset Flex Code
5216 \begin_layout Plain Layout
5224 \begin_inset Flex Code
5227 \begin_layout Plain Layout
5233 acts in some ways just like
5234 \begin_inset Flex MenuItem
5237 \begin_layout Plain Layout
5243 and permits you to bind keys to accented characters.
5244 You can also turn keys into dead-keys by binding them to something like
5246 \begin_inset Flex Code
5249 \begin_layout Plain Layout
5255 and then binding this symbolic key to the corresponding LyX command.
5259 \begin_layout Plain Layout
5264 : This is exactly what I do in my
5265 \begin_inset Flex Code
5268 \begin_layout Plain Layout
5275 \begin_inset Flex Code
5278 \begin_layout Plain Layout
5286 \begin_inset Flex MenuItem
5289 \begin_layout Plain Layout
5291 \begin_inset space ~
5300 \begin_inset Flex Code
5303 \begin_layout Plain Layout
5309 and a bunch of these
5310 \begin_inset Quotes eld
5314 \begin_inset Flex Code
5317 \begin_layout Plain Layout
5324 \begin_inset Quotes erd
5327 symbolic keys bound such things as
5328 \begin_inset Flex MenuItem
5331 \begin_layout Plain Layout
5333 \begin_inset space ~
5342 \begin_inset Flex MenuItem
5345 \begin_layout Plain Layout
5347 \begin_inset space ~
5356 This is how I produce my accented characters.
5361 You can make just about anything into the
5362 \begin_inset Flex Code
5365 \begin_layout Plain Layout
5372 \begin_inset Flex MenuItem
5375 \begin_layout Plain Layout
5381 keys, a spare function key, etc.
5382 As for the LyX commands that produce accents, check the entry for
5383 \begin_inset Flex Code
5386 \begin_layout Plain Layout
5397 You'll find the complete list there.
5400 \begin_layout Subsection
5401 Saving your Language Configuration
5404 \begin_layout Standard
5405 You can edit your preferences so that your desired language environment
5406 is automatically configured when LyX starts up, via the
5407 \begin_inset Flex MenuItem
5410 \begin_layout Plain Layout
5411 Edit\SpecialChar \menuseparator
5420 \begin_layout Chapter
5421 Installing New Document Classes, Layouts, and Templates
5422 \begin_inset CommandInset label
5424 name "cha:Installing-New-Document"
5429 \begin_inset Argument 1
5432 \begin_layout Plain Layout
5433 Installing New Document Classes
5441 \begin_layout Standard
5442 In this chapter, we describe the procedures for creating and installing
5443 new LyX layout and template files, as well as offer a refresher on correctly
5444 installing new LaTeX document classes.
5448 \begin_layout Standard
5449 First, let us a say a few words about how one ought to think about the relation
5450 between LyX and LaTeX.
5451 The thing to understand is that, in a certain sense, LyX doesn't know anything
5453 Indeed, from LyX's point of view, LaTeX is just one of several
5454 \begin_inset Quotes eld
5458 \begin_inset Quotes erd
5461 in which it is capable of producing output.
5462 Other such formats are DocBook, plaintext, and XHTML.
5463 LaTeX is, of course, a particularly important format, but very little of
5464 the information LyX has about LaTeX is actually contained in the program
5469 \begin_layout Plain Layout
5470 Some commands are sufficiently complex that they are
5471 \begin_inset Quotes eld
5475 \begin_inset Quotes erd
5479 But the developers generally regard this as a Bad Thing.
5484 Rather, that information, even for the standard classes like
5485 \begin_inset Flex Code
5488 \begin_layout Plain Layout
5494 , is contained in `layout files'.
5495 Similarly, LyX itself does not know much about DocBook or XHTML.
5496 What it knows is contained in layout files.
5499 \begin_layout Standard
5500 You can think of the layout file for a given document class as a translation
5501 manual between LyX constructs---paragraphs with their corresponding styles,
5502 certain sorts of insets, etc---and the corresponding LaTeX, DocBook, or
5504 Almost everything LyX knows about
5505 \begin_inset Flex Code
5508 \begin_layout Plain Layout
5514 , for example, is contained in the file
5515 \begin_inset Flex Code
5518 \begin_layout Plain Layout
5524 and in various other files it includes.
5525 For this reason, anyone intending to write layout files should plan to
5526 study the existing files.
5527 A good place to start is with
5528 \begin_inset Flex Code
5531 \begin_layout Plain Layout
5537 , which is included in
5538 \begin_inset Flex Code
5541 \begin_layout Plain Layout
5548 \begin_inset Flex Code
5551 \begin_layout Plain Layout
5557 , and many of the other layout files for document classes.
5558 This file is where sections and the like are defined:
5559 \begin_inset Flex Code
5562 \begin_layout Plain Layout
5568 tells LyX how paragraphs that are marked with the Section, Subsection,
5569 etc, styles can be translated into corresponding LaTeX, DocBook, and XHTML
5572 \begin_inset Flex Code
5575 \begin_layout Plain Layout
5581 file basically just includes several of these
5582 \begin_inset Flex Code
5585 \begin_layout Plain Layout
5594 \begin_layout Standard
5595 Defining the LyX--LaTeX correspondence is not the only thing layout files
5597 Their other job is to define how the LyX constructs themselves will appear
5599 The fact that layout files have these two jobs is often a source of confusion,
5600 because they are completely separate.
5601 Telling LyX how to translate a certain paragraph style into LaTeX does
5602 not tell LyX how to display it; conversely, telling LyX how to display
5603 a certain paragraph style does not tell LyX how to translate it into LaTeX
5604 (let alone tell LaTeX how to display it).
5605 So, in general, when you define a new LyX construct, you must always do
5606 two quite separate things: (i)
5607 \begin_inset space ~
5610 tell LyX how to translate it into LaTeX and (ii)
5611 \begin_inset space ~
5614 tell LyX how to display it.
5617 \begin_layout Standard
5618 Much the same is true, of course, as regards LyX's other backend formats,
5619 though XHTML is in some ways different, because in that case LyX
5623 able, to some extent, to use information about how it should display a
5624 paragraph on the screen to output information (in the form of CSS) about
5625 how the paragraph should be displayed in a browser.
5626 Even in this case, however, the distinction between what LyX does internally
5627 and how things are rendered externally remains in force, and the two can
5628 be controlled separately.
5630 \begin_inset CommandInset ref
5632 reference "sec:Tags-for-XHTML"
5639 \begin_layout Section
5640 Installing new LaTeX files
5643 \begin_layout Standard
5644 Some installations may not include a LaTeX package or class file that you
5645 would like to use within LyX.
5646 For example, you might need FoilTeX, a package for preparing slides for
5647 overhead projectors.
5648 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5649 a user interface for installing such packages.
5650 For example, with MiKTeX, you start the program
5651 \begin_inset Quotes eld
5655 \begin_inset space ~
5659 \begin_inset Quotes erd
5662 to get a list of available packages.
5663 To install one of them, right click on it or use the corresponding toolbar
5667 \begin_layout Standard
5668 If your LaTeX distribution does not provide such a `package manager', or
5669 if the package is not available from your distribution, then follow these
5670 steps to install it manually:
5673 \begin_layout Enumerate
5674 Get the package from
5675 \begin_inset CommandInset href
5678 target "http://www.ctan.org/"
5685 \begin_layout Enumerate
5686 If the package contains a file with the ending
5687 \begin_inset Quotes eld
5691 \begin_inset Flex Code
5694 \begin_layout Plain Layout
5701 \begin_inset Quotes erd
5704 (is the case for FoilTeX) then open a console, change to the folder of
5705 this file and execute the command
5706 \begin_inset Flex Code
5709 \begin_layout Plain Layout
5716 You have now unpacked the package and have all files to install it.
5717 Most LaTeX-packages are not packed and you can skip this step.
5720 \begin_layout Enumerate
5721 Now you need to decide if the package should be available for all users
5726 \begin_layout Enumerate
5727 On *nix systems (Linux, OSX, etc.), if you want the new package to be available
5728 for all users on your system, then install it in your `local' TeX tree,
5729 otherwise install it in your own `user' TeX tree.
5730 Where these trees should be created, if they do not already exist, depends
5732 To find this out, look in the file
5733 \begin_inset Flex Code
5736 \begin_layout Plain Layout
5746 \begin_layout Plain Layout
5747 This is usually in the directory
5748 \begin_inset Flex Code
5751 \begin_layout Plain Layout
5757 , though you can execute the command
5758 \begin_inset Flex Code
5761 \begin_layout Plain Layout
5772 The location of the `local' TeX tree is defined by the
5773 \begin_inset Flex Code
5776 \begin_layout Plain Layout
5782 variable; this is usually somewhere like
5783 \begin_inset Flex Code
5786 \begin_layout Plain Layout
5787 /usr/local/share/texmf
5793 The location of the `user' TeX tree is defined by
5794 \begin_inset Flex Code
5797 \begin_layout Plain Layout
5804 \begin_inset Flex Code
5807 \begin_layout Plain Layout
5814 (If these variables are not predefined, you have to define them.) You'll
5815 probably need root permissions to create or modify the `local' tree, but
5816 not for your `user' tree.
5817 \begin_inset Newline newline
5820 In general, it is recommended to install in the user tree because your user
5821 will not be modified or even overwritten when you upgrade your system.
5822 It will typically also be backed up together with everything else when
5823 you backup your home directory (which, of course, you do on a regular basis).
5826 \begin_layout Enumerate
5827 On Windows, if you want the new package to be available for all users on
5828 your system, change to the folder where LaTeX is installed and then change
5830 \begin_inset Flex Code
5833 \begin_layout Plain Layout
5844 (For MiKTeX, this would be by default the folder
5845 \begin_inset Flex Code
5848 \begin_layout Plain Layout
5866 \begin_layout Plain Layout
5867 Note that this will be the correct path only on English installations.
5868 On a German one, it would be
5869 \begin_inset Flex Code
5872 \begin_layout Plain Layout
5886 , and similarly for other languages.
5891 Create there a new folder
5892 \begin_inset Flex Code
5895 \begin_layout Plain Layout
5901 and copy all files of the package into it.
5903 \begin_inset Newline newline
5906 If the package should only available for you or you don't have admin permissions
5907 , do the same, but in the local LaTeX folder.
5909 \begin_inset space \thinspace{}
5913 \begin_inset space ~
5916 2.8 under Windows XP, this would be the folder:
5917 \begin_inset Newline newline
5923 \begin_inset Flex Code
5926 \begin_layout Plain Layout
5929 Documents and Settings
5941 \begin_inset Newline newline
5947 \begin_inset Phantom HPhantom
5950 \begin_layout Plain Layout
5961 \begin_inset Flex Code
5964 \begin_layout Plain Layout
5977 \begin_inset Newline newline
5980 On Vista, it would be:
5981 \begin_inset Newline newline
5985 \begin_inset Flex Code
5988 \begin_layout Plain Layout
6014 \begin_layout Enumerate
6015 Now one only need to tell LaTeX that there are new files.
6016 This depends on the used LaTeX-Distribution:
6020 \begin_layout Enumerate
6021 For TeXLive execute the command
6022 \begin_inset Flex Code
6025 \begin_layout Plain Layout
6032 If you installed the package for all users, then you will probably need
6033 to have root permissions for that.
6036 \begin_layout Enumerate
6037 For MiKTeX, if you have installed the package for all users, start the program
6039 \begin_inset Quotes eld
6043 \begin_inset space ~
6047 \begin_inset Quotes erd
6050 and press the button marked
6051 \begin_inset Quotes eld
6055 \begin_inset Quotes erd
6059 Otherwise start the program
6060 \begin_inset Quotes eld
6064 \begin_inset Quotes erd
6071 \begin_layout Enumerate
6072 Finally, you need to tell LyX that there are new packages available.
6073 So, in LyX, use the menu
6074 \begin_inset Flex MenuItem
6077 \begin_layout Plain Layout
6080 \SpecialChar \menuseparator
6086 and then restart LyX.
6089 \begin_layout Standard
6090 Now the package is installed.
6091 In our example, the document class
6092 \begin_inset Flex Code
6095 \begin_layout Plain Layout
6097 \begin_inset space ~
6104 \begin_layout Plain Layout
6116 will now be available under
6117 \begin_inset Flex MenuItem
6120 \begin_layout Plain Layout
6121 Document\SpecialChar \menuseparator
6122 Settings\SpecialChar \menuseparator
6132 \begin_layout Standard
6133 If you would like to use a LaTeX document class that is not even listed
6135 \begin_inset Flex MenuItem
6138 \begin_layout Plain Layout
6139 Document\SpecialChar \menuseparator
6140 Settings\SpecialChar \menuseparator
6146 , then you need to create a `layout' file for it.
6147 That is the topic of the next section.
6150 \begin_layout Section
6151 Types of layout files
6154 \begin_layout Standard
6155 This section describes the various sorts of LyX files that contain layout
6157 These files describe various paragraph and character styles, determining
6158 how LyX should display them and how they should be translated into LaTeX,
6159 DocBook, XHTML, or whatever output format is being used.
6163 \begin_layout Standard
6164 We shall try to provide a thorough description of the process of writing
6166 However, there are so many different types of documents supported even
6167 by just LaTeX that we can't hope to cover every different possibility or
6168 problem you might encounter.
6169 The LyX users' list is frequented by people with lots of experience with
6170 layout design who are willing to share what they've learned, so please
6171 feel free to ask questions there.
6174 \begin_layout Standard
6175 As you prepare to write a new layout, it is extremely helpful to look at
6176 the layouts distributed with LyX.
6177 If you write a LyX layout for a LaTeX document class that might also be
6178 used by others, or write a module that might be useful to others, then
6179 you should consider posting your layout to the
6180 \begin_inset CommandInset href
6182 name "layout section on the LyX wiki"
6183 target "http://wiki.lyx.org/Layouts/Layouts"
6187 or even to the LyX developers' list, so that it might be included in LyX
6192 \begin_layout Plain Layout
6193 Note that LyX is licensed under the General Public License, so any material
6194 that is contributed to LyX must be similarly licensed.
6202 \begin_layout Subsection
6204 \begin_inset CommandInset label
6206 name "sub:Layout-modules"
6213 \begin_layout Standard
6214 We have spoken to this point about `layout files'.
6215 But there are different sorts of files that contain layout information.
6216 Layout files, strictly so called, have the
6217 \begin_inset Flex Code
6220 \begin_layout Plain Layout
6226 extension and provide LyX with information about document classes.
6227 As of LyX 1.6, however, layout information can also be contained in layout
6233 \begin_inset Flex Code
6236 \begin_layout Plain Layout
6243 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6244 some modules—such as the
6245 \begin_inset Flex Code
6248 \begin_layout Plain Layout
6254 module—specifically provide support for one package.
6255 In a sense, layout modules are similar to included
6259 \begin_layout Plain Layout
6260 These can have any extension, but by convention have the
6261 \begin_inset Flex Code
6264 \begin_layout Plain Layout
6276 \begin_inset Flex Code
6279 \begin_layout Plain Layout
6285 —in that modules are not specific to a given document class but may be used
6286 with many different classes.
6287 The difference is that using an included file with
6288 \begin_inset Flex Code
6291 \begin_layout Plain Layout
6297 requires editing that file.
6298 Modules, by contrast, are selected in the
6299 \begin_inset Flex MenuItem
6302 \begin_layout Plain Layout
6303 Document\SpecialChar \menuseparator
6312 \begin_layout Standard
6313 Building modules is the easiest way to get started with layout editing,
6314 since it can be as simple as adding a single new paragraph style or flex
6316 But modules may, in principle, contain anything a layout file can contain.
6319 \begin_layout Standard
6320 After creating a new module and copying it to the
6321 \begin_inset Flex Code
6324 \begin_layout Plain Layout
6330 folder, you will need to reconfigure and then restart LyX for the module
6331 to appear in the menu.
6332 However, changes you make to the module will be seen immediately, if you
6334 \begin_inset Flex MenuItem
6337 \begin_layout Plain Layout
6338 Document\SpecialChar \menuseparator
6344 , highlight something, and then hit
6345 \begin_inset Quotes eld
6349 \begin_inset Quotes erd
6355 It is strongly recommended that you save your work before doing this
6360 it is strongly recommended that you not attempt to edit modules while simultaneo
6361 usly working on actual documents
6364 Though of course the developers strive to keep LyX stable in such situations,
6365 syntax errors and the like in your module file could cause strange behavior.
6368 \begin_layout Subsubsection
6372 \begin_layout Standard
6373 Modules are to LyX as packages are to LaTeX.
6374 Sometimes, however, you find yourself wanting a specific inset or character
6375 style just for one document and writing a module that will also be available
6376 to other documents makes little sense.
6377 What you need is LyX's
6378 \begin_inset Quotes eld
6382 \begin_inset Quotes erd
6388 \begin_layout Standard
6389 You will find it under
6391 Document\SpecialChar \menuseparator
6392 Settings\SpecialChar \menuseparator
6396 The large text box allows you to enter anything that you might enter in
6397 a layout file or module.
6398 You can think of a document's local layout, in fact, as a module that belongs
6400 So, in particular, you must enter a
6401 \begin_inset Flex Code
6404 \begin_layout Plain Layout
6411 Any format is acceptable, but one would normally use the format current
6413 (In LyX 2.0, the current layout format is 35.) You should be aware that local
6414 layout is not supported by versions of LyX prior to 1.6, so you should not
6415 use it if you want to be able to export your document to LyX 1.5 or earlier
6416 (without, that is, losing the local layout information).
6417 If you wish to be able to export to 1.6---local layout is supported in 1.6,
6418 though there is no UI for it---then you should use format 11 and, of course,
6419 use only layout constructs that were available in LyX 1.6.
6422 \begin_layout Standard
6423 When you have entered something in the
6424 \begin_inset Flex Code
6427 \begin_layout Plain Layout
6433 pane, LyX will enable the
6434 \begin_inset Quotes eld
6438 \begin_inset Quotes erd
6441 button at the bottom.
6442 Clicking this button will cause LyX to determine whether what you have
6443 entered is valid layout information for the chosen format.
6444 LyX will report the result but, unfortunately, will not tell you what errors
6445 there might have been.
6446 These will be written to the terminal, however, if LyX is started from
6448 You will not be permitted to save your local layout until you have entered
6452 \begin_layout Standard
6453 The warnings at the end of the previous section apply here, too.
6454 Do not play with local layout while you are actually working, especially
6455 if you have not saved your document.
6456 That said, using local layout with a test document can be a very convenient
6457 way to try out layout ideas, or even to start developing a module.
6460 \begin_layout Subsection
6462 \begin_inset Flex MenuItem
6465 \begin_layout Plain Layout
6474 \begin_layout Standard
6475 There are two situations you are likely to encounter when wanting to support
6476 a new LaTeX document class, involving style (
6477 \begin_inset Flex Code
6480 \begin_layout Plain Layout
6486 ) files and LaTeX2e class (
6487 \begin_inset Flex Code
6490 \begin_layout Plain Layout
6497 Supporting a style file is usually fairly easy.
6498 Supporting a new class file is a bit harder.
6499 We'll discuss the former in this section and the latter in the next.
6500 Similar remarks apply, of course, if you want to support a new DocBook
6504 \begin_layout Standard
6505 The easier case is the one in which your new document class is provided
6506 as a style file that is to be used in conjunction with an already supported
6508 For the sake of the example, we'll assume that the style file is called
6510 \begin_inset Flex MenuItem
6513 \begin_layout Plain Layout
6519 and that it is meant to be used with
6520 \begin_inset Flex MenuItem
6523 \begin_layout Plain Layout
6529 , which is a standard class.
6533 \begin_layout Standard
6534 Start by copying the existing class's layout file into your local directory:
6538 \begin_layout Plain Layout
6539 Of course, which directory is your local directory will vary by platform,
6540 and LyX allows you to specify your local directory on startup, too, using
6542 \begin_inset Flex Code
6545 \begin_layout Plain Layout
6559 \begin_layout LyX-Code
6560 cp report.layout ~/.lyx/layouts/myclass.layout
6563 \begin_layout Standard
6565 \begin_inset Flex Code
6568 \begin_layout Plain Layout
6574 and change the line:
6577 \begin_layout LyX-Code
6580 DeclareLaTeXClass{report}
6583 \begin_layout Standard
6587 \begin_layout LyX-Code
6590 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6593 \begin_layout Standard
6597 \begin_layout LyX-Code
6599 \begin_inset Newline newline
6605 \begin_inset Newline newline
6611 \begin_layout Standard
6612 near the top of the file.
6615 \begin_layout Standard
6616 Start LyX and select
6617 \begin_inset Flex MenuItem
6620 \begin_layout Plain Layout
6621 Tools\SpecialChar \menuseparator
6628 Then restart LyX and try creating a new document.
6630 \begin_inset Flex MenuItem
6633 \begin_layout Plain Layout
6639 " as a document class option in the
6640 \begin_inset Flex MenuItem
6643 \begin_layout Plain Layout
6644 Document\SpecialChar \menuseparator
6651 It is likely that some of the sectioning commands and such in your new
6652 class will work differently from how they worked in the base class—
6653 \begin_inset Flex Code
6656 \begin_layout Plain Layout
6662 in this example—so you can fiddle around with the settings for the different
6663 sections if you wish.
6664 The layout information for sections is contained in
6665 \begin_inset Flex Code
6668 \begin_layout Plain Layout
6674 , but you do not need to copy and change this file.
6675 Instead, you can simply add your changes to your layout file, after the
6677 \begin_inset Flex Code
6680 \begin_layout Plain Layout
6686 , which itself includes
6687 \begin_inset Flex Code
6690 \begin_layout Plain Layout
6697 For example, you might add these lines:
6700 \begin_layout LyX-Code
6704 \begin_layout LyX-Code
6708 \begin_layout LyX-Code
6712 \begin_layout LyX-Code
6716 \begin_layout LyX-Code
6720 \begin_layout Standard
6721 to change the font for chapter headings to sans-serif.
6722 This will override (or, in this case, add to) the existing declaration
6723 for the Chapter style.
6727 \begin_layout Standard
6728 Your new package may also provide commands or environments not present in
6730 In this case, you will want to add these to the layout file.
6732 \begin_inset CommandInset ref
6734 reference "sec:TextClass"
6738 for information on how to do so.
6741 \begin_layout Standard
6743 \begin_inset Flex MenuItem
6746 \begin_layout Plain Layout
6752 can be used with several different document classes, and even if it cannot,
6753 you might find it easiest just to write a module that you can load with
6755 The simplest possible such module would be:
6758 \begin_layout LyX-Code
6761 DeclareLyXModule{My Package}
6764 \begin_layout LyX-Code
6768 \begin_layout LyX-Code
6769 #Support for mypkg.sty.
6772 \begin_layout LyX-Code
6774 \begin_inset Newline newline
6780 \begin_layout LyX-Code
6782 \begin_inset Newline newline
6788 \begin_layout LyX-Code
6790 \begin_inset Newline newline
6796 \begin_inset Newline newline
6802 \begin_layout Standard
6803 A more complex module might modify the behavior of some existing constructs
6804 or define some new ones.
6806 \begin_inset CommandInset ref
6808 reference "sec:TextClass"
6815 \begin_layout Subsection
6817 \begin_inset Flex MenuItem
6820 \begin_layout Plain Layout
6829 \begin_layout Standard
6830 There are two possibilities here.
6831 One is that the class file is itself based upon an existing document class.
6832 For example, many thesis classes are based upon
6833 \begin_inset Flex MenuItem
6836 \begin_layout Plain Layout
6843 To see whether yours is, look for a line like
6846 \begin_layout LyX-Code
6852 \begin_layout Standard
6854 If so, then you may proceed largely as in the previous section, though
6856 \begin_inset Flex Code
6859 \begin_layout Plain Layout
6865 line will be different.
6866 If your new class is
6867 \begin_inset Flex Code
6870 \begin_layout Plain Layout
6876 and it is based upon
6877 \begin_inset Flex Code
6880 \begin_layout Plain Layout
6886 , then the line should read:
6890 \begin_layout Plain Layout
6891 And it will be easiest if you save the file to
6892 \begin_inset Flex Code
6895 \begin_layout Plain Layout
6901 : LyX assumes that the document class has the same name as the layout file.
6910 \begin_layout LyX-Code
6913 DeclareLaTeXClass[thesis,book]{thesis}
6916 \begin_layout Standard
6917 If, on the other hand, the new class is not based upon an existing class,
6918 you will probably have to
6919 \begin_inset Quotes eld
6923 \begin_inset Quotes erd
6927 We strongly suggest copying an existing layout file which uses a similar
6928 LaTeX class and then modifying it, if you can do so.
6929 At least use an existing file as a starting point so you can find out what
6930 items you need to worry about.
6931 Again, the specifics are covered below.
6934 \begin_layout Subsection
6936 \begin_inset CommandInset label
6938 name "sub:Creating-Templates"
6945 \begin_layout Standard
6946 Once you have written a layout file for a new document class, you might
6947 want to consider writing a
6952 A template acts as a kind of tutorial for your layout, showing how it might
6953 be used, though containing dummy content.
6954 You can of course look at the various templates included with LyX for ideas.
6957 \begin_layout Standard
6958 Templates are created just like usual documents: using LyX.
6959 The only difference is that usual documents contain all possible settings,
6960 including the font scheme and the paper size.
6961 Usually a user doesn't want a template to overwrite his preferred settings
6962 for such parameters.
6963 For that reason, the designer of a template should remove the corresponding
6965 \begin_inset Flex Code
6968 \begin_layout Plain Layout
6977 \begin_inset Flex Code
6980 \begin_layout Plain Layout
6988 from the template LyX file.
6989 This can be done with any simple text-editor, for example
6990 \begin_inset Flex Code
6993 \begin_layout Plain Layout
7000 \begin_inset Flex Code
7003 \begin_layout Plain Layout
7013 \begin_layout Standard
7014 Put the edited template files you create in
7015 \begin_inset Flex Code
7018 \begin_layout Plain Layout
7024 , copy the ones you use from the global template directory in
7025 \begin_inset Flex Code
7028 \begin_layout Plain Layout
7034 to the same place, and redefine the template path in the
7035 \begin_inset Flex MenuItem
7038 \begin_layout Plain Layout
7039 Tools\SpecialChar \menuseparator
7040 Preferences\SpecialChar \menuseparator
7049 \begin_layout Standard
7050 Note, by the way, that there is a template which has a particular meaning:
7052 \begin_inset Flex Code
7055 \begin_layout Plain Layout
7062 This template is loaded every time you create a new document with
7063 \begin_inset Flex MenuItem
7066 \begin_layout Plain Layout
7067 File\SpecialChar \menuseparator
7073 in order to provide useful defaults.
7074 To create this template from inside LyX, all you have to do is to open
7075 a document with the correct settings, and use the
7076 \begin_inset Flex MenuItem
7079 \begin_layout Plain Layout
7080 Save as Document Defaults
7088 \begin_layout Subsection
7089 Upgrading old layout files
7092 \begin_layout Standard
7093 The format of layout files changes with each LyX release, so old layout
7094 files need to be converted to the new format.
7095 This process has been automated since LyX 1.4: If LyX reads a layout file
7096 in an older format, it automatically calls the script
7097 \begin_inset Flex Code
7100 \begin_layout Plain Layout
7106 to convert it to a temporary file in current format.
7107 The original file is left untouched.
7108 If you use the layout file often, then, you may want to convert it permanently,
7109 so that LyX does not have to do so itself every time.
7110 To do this, you can call the converter manually:
7113 \begin_layout LyX-Code
7114 mv myclass.layout myclass.old
7117 \begin_layout LyX-Code
7118 python LyXDir/scripts/layout2layout.py myclass.old myclass.layout
7121 \begin_layout Standard
7123 \begin_inset Flex Code
7126 \begin_layout Plain Layout
7132 with the name of your LyX system directory, of course.
7135 \begin_layout Standard
7136 Note that manual conversion does not affect included files, so these will
7137 have to be converted separately.
7140 \begin_layout Section
7141 \begin_inset CommandInset label
7143 name "sec:TextClass"
7147 The layout file format
7150 \begin_layout Standard
7151 When it's finally time to get your hands dirty and create or edit your own
7152 layout file, the following sections describe what you're up against.
7153 Our advice is to go slowly, save and test often, listen to soothing music,
7154 and enjoy one or two of your favorite adult beverages; more if you are
7155 getting particularly stuck.
7156 It's really not that hard, except that the multitude of options can become
7157 overwhelming if you try to do too much in one sitting.
7158 Go have another adult beverage, just for good measure.
7161 \begin_layout Standard
7162 Note that all the tags used in layout files are case-insensitive.
7164 \begin_inset Flex Code
7167 \begin_layout Plain Layout
7174 \begin_inset Flex Code
7177 \begin_layout Plain Layout
7184 \begin_inset Flex Code
7187 \begin_layout Plain Layout
7193 are really the same tag.
7194 The possible values are printed in brackets after the feature's name.
7195 The default value if a feature isn't specified inside a text class-description
7197 \begin_inset Flex Code
7200 \begin_layout Plain Layout
7209 If the argument has a data type like
7210 \begin_inset Quotes eld
7214 \begin_inset Quotes erd
7218 \begin_inset Quotes eld
7222 \begin_inset Quotes erd
7225 , the default is shown like this:
7226 \begin_inset Flex Code
7229 \begin_layout Plain Layout
7240 \begin_layout Subsection
7241 The document class declaration
7242 \change_inserted -712698321 1349766602
7248 \begin_layout Standard
7249 Lines in a layout file which begin with
7250 \begin_inset Flex Code
7253 \begin_layout Plain Layout
7260 There is one exception to this rule.
7262 \begin_inset Flex Code
7265 \begin_layout Plain Layout
7271 files should begin with
7272 \change_deleted -712698321 1349766533
7276 \change_inserted -712698321 1349766536
7282 \begin_layout LyX-Code
7285 #% Do not delete the line below; configure depends on this
7288 \begin_layout LyX-Code
7294 \change_deleted -712698321 1349766193
7296 \change_inserted -712698321 1349766201
7297 Article (Standard Class)
7300 \change_inserted -712698321 1349766538
7304 \begin_layout LyX-Code
7306 \change_inserted -712698321 1349766581
7311 DeclareCategory{Articles}
7316 \begin_layout Standard
7318 \change_inserted -712698321 1349766695
7322 \change_inserted -712698321 1349766626
7326 \change_deleted -712698321 1349766628
7328 \change_inserted -712698321 1349766628
7331 used when you (re)configure LyX.
7332 The layout file is read by the LaTeX script
7333 \begin_inset Flex Code
7336 \begin_layout Plain Layout
7342 , in a special mode where
7343 \begin_inset Flex Code
7346 \begin_layout Plain Layout
7353 The first line is just a LaTeX comment,
7354 \change_deleted -712698321 1349766656
7357 the second one contains the
7358 \change_inserted -712698321 1349766650
7361 declaration of the text class
7362 \change_inserted -712698321 1349766689
7363 , and the third line contains the optional classification of the class
7366 If these lines appear in a file named
7367 \begin_inset Flex Code
7370 \begin_layout Plain Layout
7376 , then they define a text class of name
7377 \begin_inset Flex Code
7380 \begin_layout Plain Layout
7386 (the name of the layout file) which uses the LaTeX document class
7387 \begin_inset Flex Code
7390 \begin_layout Plain Layout
7396 (the default is to use the same name as the layout).
7398 \begin_inset Quotes eld
7402 \change_deleted -712698321 1349766253
7404 \change_inserted -712698321 1349766260
7405 Article (Standard Class)
7408 \begin_inset Quotes erd
7411 that appears above is used as a description of the text class in the
7412 \begin_inset Flex MenuItem
7415 \begin_layout Plain Layout
7416 Document\SpecialChar \menuseparator
7424 \change_inserted -712698321 1349767097
7426 \begin_inset Quotes eld
7430 \begin_inset Quotes erd
7433 in the example) is also used in the
7434 \begin_inset Flex MenuItem
7437 \begin_layout Plain Layout
7439 \change_inserted -712698321 1349766801
7440 Document\SpecialChar \menuseparator
7446 dialog: the text classes are grouped by these categories (which are usually
7447 genres, so typical categories are
7448 \begin_inset Quotes eld
7452 \begin_inset Quotes erd
7456 \begin_inset Quotes eld
7460 \begin_inset Quotes erd
7464 \begin_inset Quotes eld
7468 \begin_inset Quotes erd
7472 \begin_inset Quotes eld
7476 \begin_inset Quotes erd
7480 \begin_inset Quotes eld
7484 \begin_inset Quotes erd
7488 \begin_inset Quotes eld
7492 \begin_inset Quotes erd
7496 If no category has been declared, the class will be put in the
7497 \begin_inset Quotes eld
7501 \begin_inset Quotes erd
7509 \begin_layout Standard
7510 Let's assume that you wrote your own text class that uses the
7511 \begin_inset Flex Code
7514 \begin_layout Plain Layout
7520 document class, but where you changed the appearance of the section headings.
7521 If you put it in a file
7522 \begin_inset Flex Code
7525 \begin_layout Plain Layout
7531 , the header of this file should be:
7534 \begin_layout LyX-Code
7537 #% Do not delete the line below; configure depends on this
7540 \begin_layout LyX-Code
7545 DeclareLaTeXClass[article]{
7546 \change_deleted -712698321 1349766303
7548 \change_inserted -712698321 1349766303
7552 \change_deleted -712698321 1349766338
7554 \change_inserted -712698321 1349766338
7558 \change_deleted -712698321 1349766340
7560 \change_inserted -712698321 1349766340
7564 \change_deleted -712698321 1349766343
7566 \change_inserted -712698321 1349766343
7570 \change_inserted -712698321 1349767223
7574 \begin_layout LyX-Code
7576 \change_inserted -712698321 1349767223
7581 DeclareCategory{Articles}
7586 \begin_layout Standard
7587 This declares a text class
7588 \begin_inset Flex Code
7591 \begin_layout Plain Layout
7597 , associated with the LaTeX document class
7598 \begin_inset Flex Code
7601 \begin_layout Plain Layout
7608 \begin_inset Quotes eld
7612 \change_deleted -712698321 1349766329
7614 \change_inserted -712698321 1349766329
7618 \change_deleted -712698321 1349766347
7620 \change_inserted -712698321 1349766347
7624 \change_deleted -712698321 1349766350
7626 \change_inserted -712698321 1349766350
7630 \change_deleted -712698321 1349766352
7632 \change_inserted -712698321 1349766352
7636 \begin_inset Quotes erd
7640 If your text class depends on several packages, you can declare it as:
7643 \begin_layout LyX-Code
7646 #% Do not delete the line below; configure depends on this
7649 \begin_layout LyX-Code
7654 DeclareLaTeXClass[article,foo.sty]{
7655 \change_deleted -712698321 1349766366
7657 \change_inserted -712698321 1349766366
7661 \change_deleted -712698321 1349766369
7663 \change_inserted -712698321 1349766369
7667 \change_deleted -712698321 1349766371
7669 \change_inserted -712698321 1349766371
7673 \change_deleted -712698321 1349766374
7675 \change_inserted -712698321 1349766374
7679 \change_inserted -712698321 1349767240
7683 \begin_layout LyX-Code
7685 \change_inserted -712698321 1349767240
7690 DeclareCategory{Articles}
7695 \begin_layout Standard
7696 This indicates that your text class uses the
7697 \begin_inset Flex Code
7700 \begin_layout Plain Layout
7707 Finally, it is also possible to declare classes for DocBook code.
7708 Typical declarations will look like:
7711 \begin_layout LyX-Code
7714 #% Do not delete the line below; configure depends on this
7717 \begin_layout LyX-Code
7722 DeclareDocBookClass[article]{SGML (DocBook
7723 \change_deleted -712698321 1349766387
7725 \change_inserted -712698321 1349766387
7729 \change_inserted -712698321 1349767247
7733 \begin_layout LyX-Code
7735 \change_inserted -712698321 1349767302
7740 DeclareCategory{Articles (DocBook)}
7745 \begin_layout Standard
7746 Note that these declarations can also be given an optional parameter declaring
7747 the name of the document class (but not a list).
7750 \begin_layout Standard
7751 So, to be as explicit as possible, the form of the layout declaration is:
7754 \begin_layout LyX-Code
7759 DeclareLaTeXClass[class,package.sty]{layout description}
7760 \change_inserted -712698321 1349767329
7764 \begin_layout LyX-Code
7766 \change_inserted -712698321 1349767339
7771 DeclareCategory{category}
7776 \begin_layout Standard
7777 The class need only be specified if the name of the LaTeX class file and
7778 the name of the layout file are different or if there are packages to load.
7779 If the name of the class file is not specified, then LyX will simply assume
7780 that it is the same as the name of the layout file.
7783 \begin_layout Standard
7784 When the text class has been modified to your taste, all you have to do
7785 is to copy it either to
7786 \begin_inset Flex Code
7789 \begin_layout Plain Layout
7796 \begin_inset Flex Code
7799 \begin_layout Plain Layout
7806 \begin_inset Flex MenuItem
7809 \begin_layout Plain Layout
7810 Tools\SpecialChar \menuseparator
7816 , exit LyX and restart.
7817 Then your new text class should be available along with the others.
7820 \begin_layout Standard
7821 Once the layout file is installed, you can edit it and see your changes
7822 without having to reconfigure or to restart LyX.
7827 \begin_layout Plain Layout
7828 In versions of LyX prior to 1.6, this was not true.
7829 As a result, editing layout files was very time consuming, since you had
7830 constantly to restart LyX to see changes.
7835 You can force a reload of the current layout by using the LyX function
7837 \begin_inset Flex MenuItem
7840 \begin_layout Plain Layout
7847 There is no default binding for this function—though, of course, you can
7848 bind it to a key yourself.
7849 But you will normally use this function simply by entering it in the mini-buffe
7854 \begin_layout Standard
7860 \begin_inset Flex MenuItem
7863 \begin_layout Plain Layout
7869 is very much an `advanced feature'.
7874 recommended that you save your work before using this function.
7879 recommended that you not attempt to edit layout information while simultaneousl
7880 y working on a document that you care about.
7881 Use a test document.
7882 Syntax errors and the like in your layout file could cause peculiar behavior.
7883 In particular, such errors could cause LyX to regard the current layout
7884 as invalid and to attempt to switch to some other layout.
7888 \begin_layout Plain Layout
7889 Really bad syntax errors may even caused LyX to exit.
7890 This is because certain sorts of errors may make LyX unable to read
7900 The LyX team strives to keep LyX stable in such situations, but safe is
7905 \begin_layout Plain Layout
7906 While we're giving advice: make regular backups.
7907 And be nice to your mother.
7915 \begin_layout Subsection
7916 The Module declaration
7919 \begin_layout Standard
7920 A module must begin with a line like the following:
7923 \begin_layout LyX-Code
7926 DeclareLyXModule[endnotes.sty]{Endnotes}
7929 \begin_layout Standard
7930 The mandatory argument, in curly brackets, is the name of the module, as
7932 \begin_inset Flex MenuItem
7935 \begin_layout Plain Layout
7936 Document\SpecialChar \menuseparator
7937 Settings\SpecialChar \menuseparator
7944 The argument in square brackets is optional: It declares any LaTeX packages
7945 on which the module depends.
7946 Please note that only packages about which LyX knows should be listed in
7947 the square brackets.
7951 \begin_layout Plain Layout
7952 The list of such packages is documented only in the source code.
7957 LyX will not check for arbitrary packages.
7958 It is also possible to use the form
7959 \begin_inset Flex MenuItem
7962 \begin_layout Plain Layout
7968 as an optional argument, which declares that the module can only be used
7969 when there exists a conversion chain between the formats `
7970 \begin_inset Flex Code
7973 \begin_layout Plain Layout
7980 \begin_inset Flex Code
7983 \begin_layout Plain Layout
7992 \begin_layout Standard
7993 The module declaration should then be followed by lines like the following
7997 \begin_layout Plain Layout
7998 Preferably in English if the module should be published with LyX.
7999 This description will appear in the list of messages to be translated and
8000 will be thus translated with the next interface update.
8008 \begin_layout LyX-Code
8012 \begin_layout LyX-Code
8013 #Adds an endnote command, in addition to footnotes.
8017 \begin_layout LyX-Code
8018 #You will need to add
8020 theendnotes in TeX code where you
8023 \begin_layout LyX-Code
8024 #want the endnotes to appear.
8028 \begin_layout LyX-Code
8032 \begin_layout LyX-Code
8033 #Requires: somemodule | othermodule
8036 \begin_layout LyX-Code
8037 #Excludes: badmodule
8040 \begin_layout Standard
8041 The description is used in
8042 \begin_inset Flex MenuItem
8045 \begin_layout Plain Layout
8046 Document\SpecialChar \menuseparator
8047 Settings\SpecialChar \menuseparator
8053 to provide the user with information about what the module does.
8055 \begin_inset Flex Code
8058 \begin_layout Plain Layout
8064 line is used to identify other modules with which this one must be used;
8066 \begin_inset Flex Code
8069 \begin_layout Plain Layout
8075 line is used to identify modules with which this one may not be used.
8076 Both are optional, and, as shown, multiple modules should be separated
8077 with the pipe symbol: |.
8078 Note that the required modules are treated disjunctively:
8082 of the required modules must be used.
8087 excluded module may be used.
8088 Note that modules are identified here by their
8093 \begin_inset Flex Code
8096 \begin_layout Plain Layout
8104 \begin_inset Flex Code
8107 \begin_layout Plain Layout
8114 \begin_inset Flex Code
8117 \begin_layout Plain Layout
8126 \begin_layout Subsection
8130 \begin_layout Standard
8131 The first non-comment line of any layout file, included file, or module
8136 contain the file format number:
8139 \begin_layout Description
8140 \begin_inset Flex Code
8143 \begin_layout Plain Layout
8150 \begin_inset Flex Code
8153 \begin_layout Plain Layout
8159 ] The format of the layout file.
8162 \begin_layout Standard
8163 This tag was introduced with LyX 1.4.0.
8164 Layout files from LyX 1.3.x and earlier don't have an explicit file format
8165 and are considered to be of format 1.
8166 The format for the present version of LyX is format 21.
8167 But each version of LyX is capable of reading earlier versions' layout
8168 files, just as they are capable of reading files produced by earlier versions
8170 There is, however, no provision for converting to earlier formats.
8171 So LyX 1.6.x will not read layout files in format 21 but only files in format
8175 \begin_layout Subsection
8176 \begin_inset CommandInset label
8178 name "sub:General-text-class"
8182 General text class parameters
8185 \begin_layout Standard
8186 These are general parameters that govern the behavior of an entire document
8192 mean that they must appear in
8193 \begin_inset Flex Code
8196 \begin_layout Plain Layout
8202 files rather than in modules.
8203 A module can contain any layout tag.)
8206 \begin_layout Description
8207 \begin_inset Flex Code
8210 \begin_layout Plain Layout
8216 Adds information that will be output in the
8217 \begin_inset Flex Code
8220 \begin_layout Plain Layout
8226 block when this document class is output to XHTML.
8227 Typically, this would be used to output CSS style information, but it can
8228 be used for anything that can appear in
8229 \begin_inset Flex Code
8232 \begin_layout Plain Layout
8240 \begin_inset Quotes eld
8244 \begin_inset Flex Code
8247 \begin_layout Plain Layout
8254 \begin_inset Quotes erd
8260 \begin_layout Description
8261 \begin_inset Flex Code
8264 \begin_layout Plain Layout
8270 Adds CSS styling information.
8271 This will either be output in a
8272 \begin_inset Quotes eld
8276 \begin_inset Flex Code
8279 \begin_layout Plain Layout
8286 \begin_inset Quotes erd
8289 block or, if the user has so chosen, to a separate CSS file.Must end with
8291 \begin_inset Quotes eld
8295 \begin_inset Flex Code
8298 \begin_layout Plain Layout
8305 \begin_inset Quotes erd
8311 \begin_layout Description
8312 \begin_inset Flex Code
8315 \begin_layout Plain Layout
8321 Adds information to the document preamble.
8323 \begin_inset Newline newline
8327 \begin_inset Quotes eld
8331 \begin_inset Flex Code
8334 \begin_layout Plain Layout
8341 \begin_inset Quotes erd
8347 \begin_layout Description
8348 \begin_inset Flex Code
8351 \begin_layout Plain Layout
8357 Defines formats for use in the display of bibliographic information.
8359 \begin_inset CommandInset ref
8361 reference "sub:Citation-format-description"
8367 \begin_inset Quotes eld
8371 \begin_inset Flex Code
8374 \begin_layout Plain Layout
8381 \begin_inset Quotes erd
8387 \begin_layout Description
8388 \begin_inset Flex Code
8391 \begin_layout Plain Layout
8397 Describes various global options supported by the document class.
8399 \begin_inset space ~
8403 \begin_inset CommandInset ref
8405 reference "sub:ClassOptions"
8411 \begin_inset Quotes eld
8415 \begin_inset Flex Code
8418 \begin_layout Plain Layout
8425 \begin_inset Quotes erd
8431 \begin_layout Description
8432 \begin_inset Flex Code
8435 \begin_layout Plain Layout
8442 \begin_inset Flex Code
8445 \begin_layout Plain Layout
8454 \begin_inset Flex Code
8457 \begin_layout Plain Layout
8463 ] Whether the class should
8467 to having one or two columns.
8468 Can be changed in the
8469 \begin_inset Flex MenuItem
8472 \begin_layout Plain Layout
8473 Document\SpecialChar \menuseparator
8482 \begin_layout Description
8483 \begin_inset Flex Code
8486 \begin_layout Plain Layout
8493 \begin_inset Flex Code
8496 \begin_layout Plain Layout
8502 ] This sequence defines the properties for a counter.
8503 If the counter does not yet exist, it is created; if it does exist, it
8506 \begin_inset Quotes eld
8510 \begin_inset Flex Code
8513 \begin_layout Plain Layout
8520 \begin_inset Quotes erd
8524 \begin_inset Newline newline
8528 \begin_inset space ~
8532 \begin_inset CommandInset ref
8534 reference "sub:Counters"
8538 for details on counters.
8541 \begin_layout Description
8542 \begin_inset Flex Code
8545 \begin_layout Plain Layout
8551 Sets the default font used to display the document.
8553 \begin_inset space ~
8557 \begin_inset CommandInset ref
8559 reference "sub:Font-description"
8563 for how to declare fonts.
8565 \begin_inset Quotes eld
8569 \begin_inset Flex Code
8572 \begin_layout Plain Layout
8579 \begin_inset Quotes erd
8585 \begin_layout Description
8586 \begin_inset Flex Code
8589 \begin_layout Plain Layout
8596 \begin_inset Flex Code
8599 \begin_layout Plain Layout
8605 Specifies a module to be included by default with this document class.
8606 The module should be specified by filename without the
8607 \begin_inset Flex Code
8610 \begin_layout Plain Layout
8617 The user can still remove the module, but it will be active at the outset.
8618 (This applies only when new files are created, or when this class is chosen
8619 for an existing document.)
8622 \begin_layout Description
8623 \begin_inset Flex Code
8626 \begin_layout Plain Layout
8633 \begin_inset Flex Code
8636 \begin_layout Plain Layout
8642 ] This is the style that will be assigned to new paragraphs, usually
8643 \begin_inset Flex MenuItem
8646 \begin_layout Plain Layout
8653 This will default to the first defined style if not given, but you are
8654 encouraged to use this directive.
8657 \begin_layout Description
8658 \begin_inset Flex Code
8661 \begin_layout Plain Layout
8668 \begin_inset Flex Code
8671 \begin_layout Plain Layout
8677 ] This tag indicates that the module in question—which should be specified
8678 by filename without the
8679 \begin_inset Flex Code
8682 \begin_layout Plain Layout
8688 extension—cannot be used with this document class.
8689 This might be used in a journal-specific layout file to prevent, say, the
8691 \begin_inset Flex Code
8694 \begin_layout Plain Layout
8700 module that numbers theorems by section.
8705 be used in a module.
8706 Modules have their own way of excluding other modules (see
8707 \begin_inset CommandInset ref
8709 reference "sub:Layout-modules"
8716 \begin_layout Description
8717 \begin_inset Flex Code
8720 \begin_layout Plain Layout
8726 Defines a new float.
8728 \begin_inset space ~
8732 \begin_inset CommandInset ref
8734 reference "sub:Floats"
8740 \begin_inset Quotes eld
8744 \begin_inset Flex Code
8747 \begin_layout Plain Layout
8754 \begin_inset Quotes erd
8760 \begin_layout Description
8761 \begin_inset Flex Code
8764 \begin_layout Plain Layout
8770 Sets the information that will be output in the
8771 \begin_inset Flex Code
8774 \begin_layout Plain Layout
8780 block when this document class is output to XHTML.
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
8843 Sets CSS styling information.
8844 This will either be output in a
8845 \begin_inset Quotes eld
8849 \begin_inset Flex Code
8852 \begin_layout Plain Layout
8859 \begin_inset Quotes erd
8862 block or, if the user has so chosen, to a separate CSS file.
8863 Note that this will completely override any prior
8864 \begin_inset Flex Code
8867 \begin_layout Plain Layout
8874 \begin_inset Flex Code
8877 \begin_layout Plain Layout
8885 \begin_inset Flex Code
8888 \begin_layout Plain Layout
8894 if you just want to add material.) Must end with
8895 \begin_inset Quotes eld
8899 \begin_inset Flex Code
8902 \begin_layout Plain Layout
8909 \begin_inset Quotes erd
8915 \begin_layout Description
8916 \begin_inset Flex Code
8919 \begin_layout Plain Layout
8926 \begin_inset Flex Code
8929 \begin_layout Plain Layout
8935 ] The layout to use for the table of contents, bibliography, and so forth,
8936 when the document is output to HTML.
8937 For articles, this should normally be Section; for books, Chapter.
8938 If it is not given, then LyX will attempt to figure out which layout to
8942 \begin_layout Description
8943 \begin_inset Flex Code
8946 \begin_layout Plain Layout
8953 \begin_inset Flex Code
8956 \begin_layout Plain Layout
8962 ] Modifies the properties of the given counter.
8963 If the counter does not exist, the section is ignored.
8965 \begin_inset Quotes eld
8969 \begin_inset Flex Code
8972 \begin_layout Plain Layout
8979 \begin_inset Quotes erd
8983 \begin_inset Newline newline
8987 \begin_inset space ~
8991 \begin_inset CommandInset ref
8993 reference "sub:Counters"
8997 for details on counters.
9000 \begin_layout Description
9001 \begin_inset Flex Code
9004 \begin_layout Plain Layout
9011 \begin_inset Flex Code
9014 \begin_layout Plain Layout
9020 ] Modifies the properties of the given paragraph style.
9021 If the style does not exist, the section is ignored.
9023 \begin_inset Quotes eld
9027 \begin_inset Flex Code
9030 \begin_layout Plain Layout
9037 \begin_inset Quotes erd
9043 \begin_layout Description
9044 \begin_inset Flex Code
9047 \begin_layout Plain Layout
9053 As its name implies, this command allows you to include another layout
9054 definition file within yours to avoid duplicating commands.
9055 Common examples are the standard layout files, for example,
9056 \begin_inset Flex Code
9059 \begin_layout Plain Layout
9065 , which contains most of the basic layouts.
9068 \begin_layout Description
9069 \begin_inset Flex Code
9072 \begin_layout Plain Layout
9078 This section (re-)defines the layout of an inset.
9079 It can be applied to an existing inset or to a new, user-defined inset,
9080 e.g., a new character style.
9082 \begin_inset Quotes eld
9086 \begin_inset Flex Code
9089 \begin_layout Plain Layout
9096 \begin_inset Quotes erd
9100 \begin_inset Newline newline
9104 \begin_inset space ~
9108 \begin_inset CommandInset ref
9110 reference "sub:Flex-insets-and"
9114 for more information.
9118 \begin_layout Description
9119 \begin_inset Flex Code
9122 \begin_layout Plain Layout
9129 \begin_inset Flex Code
9132 \begin_layout Plain Layout
9138 ] A string that indicates the width of the left margin on the screen, for
9140 \begin_inset Quotes eld
9144 \begin_inset Quotes erd
9148 (Note that this is not a `length', like
9149 \begin_inset Quotes eld
9153 \begin_inset Quotes erd
9159 \begin_layout Description
9160 \begin_inset Flex Code
9163 \begin_layout Plain Layout
9170 \begin_inset Flex Code
9173 \begin_layout Plain Layout
9179 ] This command deletes an existing counter, usually one defined in an included
9183 \begin_layout Description
9184 \begin_inset Flex Code
9187 \begin_layout Plain Layout
9193 This command deletes an existing float.
9194 This is particularly useful when you want to suppress a float that has
9195 been defined in an input file.
9198 \begin_layout Description
9199 \begin_inset Flex Code
9202 \begin_layout Plain Layout
9208 This command deletes an existing style.
9209 This is particularly useful when you want to suppress a style that has
9210 be defined in an input file.
9213 \begin_layout Description
9214 \begin_inset Flex Code
9217 \begin_layout Plain Layout
9223 A string indicating the file format (as defined in the Preferences dialog)
9224 produced by this class.
9225 It is mainly useful when
9226 \begin_inset Flex Code
9229 \begin_layout Plain Layout
9235 is `literate' and one wants to define a new type of literate document.
9236 This string is reset to `docbook', `latex', or `literate' when the correspondin
9238 \begin_inset Flex Code
9241 \begin_layout Plain Layout
9247 parameter is encountered.
9250 \begin_layout Description
9251 \begin_inset Flex Code
9254 \begin_layout Plain Layout
9260 A string indicating what sort of output documents using this class will
9262 At present, the options are: `docbook', `latex', and `literate'.
9265 \begin_layout Description
9266 \begin_inset Flex Code
9269 \begin_layout Plain Layout
9276 \begin_inset Flex Code
9279 \begin_layout Plain Layout
9288 \begin_inset Flex Code
9291 \begin_layout Plain Layout
9298 \begin_inset Flex Code
9301 \begin_layout Plain Layout
9307 ] The default pagestyle.
9308 Can be changed in the
9309 \begin_inset Flex MenuItem
9312 \begin_layout Plain Layout
9313 Document\SpecialChar \menuseparator
9322 \begin_layout Description
9323 \begin_inset Flex Code
9326 \begin_layout Plain Layout
9332 Sets the preamble for the LaTeX document.
9333 Note that this will completely override any prior
9334 \begin_inset Flex Code
9337 \begin_layout Plain Layout
9344 \begin_inset Flex Code
9347 \begin_layout Plain Layout
9355 \begin_inset Flex Code
9358 \begin_layout Plain Layout
9364 if you just want to add material to the preamble.) Must end with
9365 \begin_inset Quotes eld
9369 \begin_inset Flex Code
9372 \begin_layout Plain Layout
9379 \begin_inset Quotes erd
9385 \begin_layout Description
9386 \begin_inset Flex Code
9389 \begin_layout Plain Layout
9396 \begin_inset Flex Code
9399 \begin_layout Plain Layout
9406 \begin_inset Flex Code
9409 \begin_layout Plain Layout
9418 \begin_inset space \thinspace{}
9422 \begin_inset Flex Code
9425 \begin_layout Plain Layout
9431 ] Whether the class already provides the feature
9432 \begin_inset Flex Code
9435 \begin_layout Plain Layout
9442 A feature is in general the name of a package (
9443 \begin_inset Flex Code
9446 \begin_layout Plain Layout
9453 \begin_inset Flex Code
9456 \begin_layout Plain Layout
9462 , \SpecialChar \ldots{}
9464 \begin_inset Flex Code
9467 \begin_layout Plain Layout
9474 \begin_inset Flex Code
9477 \begin_layout Plain Layout
9483 ,\SpecialChar \ldots{}
9484 ); the complete list of supported features is unfortunately not documented
9485 outside the LyX source code—but see
9486 \begin_inset Flex Code
9489 \begin_layout Plain Layout
9495 if you're interested.
9497 \begin_inset Flex MenuItem
9500 \begin_layout Plain Layout
9501 Help\SpecialChar \menuseparator
9507 also gives an overview of the supported packages.
9510 \begin_layout Description
9511 \begin_inset Flex Code
9514 \begin_layout Plain Layout
9521 \begin_inset Flex Code
9524 \begin_layout Plain Layout
9530 ] Indicates that this layout provides the functionality of the module mentioned,
9531 which should be specified by the filename without the
9532 \begin_inset Flex Code
9535 \begin_layout Plain Layout
9542 This will typically be used if the layout includes the module directly,
9543 rather than using the
9544 \begin_inset Flex Code
9547 \begin_layout Plain Layout
9553 tag to indicate that it ought to be used.
9554 It could also be used in a module that provided an alternate implementation
9555 of the same functionality.
9558 \begin_layout Description
9559 \begin_inset Flex Code
9562 \begin_layout Plain Layout
9569 \begin_inset Flex Code
9572 \begin_layout Plain Layout
9578 ] Whether the class requires the feature
9579 \begin_inset Flex Code
9582 \begin_layout Plain Layout
9589 Multiple features must be separated by commas.
9590 Note that you can only request supported features.
9592 \begin_inset Flex Code
9595 \begin_layout Plain Layout
9601 for a list of these.)
9604 \begin_layout Description
9605 \begin_inset Flex Code
9608 \begin_layout Plain Layout
9615 \begin_inset Flex Code
9618 \begin_layout Plain Layout
9624 ] A string that indicates the width of the right margin on the screen, for
9626 \begin_inset Quotes eld
9630 \begin_inset Flex Code
9633 \begin_layout Plain Layout
9640 \begin_inset Quotes erd
9646 \begin_layout Description
9647 \begin_inset Flex Code
9650 \begin_layout Plain Layout
9657 \begin_inset Flex Code
9660 \begin_layout Plain Layout
9666 ] Sets which divisions get numbered.
9668 \begin_inset Newline newline
9672 \begin_inset Flex Code
9675 \begin_layout Plain Layout
9684 \begin_layout Description
9685 \begin_inset Flex Code
9688 \begin_layout Plain Layout
9695 \begin_inset Flex Code
9698 \begin_layout Plain Layout
9707 \begin_inset space \thinspace{}
9711 \begin_inset Flex Code
9714 \begin_layout Plain Layout
9720 ] Whether the class-default should be printing on one or both sides of the
9722 Can be changed in the
9723 \begin_inset Flex MenuItem
9726 \begin_layout Plain Layout
9727 Document\SpecialChar \menuseparator
9736 \begin_layout Description
9737 \begin_inset Flex Code
9740 \begin_layout Plain Layout
9747 \begin_inset Flex Code
9750 \begin_layout Plain Layout
9756 ] This sequence defines a paragraph style.
9757 If the style does not yet exist, it is created; if it does exist, its parameter
9760 \begin_inset Quotes eld
9764 \begin_inset Flex Code
9767 \begin_layout Plain Layout
9774 \begin_inset Quotes erd
9778 \begin_inset Newline newline
9782 \begin_inset space ~
9786 \begin_inset CommandInset ref
9788 reference "sub:Paragraph-Styles"
9792 for details on paragraph styles.
9795 \begin_layout Description
9796 \begin_inset Flex Code
9799 \begin_layout Plain Layout
9806 \begin_inset Flex Code
9809 \begin_layout Plain Layout
9815 ] The name of the command or environment to be used with
9816 \begin_inset Flex Code
9819 \begin_layout Plain Layout
9828 \begin_layout Description
9829 \begin_inset Flex Code
9832 \begin_layout Plain Layout
9839 \begin_inset Flex Code
9842 \begin_layout Plain Layout
9851 \begin_inset Flex Code
9854 \begin_layout Plain Layout
9860 ] Indicates what kind of markup is used to define the title of a document.
9862 \begin_inset Flex Code
9865 \begin_layout Plain Layout
9871 means that the macro with name
9872 \begin_inset Flex Code
9875 \begin_layout Plain Layout
9881 will be inserted after the last layout which has
9882 \begin_inset Quotes eld
9886 \begin_inset Flex Code
9889 \begin_layout Plain Layout
9891 \begin_inset space ~
9900 \begin_inset Quotes erd
9905 \begin_inset Flex Code
9908 \begin_layout Plain Layout
9914 corresponds to the case where all layouts which have
9915 \begin_inset Quotes eld
9919 \begin_inset Flex Code
9922 \begin_layout Plain Layout
9924 \begin_inset space ~
9933 \begin_inset Quotes erd
9936 should be enclosed into the
9937 \begin_inset Flex Code
9940 \begin_layout Plain Layout
9949 \begin_layout Description
9950 \begin_inset Flex Code
9953 \begin_layout Plain Layout
9960 \begin_inset Flex Code
9963 \begin_layout Plain Layout
9969 ] Sets which divisions are included in the table of contents.
9971 \begin_inset Flex Code
9974 \begin_layout Plain Layout
9983 \begin_layout Subsection
9984 \begin_inset Flex Code
9987 \begin_layout Plain Layout
9994 \begin_inset CommandInset label
9996 name "sub:ClassOptions"
10003 \begin_layout Standard
10005 \begin_inset Flex Code
10008 \begin_layout Plain Layout
10014 section can contain the following entries:
10017 \begin_layout Description
10018 \begin_inset Flex Code
10021 \begin_layout Plain Layout
10028 \begin_inset Flex Code
10031 \begin_layout Plain Layout
10037 ] The list of available font sizes for the document's main font, separated
10039 \begin_inset Quotes eld
10043 \begin_inset Flex Code
10046 \begin_layout Plain Layout
10053 \begin_inset Quotes erd
10059 \begin_layout Description
10060 \begin_inset Flex Code
10063 \begin_layout Plain Layout
10069 Used to set the DTD line with XML-based output classes.
10071 \begin_inset space \thinspace{}
10075 \begin_inset Quotes eld
10078 -//OASIS//DTD DocBook V4.2//EN
10079 \begin_inset Quotes erd
10085 \begin_layout Description
10086 \begin_inset Flex Code
10089 \begin_layout Plain Layout
10096 \begin_inset Flex Code
10099 \begin_layout Plain Layout
10100 string="empty|plain|headings|fancy"
10105 ] The list of available page sty\SpecialChar \-
10107 \begin_inset Quotes eld
10111 \begin_inset Flex Code
10114 \begin_layout Plain Layout
10121 \begin_inset Quotes erd
10127 \begin_layout Description
10128 \begin_inset Flex Code
10131 \begin_layout Plain Layout
10138 \begin_inset Flex Code
10141 \begin_layout Plain Layout
10147 ] Some document class options, separated by a comma, that will be added
10148 to the optional part of the
10149 \begin_inset Flex Code
10152 \begin_layout Plain Layout
10163 \begin_layout Standard
10165 \begin_inset Flex Code
10168 \begin_layout Plain Layout
10174 section must end with
10175 \begin_inset Quotes eld
10179 \begin_inset Flex Code
10182 \begin_layout Plain Layout
10189 \begin_inset Quotes erd
10195 \begin_layout Subsection
10197 \begin_inset CommandInset label
10199 name "sub:Paragraph-Styles"
10206 \begin_layout Standard
10207 A paragraph style description looks like this:
10211 \begin_layout Plain Layout
10212 Note that this will either define a new style or modify an existing one.
10220 \begin_layout LyX-Code
10227 \begin_layout LyX-Code
10231 \begin_layout LyX-Code
10235 \begin_layout Standard
10236 where the following commands are allowed:
10239 \begin_layout Description
10240 \begin_inset Flex Code
10243 \begin_layout Plain Layout
10250 \begin_inset Flex Code
10253 \begin_layout Plain Layout
10258 , left, right, center
10263 ] Paragraph alignment.
10266 \begin_layout Description
10267 \begin_inset Flex Code
10270 \begin_layout Plain Layout
10277 \begin_inset Flex Code
10280 \begin_layout Plain Layout
10285 , left, right, center
10290 ] A comma separated list of permitted alignments.
10291 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
10293 For example a right-aligned or centered enumeration isn't possible.)
10294 \change_inserted -712698321 1353679769
10298 \begin_layout Description
10300 \change_inserted -712698321 1353680268
10301 \begin_inset Flex Code
10304 \begin_layout Plain Layout
10306 \change_inserted -712698321 1353679781
10313 \begin_inset Flex Code
10316 \begin_layout Plain Layout
10318 \change_inserted -712698321 1353679772
10324 ] Defines argument number <int> of a command\SpecialChar \slash{}
10325 environment associated with
10327 This is useful for things like section headings, and only makes sense with
10329 Every (optional or required) argument of a command or environment -- except
10330 for the required argument that is associated with the content of the paragraph
10331 itself -- has a separate definition, where the number specifies the order
10333 The definition must end with
10334 \begin_inset Flex Code
10337 \begin_layout Plain Layout
10339 \change_inserted -712698321 1353680069
10346 So a command with two optional arguments has:
10350 \begin_layout Quote
10352 \change_inserted -712698321 1353680127
10358 \begin_layout Quote
10360 \change_inserted -712698321 1353680195
10366 \begin_layout Quote
10368 \change_inserted -712698321 1353680135
10374 \begin_layout Quote
10376 \change_inserted -712698321 1353680140
10382 \begin_layout Quote
10384 \change_inserted -712698321 1353680197
10390 \begin_layout Quote
10392 \change_inserted -712698321 1353680147
10398 \begin_layout Standard
10400 \change_inserted -712698321 1353680528
10402 \begin_inset Flex Code
10405 \begin_layout Plain Layout
10407 \change_inserted -712698321 1353680412
10413 definition, the following specifications are possible:
10416 \begin_layout Itemize
10418 \change_inserted -712698321 1355076779
10419 \begin_inset Flex Code
10422 \begin_layout Plain Layout
10424 \change_inserted -712698321 1353680543
10433 \begin_inset Flex Code
10436 \begin_layout Plain Layout
10438 \change_inserted -712698321 1353680567
10444 The string that will appear both in the menu (to insert this argument)
10445 and on the argument inset button (unless you also specify a separate
10446 \begin_inset Flex Code
10449 \begin_layout Plain Layout
10451 \change_inserted -712698321 1355076779
10458 For the menu, you can define an accelerator by appending the respective
10459 character to the string, divided by
10460 \begin_inset Quotes eld
10464 \begin_inset Quotes erd
10468 \begin_inset space \thinspace{}
10473 \begin_inset Flex Code
10476 \begin_layout Plain Layout
10478 \change_inserted -712698321 1353691482
10479 \begin_inset Quotes eld
10483 \begin_inset Quotes erd
10496 \begin_layout Itemize
10498 \change_inserted -712698321 1355076754
10499 \begin_inset Flex Code
10502 \begin_layout Plain Layout
10504 \change_inserted -712698321 1355076658
10511 \begin_inset Flex Code
10514 \begin_layout Plain Layout
10516 \change_inserted -712698321 1355076654
10522 A separate string for the menu.
10523 You can define an accelerator by appending the respective character to
10524 the string, divided by
10525 \begin_inset Quotes eld
10529 \begin_inset Quotes erd
10533 \begin_inset space \thinspace{}
10538 \begin_inset Flex Code
10541 \begin_layout Plain Layout
10543 \change_inserted -712698321 1355076654
10544 \begin_inset Quotes eld
10548 \begin_inset Quotes erd
10557 This specification is optional.
10558 If it is not given the
10559 \begin_inset Flex Code
10562 \begin_layout Plain Layout
10564 \change_inserted -712698321 1355076736
10572 will be used instead for the menu.
10575 \begin_layout Itemize
10577 \change_inserted -712698321 1353680665
10578 \begin_inset Flex Code
10581 \begin_layout Plain Layout
10583 \change_inserted -712698321 1353680616
10590 \begin_inset Flex Code
10593 \begin_layout Plain Layout
10595 \change_inserted -712698321 1353680623
10601 A longer explanatory text that appears in the tooltip when hovering over
10602 the argument inset.
10605 \begin_layout Itemize
10607 \change_inserted -712698321 1353680874
10608 \begin_inset Flex Code
10611 \begin_layout Plain Layout
10613 \change_inserted -712698321 1353680732
10620 \begin_inset Flex Code
10623 \begin_layout Plain Layout
10625 \change_inserted -712698321 1353680738
10631 Declare if this is a mandatory
10632 \change_inserted 2090807402 1353765594
10634 \change_inserted -712698321 1353680874
10636 \change_inserted 2090807402 1353765599
10638 \change_inserted -712698321 1353680874
10640 Mandatory arguments will be output empty if not given, while optional arguments
10641 will not be output at all.
10642 By default, mandatory arguments are delimited by
10643 \begin_inset Flex Code
10646 \begin_layout Plain Layout
10648 \change_inserted -712698321 1353680808
10656 , while optional arguments are delimited by
10657 \begin_inset Flex Code
10660 \begin_layout Plain Layout
10662 \change_inserted -712698321 1353680833
10671 \begin_layout Itemize
10673 \change_inserted -712698321 1353917199
10674 \begin_inset Flex Code
10677 \begin_layout Plain Layout
10679 \change_inserted -712698321 1353680879
10686 \begin_inset Flex Code
10689 \begin_layout Plain Layout
10691 \change_inserted -712698321 1353680874
10697 defines another argument (by its number) which this argument requires to
10698 be output if it is itself output.
10700 \begin_inset space \thinspace{}
10703 g., in LaTeX commands, optional arguments often require previous optional
10704 arguments to be output (at least empty), as in
10705 \begin_inset Flex Code
10708 \begin_layout Plain Layout
10710 \change_inserted -712698321 1353688183
10713 command[][arg]{text}
10721 This can be achieved by the statement
10722 \begin_inset Flex Code
10725 \begin_layout Plain Layout
10727 \change_inserted -712698321 1353681031
10736 \begin_inset Flex Code
10739 \begin_layout Plain Layout
10741 \change_inserted -712698321 1353681045
10752 \begin_layout Itemize
10754 \change_inserted -712698321 1354263104
10755 \begin_inset Flex Code
10758 \begin_layout Plain Layout
10760 \change_inserted -712698321 1353681072
10769 \begin_inset Flex Code
10772 \begin_layout Plain Layout
10774 \change_inserted -712698321 1353681067
10780 defines a custom left delimiter (instead of
10781 \begin_inset Flex Code
10784 \begin_layout Plain Layout
10786 \change_inserted -712698321 1353681127
10795 \begin_inset Flex Code
10798 \begin_layout Plain Layout
10800 \change_inserted -712698321 1353681133
10809 A line break in the output can be indicated by
10810 \begin_inset Flex Code
10813 \begin_layout Plain Layout
10815 \change_inserted -712698321 1354263104
10826 \begin_layout Itemize
10828 \change_inserted -712698321 1355144479
10829 \begin_inset Flex Code
10832 \begin_layout Plain Layout
10834 \change_inserted -712698321 1353681149
10841 \begin_inset Flex Code
10844 \begin_layout Plain Layout
10846 \change_inserted -712698321 1353681146
10852 defines a custom right delimiter (instead of
10853 \begin_inset Flex Code
10856 \begin_layout Plain Layout
10858 \change_inserted -712698321 1353681158
10865 \begin_inset Flex Code
10868 \begin_layout Plain Layout
10870 \change_inserted -712698321 1353681161
10877 A line break in the output can be indicated by
10878 \begin_inset Flex Code
10881 \begin_layout Plain Layout
10883 \change_inserted -712698321 1354263106
10892 \begin_layout Itemize
10894 \change_inserted -712698321 1355144578
10895 \begin_inset Flex Code
10898 \begin_layout Plain Layout
10900 \change_inserted -712698321 1355144487
10909 \begin_inset Flex Code
10912 \begin_layout Plain Layout
10914 \change_inserted -712698321 1355144500
10920 defines an argument that is inserted in any case (alone or in addition
10921 to user-specified arguments).
10922 Multiple arguments need to be separated by comma.
10927 \begin_layout Itemize
10929 \change_inserted -712698321 1353917320
10930 \begin_inset Flex Code
10933 \begin_layout Plain Layout
10935 \change_inserted -712698321 1353917320
10941 The font used for the argument content.
10943 \begin_inset space ~
10947 \begin_inset CommandInset ref
10949 reference "sub:Font-description"
10956 \begin_layout Itemize
10958 \change_inserted -712698321 1353917320
10959 \begin_inset Flex Code
10962 \begin_layout Plain Layout
10964 \change_inserted -712698321 1353917320
10970 The font used for the label.
10972 \begin_inset space ~
10976 \begin_inset CommandInset ref
10978 reference "sub:Font-description"
10985 \begin_layout Itemize
10987 \change_inserted -712698321 1355661048
10988 \begin_inset Flex Code
10991 \begin_layout Plain Layout
10993 \change_inserted -712698321 1353917320
11000 \begin_inset Flex Code
11003 \begin_layout Plain Layout
11005 \change_inserted -712698321 1353917320
11012 \begin_inset Flex Code
11015 \begin_layout Plain Layout
11017 \change_inserted -712698321 1353917320
11024 \begin_inset Flex Code
11027 \begin_layout Plain Layout
11029 \change_inserted -712698321 1353917320
11035 , describing the rendering style used for the inset's frame and buttons.
11037 \begin_inset Flex Code
11040 \begin_layout Plain Layout
11042 \change_inserted -712698321 1353917320
11051 \begin_layout Itemize
11053 \change_inserted -712698321 1355747298
11054 \begin_inset Flex Code
11057 \begin_layout Plain Layout
11059 \change_inserted -712698321 1355661057
11066 \begin_inset Flex Code
11069 \begin_layout Plain Layout
11071 \change_inserted -712698321 1355661049
11078 \begin_inset Flex Code
11081 \begin_layout Plain Layout
11083 \change_inserted -712698321 1355661077
11091 , this argument is automatically inserted when the respective style is selected.
11092 Currently, only one argument per style\SpecialChar \slash{}
11093 layout can be automatically inserted.
11094 \change_inserted 155139281 1354198988
11098 \begin_layout Standard
11100 \change_inserted -712698321 1356689813
11101 By default, the text entered in the LyX workarea in the respective layout
11102 is the last (mandatory) argument of a command if the
11103 \begin_inset Flex Code
11106 \begin_layout Plain Layout
11108 \change_inserted -712698321 1356689619
11117 \begin_inset Flex Code
11120 \begin_layout Plain Layout
11122 \change_inserted -712698321 1356689629
11131 However, arguments with the prefix
11132 \begin_inset Flex Code
11135 \begin_layout Plain Layout
11137 \change_inserted -712698321 1356689679
11145 are output after this workarea argument.
11146 Note that post-argument numbering restarts at 1, so the first argument
11147 following the workarea argument is
11148 \begin_inset Flex Code
11151 \begin_layout Plain Layout
11153 \change_inserted -712698321 1356689813
11162 Post-arguments are ignored in any other
11163 \begin_inset Flex Code
11166 \begin_layout Plain Layout
11168 \change_inserted -712698321 1356689801
11175 \begin_inset Flex Code
11178 \begin_layout Plain Layout
11180 \change_inserted -712698321 1356689801
11191 \begin_layout Standard
11193 \change_inserted 155139281 1354199102
11195 \begin_inset Flex Code
11198 \begin_layout Plain Layout
11200 \change_inserted 155139281 1354199013
11211 \begin_inset Flex Code
11214 \begin_layout Plain Layout
11216 \change_inserted 155139281 1354199102
11227 \begin_inset Flex Code
11230 \begin_layout Plain Layout
11232 \change_inserted 155139281 1354199044
11240 followed by the number (e.
11241 \begin_inset space \thinspace{}
11246 \begin_inset Flex Code
11249 \begin_layout Plain Layout
11251 \change_inserted 155139281 1354199064
11265 \begin_layout Description
11266 \begin_inset Flex Code
11269 \begin_layout Plain Layout
11275 Note that this will completely override any prior
11276 \begin_inset Flex Code
11279 \begin_layout Plain Layout
11285 declaration for this style.
11287 \begin_inset Quotes eld
11291 \begin_inset Flex Code
11294 \begin_layout Plain Layout
11301 \begin_inset Quotes erd
11306 \begin_inset space ~
11310 \begin_inset CommandInset ref
11312 reference "sub:I18n"
11316 for details on its use.
11319 \begin_layout Description
11320 \begin_inset Flex Code
11323 \begin_layout Plain Layout
11330 \begin_inset Flex Code
11333 \begin_layout Plain Layout
11343 \begin_layout Plain Layout
11344 Note that a `float' here is a real number, such as: 1.5.
11349 The vertical space with which the last of a chain of paragraphs with this
11350 style is separated from the following paragraph.
11351 If the next paragraph has another style, the separations are not simply
11352 added, but the maximum is taken.
11355 \begin_layout Description
11356 \begin_inset Flex Code
11359 \begin_layout Plain Layout
11366 \begin_inset Flex Code
11369 \begin_layout Plain Layout
11375 ] The category for this style.
11376 This is used to group related styles in the style combobox on the toolbar.
11377 Any string can be used, but you may want to use existing categories with
11382 \begin_layout Description
11383 \begin_inset Flex Code
11386 \begin_layout Plain Layout
11392 Depth of XML command.
11393 Used only with XML-type formats.
11396 \begin_layout Description
11397 \begin_inset Flex Code
11400 \begin_layout Plain Layout
11407 \begin_inset Flex Code
11410 \begin_layout Plain Layout
11416 ] Copies all the features of an existing style into the current one.
11420 \begin_layout Description
11421 \begin_inset Flex Code
11424 \begin_layout Plain Layout
11431 \begin_inset Flex Code
11434 \begin_layout Plain Layout
11440 ] The name of a style whose preamble should be output
11445 This allows to ensure some ordering of the preamble snippets when macros
11446 definitions depend on one another.
11450 \begin_layout Plain Layout
11451 Note that, besides that functionality, there is no way to ensure any ordering
11453 The ordering that you see in a given version of LyX may change without
11454 warning in later versions.
11462 \begin_layout Description
11463 \begin_inset Flex Code
11466 \begin_layout Plain Layout
11473 \begin_inset Flex Code
11476 \begin_layout Plain Layout
11481 , Box, Filled_Box, Static
11486 ] The type of label that stands at the end of the paragraph (or sequence
11488 \begin_inset Flex Code
11491 \begin_layout Plain Layout
11498 \begin_inset Newline newline
11502 \begin_inset Flex Code
11505 \begin_layout Plain Layout
11512 \begin_inset Flex Code
11515 \begin_layout Plain Layout
11522 \begin_inset Flex Code
11525 \begin_layout Plain Layout
11533 \begin_inset Flex Code
11536 \begin_layout Plain Layout
11543 \begin_inset Quotes eld
11547 \begin_inset Quotes erd
11551 \begin_inset Flex Code
11554 \begin_layout Plain Layout
11561 \begin_inset space \space{}
11565 \begin_inset Flex Code
11568 \begin_layout Plain Layout
11574 ) is a white (resp.
11575 \begin_inset space ~
11578 black) square suitable for end of proof markers,
11579 \begin_inset Flex Code
11582 \begin_layout Plain Layout
11588 is an explicit text string.
11591 \begin_layout Description
11592 \begin_inset Flex Code
11595 \begin_layout Plain Layout
11602 \begin_inset Flex Code
11605 \begin_layout Plain Layout
11611 ] The string used for a label with a
11612 \begin_inset Flex Code
11615 \begin_layout Plain Layout
11622 \begin_inset Newline newline
11626 \begin_inset Flex Code
11629 \begin_layout Plain Layout
11639 \begin_layout Description
11640 \begin_inset Flex Code
11643 \begin_layout Plain Layout
11649 The font used for both the text body
11655 \begin_inset space ~
11659 \begin_inset CommandInset ref
11661 reference "sub:Font-description"
11666 Note that defining this font automatically defines the
11667 \begin_inset Flex Code
11670 \begin_layout Plain Layout
11677 So you should define this one first if you also want to define
11678 \begin_inset Flex Code
11681 \begin_layout Plain Layout
11690 \begin_layout Description
11691 \begin_inset Flex Code
11694 \begin_layout Plain Layout
11701 \begin_inset Flex Code
11704 \begin_layout Plain Layout
11713 \begin_inset space \thinspace{}
11717 \begin_inset Flex Code
11720 \begin_layout Plain Layout
11726 ] Usually LyX does not allow you to insert more than one space between words,
11727 since a space is considered as the separation between two words, not a
11728 character or symbol of its own.
11729 This is a very fine thing but sometimes annoying, for example, when typing
11730 program code or plain LaTeX code.
11732 \begin_inset Flex Code
11735 \begin_layout Plain Layout
11742 Note that LyX will create protected blanks for the additional blanks when
11743 in another mode than LaTeX-mode.
11746 \begin_layout Description
11747 \begin_inset Flex Code
11750 \begin_layout Plain Layout
11756 These tags are used with XHTML output.
11758 \begin_inset CommandInset ref
11760 reference "sub:Paragraph-Style-XHTML"
11767 \begin_layout Description
11768 \begin_inset Flex Code
11771 \begin_layout Plain Layout
11777 [FIXME] (Used only with XML-type formats.)
11780 \begin_layout Description
11781 \begin_inset Flex Code
11784 \begin_layout Plain Layout
11791 \begin_inset Flex Code
11794 \begin_layout Plain Layout
11803 \begin_inset space \thinspace{}
11807 \begin_inset Flex Code
11810 \begin_layout Plain Layout
11817 \begin_inset Flex Code
11820 \begin_layout Plain Layout
11826 , marks the style as to be included in the document preamble and not in
11828 This is useful for document classes that want such information as the title
11829 and author to appear in the preamble.
11830 Note that this works only for styles for which the
11831 \begin_inset Flex Code
11834 \begin_layout Plain Layout
11841 \begin_inset Flex Code
11844 \begin_layout Plain Layout
11851 \begin_inset Flex Code
11854 \begin_layout Plain Layout
11863 \begin_layout Description
11864 \begin_inset Flex Code
11867 \begin_layout Plain Layout
11874 \begin_inset Flex Code
11877 \begin_layout Plain Layout
11886 \begin_inset space \thinspace{}
11890 \begin_inset Flex Code
11893 \begin_layout Plain Layout
11900 \begin_inset Flex Code
11903 \begin_layout Plain Layout
11909 , marks the style as being part of a title block (see also the
11910 \begin_inset Flex Code
11913 \begin_layout Plain Layout
11920 \begin_inset Flex Code
11923 \begin_layout Plain Layout
11932 \begin_layout Description
11934 \change_inserted -712698321 1355932296
11935 \begin_inset Flex Code
11938 \begin_layout Plain Layout
11940 \change_inserted -712698321 1355932178
11947 \begin_inset Flex Code
11950 \begin_layout Plain Layout
11952 \change_inserted -712698321 1355932181
11958 ] The LaTeX command sequence declaring an item in a list.
11959 The command is to be defined without the preceding backslash (the default
11961 \begin_inset Quotes eld
11965 \begin_inset Quotes erd
11969 \begin_inset Flex Code
11972 \begin_layout Plain Layout
11974 \change_inserted -712698321 1355932279
11984 in the LaTeX output).
11987 \begin_layout Description
11988 \begin_inset Flex Code
11991 \begin_layout Plain Layout
11998 \begin_inset Flex Code
12001 \begin_layout Plain Layout
12007 ] This provides extra space between paragraphs that have the same style.
12008 If you put other styles into an environment, each is separated with the
12010 \begin_inset Flex Code
12013 \begin_layout Plain Layout
12020 But the whole items of the environment are additionally separated with
12022 \begin_inset Flex Code
12025 \begin_layout Plain Layout
12032 Note that this is a
12037 \begin_layout Description
12038 \begin_inset Flex Code
12041 \begin_layout Plain Layout
12047 [FIXME] (Used only with XML-type formats.)
12050 \begin_layout Description
12051 \begin_inset Flex Code
12054 \begin_layout Plain Layout
12061 \begin_inset Flex Code
12064 \begin_layout Plain Layout
12073 \begin_inset space \thinspace{}
12077 \begin_inset Flex Code
12080 \begin_layout Plain Layout
12086 ] Usually LyX does not allow you to leave a paragraph empty, since it would
12087 lead to empty LaTeX output.
12088 There are some cases where this could be desirable however: in a letter
12089 template, the required fields can be provided as empty fields, so that
12090 people do not forget them; in some special classes, a style can be used
12091 as some kind of break, which does not contain actual text.
12094 \begin_layout Description
12095 \begin_inset Flex Code
12098 \begin_layout Plain Layout
12105 \begin_inset Flex Code
12108 \begin_layout Plain Layout
12114 ] The vertical space between the label and the text body.
12115 Only used for labels that are above the text body (
12116 \begin_inset Flex Code
12119 \begin_layout Plain Layout
12126 \begin_inset Newline newline
12130 \begin_inset Flex Code
12133 \begin_layout Plain Layout
12134 Centered_Top_Environment
12142 \begin_layout Description
12143 \begin_inset Flex Code
12146 \begin_layout Plain Layout
12153 \begin_inset Flex Code
12156 \begin_layout Plain Layout
12162 ] The name of the counter for automatic numbering.
12163 \begin_inset Newline newline
12171 \begin_inset Flex Code
12174 \begin_layout Plain Layout
12181 \begin_inset Flex Code
12184 \begin_layout Plain Layout
12191 In that case, the counter will be stepped each time the style appears.
12192 \begin_inset Newline newline
12200 \begin_inset Flex Code
12203 \begin_layout Plain Layout
12210 \begin_inset Flex Code
12213 \begin_layout Plain Layout
12219 , though this case is a bit complicated.
12220 Suppose you declare
12221 \begin_inset Quotes eld
12225 \begin_inset Flex Code
12228 \begin_layout Plain Layout
12229 LabelCounter myenum
12235 \begin_inset Quotes erd
12239 Then the actual counters used are
12240 \begin_inset Flex Code
12243 \begin_layout Plain Layout
12250 \begin_inset Flex Code
12253 \begin_layout Plain Layout
12260 \begin_inset Flex Code
12263 \begin_layout Plain Layout
12270 \begin_inset Flex Code
12273 \begin_layout Plain Layout
12279 , much as in LaTeX.
12280 These counters must all be declared separately.
12281 \begin_inset Newline newline
12285 \begin_inset CommandInset ref
12287 reference "sub:Counters"
12291 for details on counters.
12294 \begin_layout Description
12295 \begin_inset Flex Code
12298 \begin_layout Plain Layout
12304 The font used for the label.
12306 \begin_inset space ~
12310 \begin_inset CommandInset ref
12312 reference "sub:Font-description"
12319 \begin_layout Description
12320 \begin_inset Flex Code
12323 \begin_layout Plain Layout
12330 \begin_inset Flex Code
12333 \begin_layout Plain Layout
12339 ] Text that indicates how far a label should be indented.
12342 \begin_layout Description
12343 \begin_inset Flex Code
12346 \begin_layout Plain Layout
12353 \begin_inset Flex Code
12356 \begin_layout Plain Layout
12362 ] Text that indicates the amount of horizontal space between the label and
12364 Only used for labels that are not above the text body.
12367 \begin_layout Description
12368 \begin_inset Flex Code
12371 \begin_layout Plain Layout
12378 \begin_inset Flex Code
12381 \begin_layout Plain Layout
12387 ] The string used for a label with a
12388 \begin_inset Flex Code
12391 \begin_layout Plain Layout
12398 \begin_inset Flex Code
12401 \begin_layout Plain Layout
12409 \begin_inset Flex Code
12412 \begin_layout Plain Layout
12418 is set, this string can be contain the special formatting commands described
12420 \begin_inset CommandInset ref
12422 reference "sub:Counters"
12429 \begin_layout Description
12430 \begin_inset Flex Code
12433 \begin_layout Plain Layout
12434 LabelStringAppendix
12440 \begin_inset Flex Code
12443 \begin_layout Plain Layout
12449 ] This is used inside the appendix instead of
12450 \begin_inset Newline newline
12454 \begin_inset Flex Code
12457 \begin_layout Plain Layout
12465 \begin_inset Flex Code
12468 \begin_layout Plain Layout
12475 \begin_inset Newline newline
12479 \begin_inset Flex Code
12482 \begin_layout Plain Layout
12483 LabelStringAppendix
12491 \begin_layout Description
12492 \begin_inset Flex Code
12495 \begin_layout Plain Layout
12501 [FIXME] (Used only with XML-type formats.)
12504 \begin_layout Description
12505 \begin_inset Flex Code
12508 \begin_layout Plain Layout
12515 \begin_inset Flex Code
12518 \begin_layout Plain Layout
12523 , Manual, Static, Top_Environment,
12524 \begin_inset Newline newline
12527 Centered_Top_Environment, Counter, Sensitive, Enumerate,
12528 \begin_inset Newline newline
12531 Itemize, Bibliography
12540 \begin_layout Description
12541 \begin_inset Flex Code
12544 \begin_layout Plain Layout
12550 means the label is the very first word (up to the first real blank).
12551 Use protected spaces if you want more than one word as the label.
12555 \begin_layout Description
12556 \begin_inset Flex Code
12559 \begin_layout Plain Layout
12565 means the label is simply what is declared as
12566 \begin_inset Flex Code
12569 \begin_layout Plain Layout
12576 Note that this really is `static'.
12579 \begin_layout Description
12580 \begin_inset Flex Code
12583 \begin_layout Plain Layout
12590 \begin_inset space ~
12594 \begin_inset space ~
12598 \begin_inset Flex Code
12601 \begin_layout Plain Layout
12602 Centered_Top_Environment
12607 are special cases of
12608 \begin_inset Flex Code
12611 \begin_layout Plain Layout
12618 The label will be printed above the paragraph, but only at the top of an
12619 environment or the top of a chain of paragraphs with this style.
12620 This might be used with the
12621 \begin_inset Flex MenuItem
12624 \begin_layout Plain Layout
12630 style, for example.
12633 \begin_layout Description
12634 \begin_inset Flex Code
12637 \begin_layout Plain Layout
12643 is a special case for the caption-labels
12644 \begin_inset Quotes eld
12648 \begin_inset Quotes erd
12652 \begin_inset Quotes eld
12656 \begin_inset Quotes erd
12660 \begin_inset Newline newline
12664 \begin_inset Flex Code
12667 \begin_layout Plain Layout
12673 means the (hardcoded) label string depends on the kind of float: It is
12674 hardcoded to be `FloatType N', where N is the value of the counter associated
12678 \begin_layout Description
12679 \begin_inset Flex Code
12682 \begin_layout Plain Layout
12688 defines automatically numbered labels.
12690 \begin_inset Flex Code
12693 \begin_layout Plain Layout
12699 will be expanded to contain any counters: So the result will for example
12701 \begin_inset Quotes eld
12705 \begin_inset Flex Code
12708 \begin_layout Plain Layout
12719 \begin_inset Quotes erd
12724 \begin_inset space ~
12728 \begin_inset CommandInset ref
12730 reference "sub:Counters"
12734 for more information on counters.
12737 \begin_layout Description
12738 \begin_inset Flex Code
12741 \begin_layout Plain Layout
12747 produces the usual sort of enumeration labels.
12748 At present, it is hardcoded to use Arabic numerals, lowercase letters,
12749 small Roman numerals, and uppercase letters for the four possible depths.
12752 \begin_layout Description
12753 \begin_inset Flex Code
12756 \begin_layout Plain Layout
12762 produces various bullets at the different levels.
12763 It is also hardcoded.
12766 \begin_layout Description
12767 \begin_inset Flex Code
12770 \begin_layout Plain Layout
12776 is used internally by LyX and should be used only with
12777 \begin_inset Flex Code
12780 \begin_layout Plain Layout
12781 LatexType BibEnvironment
12790 \begin_layout Description
12791 \begin_inset Flex Code
12794 \begin_layout Plain Layout
12800 Note that this will completely override any prior
12801 \begin_inset Flex Code
12804 \begin_layout Plain Layout
12810 declaration for this style.
12812 \begin_inset Quotes eld
12816 \begin_inset Flex Code
12819 \begin_layout Plain Layout
12826 \begin_inset Quotes erd
12831 \begin_inset CommandInset ref
12833 reference "sub:I18n"
12837 for details on its use.
12840 \begin_layout Description
12841 \begin_inset Flex Code
12844 \begin_layout Plain Layout
12851 \begin_inset Flex Code
12854 \begin_layout Plain Layout
12860 ] The name of the corresponding LaTeX stuff.
12861 Either the environment or command name.
12864 \begin_layout Description
12865 \begin_inset Flex Code
12868 \begin_layout Plain Layout
12875 \begin_inset Flex Code
12878 \begin_layout Plain Layout
12884 ] An optional parameter for the corresponding
12885 \begin_inset Flex Code
12888 \begin_layout Plain Layout
12895 This parameter cannot be changed from within LyX
12896 \change_inserted -712698321 1355144804
12898 \begin_inset Flex Code
12901 \begin_layout Plain Layout
12903 \change_inserted -712698321 1355144804
12909 for customizable parameters)
12913 \change_inserted -712698321 1355144804
12914 This will be output as is after all LaTeX
12915 \begin_inset Flex Code
12918 \begin_layout Plain Layout
12920 \change_inserted -712698321 1355144658
12933 \begin_layout Description
12934 \begin_inset Flex Code
12937 \begin_layout Plain Layout
12944 \begin_inset Flex Code
12947 \begin_layout Plain Layout
12952 , Command, Environment, Item_Environment,
12953 \begin_inset Newline newline
12956 List_Environment, Bib_Environment
12961 ] How the style should be translated into LaTeX.
12965 \begin_layout Plain Layout
12966 \begin_inset Flex Code
12969 \begin_layout Plain Layout
12975 is perhaps a bit misleading, since these rules apply to SGML classes, too.
12976 Visit the SGML class files for specific examples.
12985 \begin_layout Description
12986 \begin_inset Flex Code
12989 \begin_layout Plain Layout
12995 means nothing special.
12998 \begin_layout Description
12999 \begin_inset Flex Code
13002 \begin_layout Plain Layout
13009 \begin_inset Flex Code
13012 \begin_layout Plain Layout
13019 {\SpecialChar \ldots{}
13028 \begin_layout Description
13029 \begin_inset Flex Code
13032 \begin_layout Plain Layout
13039 \begin_inset Flex Code
13042 \begin_layout Plain Layout
13049 }\SpecialChar \ldots{}
13065 \begin_layout Description
13066 \begin_inset Flex Code
13069 \begin_layout Plain Layout
13076 \begin_inset Flex Code
13079 \begin_layout Plain Layout
13086 \begin_inset Flex Code
13089 \begin_layout Plain Layout
13097 is generated for each paragraph of this environment.
13101 \begin_layout Description
13102 \begin_inset Flex Code
13105 \begin_layout Plain Layout
13112 \begin_inset Flex Code
13115 \begin_layout Plain Layout
13122 \begin_inset Newline newline
13126 \begin_inset Flex Code
13129 \begin_layout Plain Layout
13135 is passed as an argument to the environment.
13136 \begin_inset Newline newline
13140 \begin_inset Flex Code
13143 \begin_layout Plain Layout
13149 can be defined in the
13150 \begin_inset Flex MenuItem
13153 \begin_layout Plain Layout
13154 Edit\SpecialChar \menuseparator
13156 \begin_inset space ~
13167 \begin_layout Description
13168 \begin_inset Flex Code
13171 \begin_layout Plain Layout
13178 \begin_inset Flex Code
13181 \begin_layout Plain Layout
13187 but adds additionally the necessary mandatory argument to the begin statement
13188 of the bibliography environment:
13189 \begin_inset Newline newline
13193 \begin_inset Flex Code
13196 \begin_layout Plain Layout
13199 begin{thebibliography}{99}
13204 It is therefore only useful for bibliography environments.
13207 \begin_layout Standard
13208 Putting the last few things together, the LaTeX output will be either:
13211 \begin_layout LyX-Code
13214 LatexName[LatexParam]{\SpecialChar \ldots{}
13218 \begin_layout Standard
13222 \begin_layout LyX-Code
13225 begin{LatexName}[LatexParam] \SpecialChar \ldots{}
13231 \begin_layout Standard
13232 depending upon the LaTeX type.
13236 \begin_layout Description
13238 \change_inserted -712698321 1354263086
13239 \begin_inset Flex Code
13242 \begin_layout Plain Layout
13244 \change_inserted -712698321 1353866852
13251 \begin_inset Flex Code
13254 \begin_layout Plain Layout
13256 \change_inserted -712698321 1353866852
13262 ] A string that is put at the beginning of the style content.
13263 A line break in the output can be indicated by
13264 \begin_inset Flex Code
13267 \begin_layout Plain Layout
13269 \change_inserted -712698321 1354263086
13280 \begin_layout Description
13281 \begin_inset Flex Code
13284 \begin_layout Plain Layout
13291 \begin_inset Flex Code
13294 \begin_layout Plain Layout
13300 ] If you put styles into environments, the different
13301 \begin_inset Flex Code
13304 \begin_layout Plain Layout
13310 are not simply added, but added with a factor
13311 \begin_inset Formula $\frac{4}{\mathrm{depth}+4}$
13315 Note that this parameter is also used when
13316 \begin_inset Flex Code
13319 \begin_layout Plain Layout
13326 \begin_inset Flex Code
13329 \begin_layout Plain Layout
13336 \begin_inset Flex Code
13339 \begin_layout Plain Layout
13346 Then it is added to the manual or dynamic margin.
13347 \begin_inset Newline newline
13351 \begin_inset Quotes eld
13355 \begin_inset Flex Code
13358 \begin_layout Plain Layout
13365 \begin_inset Quotes erd
13368 means that the paragraph is indented with the width of
13369 \begin_inset Quotes eld
13373 \begin_inset Flex Code
13376 \begin_layout Plain Layout
13383 \begin_inset Quotes erd
13386 in the normal font.
13387 You can get a negative width by prefixing the string with
13388 \begin_inset Quotes eld
13392 \begin_inset Flex Code
13395 \begin_layout Plain Layout
13402 \begin_inset Quotes erd
13406 This way was chosen so that the look is the same with each used screen
13410 \begin_layout Description
13411 \begin_inset Flex Code
13414 \begin_layout Plain Layout
13421 \begin_inset Flex Code
13424 \begin_layout Plain Layout
13429 , Manual, Dynamic, First_Dynamic, Right_Address_Box
13435 \begin_inset Newline newline
13438 The kind of margin that the style has on the left side.
13442 \begin_layout Description
13443 \begin_inset Flex Code
13446 \begin_layout Plain Layout
13452 just means a fixed margin.
13455 \begin_layout Description
13456 \begin_inset Flex Code
13459 \begin_layout Plain Layout
13465 means that the left margin depends on the string entered in the
13466 \begin_inset Flex MenuItem
13469 \begin_layout Plain Layout
13470 Edit\SpecialChar \menuseparator
13472 \begin_inset space ~
13481 This is used to typeset nice lists without tabulators.
13484 \begin_layout Description
13485 \begin_inset Flex Code
13488 \begin_layout Plain Layout
13494 means that the margin depends on the size of the label.
13495 This is used for automatic enumerated headlines.
13496 It is obvious that the headline
13497 \begin_inset Quotes eld
13500 5.4.3.2.1 Very long headline
13501 \begin_inset Quotes erd
13504 must have a wider left margin (as wide as
13505 \begin_inset Quotes eld
13509 \begin_inset Quotes erd
13512 plus the space) than
13513 \begin_inset Quotes eld
13516 3.2 Very long headline
13517 \begin_inset Quotes erd
13521 \begin_inset Quotes eld
13525 \begin_inset Quotes erd
13528 are not able to do this.
13531 \begin_layout Description
13532 \begin_inset Flex Code
13535 \begin_layout Plain Layout
13541 is similar, but only the very first row of the paragraph is dynamic, while
13542 the others are static; this is used, for example, for descriptions.
13545 \begin_layout Description
13546 \begin_inset Flex Code
13549 \begin_layout Plain Layout
13555 means the margin is chosen in a way that the longest row of this paragraph
13556 fits to the right margin.
13557 This is used to typeset an address on the right edge of the page.
13561 \begin_layout Description
13562 \begin_inset Flex Code
13565 \begin_layout Plain Layout
13572 \begin_inset Flex Code
13575 \begin_layout Plain Layout
13584 \begin_inset space \thinspace{}
13588 \begin_inset Flex Code
13591 \begin_layout Plain Layout
13597 ] Whether fragile commands in this style should be
13598 \begin_inset Flex Code
13601 \begin_layout Plain Layout
13614 whether this command should itself be protected.)
13617 \begin_layout Description
13618 \begin_inset Flex Code
13621 \begin_layout Plain Layout
13628 \begin_inset Flex Code
13631 \begin_layout Plain Layout
13638 \begin_inset space \thinspace{}
13642 \begin_inset Flex Code
13645 \begin_layout Plain Layout
13653 ] Whether newlines are translated into LaTeX newlines (
13654 \begin_inset Flex Code
13657 \begin_layout Plain Layout
13668 The translation can be switched off to allow more comfortable LaTeX editing
13672 \begin_layout Description
13673 \begin_inset Flex Code
13676 \begin_layout Plain Layout
13683 \begin_inset Flex Code
13686 \begin_layout Plain Layout
13695 \begin_inset space \thinspace{}
13699 \begin_inset Flex Code
13702 \begin_layout Plain Layout
13708 ] If set to true, and if
13709 \begin_inset Flex Code
13712 \begin_layout Plain Layout
13719 \begin_inset Flex Code
13722 \begin_layout Plain Layout
13728 ) paragraphs are being indented, then the indentation of such a paragraph
13729 following one of this type will be suppressed.
13730 (So this will not affect the display of non-default paragraphs.)
13733 \begin_layout Description
13734 \begin_inset Flex Code
13737 \begin_layout Plain Layout
13744 \begin_inset Flex Code
13747 \begin_layout Plain Layout
13753 ] Name of a style that has replaced this style.
13754 This is used to rename a style, while keeping backward compatibility.
13757 \begin_layout Description
13759 \change_deleted -712698321 1353679722
13760 \begin_inset Flex Code
13763 \begin_layout Plain Layout
13770 \begin_inset Flex Code
13773 \begin_layout Plain Layout
13779 ] The number of optional arguments that can be used with this style.
13780 This is useful for things like section headings, and only makes sense with
13782 Note that, on output, the optional arguments will all precede any required
13783 arguments (see below).
13784 So one can have constructs like:
13788 \begin_layout LyX-Code
13790 \change_deleted -712698321 1353679722
13793 mycmd[opt1]{req1}{contents of paragraph}
13796 \begin_layout Standard
13798 \change_deleted -712698321 1353679722
13799 but one cannot have things like:
13802 \begin_layout LyX-Code
13804 \change_deleted -712698321 1353679722
13807 mycmd[opt1]{req1}[opt2]{contents of paragraph}
13810 \begin_layout Standard
13812 \change_deleted -712698321 1353679722
13813 at least, not without ERT (with which you can have anything).
13820 \begin_layout Description
13821 \begin_inset Flex Code
13824 \begin_layout Plain Layout
13831 \begin_inset Flex Code
13834 \begin_layout Plain Layout
13843 \begin_inset space \thinspace{}
13847 \begin_inset Flex Code
13850 \begin_layout Plain Layout
13856 ] Indicates that paragraphs will not be separated by an empty line in LaTeX
13857 output, but only by a line break; together with
13858 \begin_inset Flex Code
13861 \begin_layout Plain Layout
13867 , this allows to emulate a plain text editor (like the ERT inset).
13870 \begin_layout Description
13871 \begin_inset Flex Code
13874 \begin_layout Plain Layout
13881 \begin_inset Flex Code
13884 \begin_layout Plain Layout
13890 ] The indent of the very first line of a paragraph.
13892 \begin_inset Newline newline
13896 \begin_inset Flex Code
13899 \begin_layout Plain Layout
13905 will be fixed for a certain style.
13906 The exception is the default style, since the indentation for these paragraphs
13907 can be prohibited with
13908 \begin_inset Flex Code
13911 \begin_layout Plain Layout
13919 \begin_inset Flex Code
13922 \begin_layout Plain Layout
13928 style paragraphs inside environments use the
13929 \begin_inset Flex Code
13932 \begin_layout Plain Layout
13938 of the environment, not their native one.
13940 \begin_inset Flex Code
13943 \begin_layout Plain Layout
13949 paragraphs inside an enumeration are not indented.
13952 \begin_layout Description
13953 \begin_inset Flex Code
13956 \begin_layout Plain Layout
13963 \begin_inset Flex Code
13966 \begin_layout Plain Layout
13972 ] The vertical space between two paragraphs of this style.
13975 \begin_layout Description
13976 \begin_inset Flex Code
13979 \begin_layout Plain Layout
13986 \begin_inset Flex Code
13989 \begin_layout Plain Layout
13995 ] LyX allows the user to choose either
13996 \begin_inset Quotes eld
14000 \begin_inset Quotes erd
14004 \begin_inset Quotes eld
14008 \begin_inset Quotes erd
14011 to separate paragraphs.
14013 \begin_inset Quotes eld
14017 \begin_inset Quotes erd
14021 \begin_inset Flex Code
14024 \begin_layout Plain Layout
14032 \begin_inset Quotes eld
14036 \begin_inset Quotes erd
14040 \begin_inset Flex Code
14043 \begin_layout Plain Layout
14049 is ignored and all paragraphs are separated by the
14050 \begin_inset Flex Code
14053 \begin_layout Plain Layout
14060 The vertical space is calculated with
14061 \begin_inset Flex Code
14064 \begin_layout Plain Layout
14066 \begin_inset space ~
14075 \begin_inset Flex Code
14078 \begin_layout Plain Layout
14084 is the height of a row with the normal font.
14085 This way, the look stays the same with different screen fonts.
14088 \begin_layout Description
14089 \begin_inset Flex Code
14092 \begin_layout Plain Layout
14099 \begin_inset Flex Code
14102 \begin_layout Plain Layout
14111 \begin_inset space \thinspace{}
14115 \begin_inset Flex Code
14118 \begin_layout Plain Layout
14124 ] Whether the contents of this paragraph should be output in raw form, meaning
14125 without special translations that LaTeX would require.
14128 \begin_layout Description
14129 \begin_inset Flex Code
14132 \begin_layout Plain Layout
14138 Information to be included in the LaTeX preamble when this style is used.
14139 Used to define macros, load packages, etc., required by this particular
14142 \begin_inset Quotes eld
14146 \begin_inset Flex Code
14149 \begin_layout Plain Layout
14156 \begin_inset Quotes erd
14162 \begin_layout Description
14163 \begin_inset Flex Code
14166 \begin_layout Plain Layout
14173 \begin_inset Flex Code
14176 \begin_layout Plain Layout
14182 ] The prefix to use when creating labels referring to paragraphs of this
14184 This allows the use of formatted references.
14187 \begin_layout Description
14189 \change_deleted -712698321 1353681258
14190 \begin_inset Flex Code
14193 \begin_layout Plain Layout
14200 \begin_inset Flex Code
14203 \begin_layout Plain Layout
14209 ] The number of required arguments that the LaTeX command or environment
14210 corresponding to this style expects.
14211 In the case of a command, these are required arguments
14215 that associated with the content of the paragraph itself.
14216 These do not actually have to be provided: LyX will output empty arguments
14218 Note that optional arguments will be output before required arguments.
14219 See the discussion of the
14220 \begin_inset Flex Code
14223 \begin_layout Plain Layout
14229 tag above for more information.
14234 \begin_layout Description
14235 \begin_inset Flex Code
14238 \begin_layout Plain Layout
14245 \begin_inset Flex Code
14248 \begin_layout Plain Layout
14254 ] Whether the style requires the feature
14255 \begin_inset Flex Code
14258 \begin_layout Plain Layout
14265 See the description of
14266 \begin_inset Flex Code
14269 \begin_layout Plain Layout
14276 \begin_inset space ~
14280 \begin_inset CommandInset ref
14282 reference "sub:General-text-class"
14286 ) for information on `features'.
14289 \begin_layout Description
14291 \change_inserted -712698321 1353693371
14292 \begin_inset Flex Code
14295 \begin_layout Plain Layout
14297 \change_inserted -712698321 1353693146
14306 \begin_inset Flex Code
14309 \begin_layout Plain Layout
14311 \change_inserted -712698321 1353693235
14320 \begin_inset Flex Code
14323 \begin_layout Plain Layout
14325 \change_inserted -712698321 1353693235
14331 ] Resets the LaTeX arguments of this style (as defined via the
14332 \begin_inset Flex Code
14335 \begin_layout Plain Layout
14337 \change_inserted -712698321 1353693371
14346 This is useful if you have copied a style via
14347 \begin_inset Flex Code
14350 \begin_layout Plain Layout
14352 \change_inserted -712698321 1353693302
14360 , but you do not want to inherit its (required and optional) arguments.
14365 \begin_layout Description
14367 \change_inserted -712698321 1354263074
14368 \begin_inset Flex Code
14371 \begin_layout Plain Layout
14373 \change_inserted -712698321 1353866876
14380 \begin_inset Flex Code
14383 \begin_layout Plain Layout
14385 \change_inserted -712698321 1353866873
14391 ] A string that is put at the end of the layout content.
14392 A line break in the output can be indicated by
14393 \begin_inset Flex Code
14396 \begin_layout Plain Layout
14398 \change_inserted -712698321 1354263069
14409 \begin_layout Description
14410 \begin_inset Flex Code
14413 \begin_layout Plain Layout
14420 \begin_inset Flex Code
14423 \begin_layout Plain Layout
14430 \begin_inset Flex Code
14433 \begin_layout Plain Layout
14442 \begin_layout Description
14443 \begin_inset Flex Code
14446 \begin_layout Plain Layout
14453 \begin_inset Flex Code
14456 \begin_layout Plain Layout
14465 \begin_inset Flex Code
14468 \begin_layout Plain Layout
14475 \begin_inset Flex Code
14478 \begin_layout Plain Layout
14485 \begin_inset Flex Code
14488 \begin_layout Plain Layout
14490 \begin_inset space ~
14498 ] This defines what the default spacing should be in the style.
14500 \begin_inset Flex Code
14503 \begin_layout Plain Layout
14510 \begin_inset Flex Code
14513 \begin_layout Plain Layout
14520 \begin_inset Flex Code
14523 \begin_layout Plain Layout
14529 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
14530 If you specify the argument
14531 \begin_inset Flex Code
14534 \begin_layout Plain Layout
14540 , then you must also provide a value argument which will be the actual multiplie
14542 Note that, contrary to other parameters,
14543 \begin_inset Flex Code
14546 \begin_layout Plain Layout
14552 implies the generation of specific LaTeX code, using the LaTeX package
14556 \begin_inset Flex Code
14559 \begin_layout Plain Layout
14568 \begin_layout Description
14569 \begin_inset Flex Code
14572 \begin_layout Plain Layout
14579 \begin_inset Flex Code
14582 \begin_layout Plain Layout
14589 \begin_inset space \thinspace{}
14593 \begin_inset Flex Code
14596 \begin_layout Plain Layout
14604 ] Allow spell-checking paragraphs of this style.
14608 \begin_layout Description
14609 \begin_inset Flex Code
14612 \begin_layout Plain Layout
14618 The font used for the text body .
14620 \begin_inset CommandInset ref
14622 reference "sub:Font-description"
14629 \begin_layout Description
14630 \begin_inset Flex Code
14633 \begin_layout Plain Layout
14642 \begin_inset Flex Code
14645 \begin_layout Plain Layout
14655 The level of the style in the table of contents.
14656 This is used for automatic numbering of section headings.
14659 \begin_layout Description
14660 \begin_inset Flex Code
14663 \begin_layout Plain Layout
14670 \begin_inset Flex Code
14673 \begin_layout Plain Layout
14679 ] The vertical space with which the very first of a chain of paragraphs
14680 with this style is separated from the previous paragraph.
14681 If the previous paragraph has another style, the separations are not simply
14682 added, but the maximum is taken.
14685 \begin_layout Subsection
14686 \begin_inset CommandInset label
14692 Internationalization of Paragraph Styles
14695 \begin_layout Standard
14696 LyX has long supported internationalization of layout information, but,
14697 until version 2.0, this applied only to the user interface and not to, say,
14699 Thus, French authors were forced to resort to ugly hacks if they wanted
14704 1' instead of `Theorem 1'.
14705 Thanks to Georg Baum, that is no longer the case.
14708 \begin_layout Standard
14710 \begin_inset Flex Code
14713 \begin_layout Plain Layout
14719 defines text that is to appear in the typeset document, it may use
14720 \begin_inset Flex Code
14723 \begin_layout Plain Layout
14730 \begin_inset Flex Code
14733 \begin_layout Plain Layout
14739 to support non-English and even multi-language documents correctly.
14740 The following excerpt (from the
14741 \begin_inset Flex Code
14744 \begin_layout Plain Layout
14750 file) shows how this works:
14753 \begin_layout LyX-Code
14758 \begin_layout LyX-Code
14761 theoremstyle{remark}
14764 \begin_layout LyX-Code
14767 newtheorem{claim}[thm]{
14774 \begin_layout LyX-Code
14778 \begin_layout LyX-Code
14782 \begin_layout LyX-Code
14787 claimname}{_(Claim)}
14790 \begin_layout LyX-Code
14794 \begin_layout LyX-Code
14798 \begin_layout LyX-Code
14807 claimname}{_(Claim)}}
14810 \begin_layout LyX-Code
14815 \begin_layout Standard
14816 In principle, any legal LaTeX may appear in the
14817 \begin_inset Flex Code
14820 \begin_layout Plain Layout
14827 \begin_inset Flex Code
14830 \begin_layout Plain Layout
14836 tags, but in practice they will typically look as they do here.
14837 The key to correct translation of the typeset text is the definition of
14839 \begin_inset Flex Code
14842 \begin_layout Plain Layout
14851 \begin_inset Flex Code
14854 \begin_layout Plain Layout
14866 \begin_layout Standard
14868 \begin_inset Flex Code
14871 \begin_layout Plain Layout
14877 tag provides for internationalization based upon the overall language of
14879 The contents of the tag will be included in the preamble, just as with
14881 \begin_inset Flex Code
14884 \begin_layout Plain Layout
14891 What makes it special is the use of the
14892 \begin_inset Quotes eld
14896 \begin_inset Quotes erd
14900 \begin_inset Flex Code
14903 \begin_layout Plain Layout
14909 , which will be replaced, when LyX produces LaTeX output, with the translation
14910 of its argument into the document language.
14913 \begin_layout Standard
14915 \begin_inset Flex Code
14918 \begin_layout Plain Layout
14924 tag is more complex, since it is meant to provide support for multi-language
14925 documents and so offers an interface to the
14926 \begin_inset Flex Code
14929 \begin_layout Plain Layout
14936 Its contents will be added to the preamble once for each language that
14937 appears in the document.
14938 In this case, the argument to
14939 \begin_inset Flex Code
14942 \begin_layout Plain Layout
14948 will be replaced with its translation into the language in question; the
14950 \begin_inset Flex Code
14953 \begin_layout Plain Layout
14959 is replaced by the language name (as used by the babel package).
14962 \begin_layout Standard
14963 A German document that also included a French section would thus have the
14964 following in the preamble:
14967 \begin_layout LyX-Code
14976 claimname}{Affirmation}}
14977 \begin_inset Newline newline
14988 claimname}{Behauptung}}
14989 \begin_inset Newline newline
14996 claimname}{Behauptung}
14999 \begin_layout Standard
15001 \begin_inset Flex Code
15004 \begin_layout Plain Layout
15010 will then conspire to produce the correct text in the output.
15013 \begin_layout Standard
15014 One important point to note here is that the translations are provided by
15015 LyX itself, through the
15016 \change_inserted -195340706 1334775793
15018 \begin_inset Flex Code
15021 \begin_layout Plain Layout
15023 \change_inserted -195340706 1334775793
15030 \change_deleted -195340706 1334775793
15031 same mechanism it uses for internationalization of the user interface
15034 This means, in effect, that
15035 \begin_inset Flex Code
15038 \begin_layout Plain Layout
15045 \begin_inset Flex Code
15048 \begin_layout Plain Layout
15054 are really only of use in layout files that are provided with LyX, since
15055 text entered in user-created layout files will not be seen by LyX's internation
15057 \change_inserted -195340706 1334775793
15059 \begin_inset Flex Code
15062 \begin_layout Plain Layout
15064 \change_inserted -195340706 1334775793
15070 file is modified accordingly
15073 That said, however, any layout created with the intention that it will
15074 be included with LyX should use these tags where appropriate.
15076 \change_inserted -195340706 1334775793
15077 Please note that the paragraph style translations provided by LyX will
15078 never change with a minor update (e.g.
15079 from version 2.1.x to 2.1.y).
15080 It is however quite likely that a major update (e.g.
15081 from 2.0.x to 2.1.y) will introduce new translations or corrections.
15086 \begin_layout Subsection
15088 \begin_inset CommandInset label
15097 \begin_layout Standard
15098 It is necessary to define the floats (
15099 \begin_inset Flex MenuItem
15102 \begin_layout Plain Layout
15109 \begin_inset Flex MenuItem
15112 \begin_layout Plain Layout
15118 , \SpecialChar \ldots{}
15119 ) in the text class itself.
15120 Standard floats are included in the file
15121 \begin_inset Flex Code
15124 \begin_layout Plain Layout
15130 , so you may have to do no more than add
15133 \begin_layout LyX-Code
15134 Input stdfloats.inc
15137 \begin_layout Standard
15138 to your layout file.
15139 If you want to implement a text class that proposes some other float types
15140 (like the AGU class bundled with LyX), the information below will hopefully
15144 \begin_layout Description
15145 \begin_inset Flex Code
15148 \begin_layout Plain Layout
15155 \begin_inset Flex Code
15158 \begin_layout Plain Layout
15165 \begin_inset Quotes erd
15169 \begin_inset Quotes erd
15172 ] The file name extension of an auxiliary file for the list of figures (or
15174 LaTeX writes the captions to this file.
15177 \begin_layout Description
15178 \begin_inset Flex Code
15181 \begin_layout Plain Layout
15188 \begin_inset Flex Code
15191 \begin_layout Plain Layout
15198 \begin_inset Quotes erd
15202 \begin_inset Quotes erd
15205 ] The string that will be used in the menus and also for the caption.
15206 This is translated to the current language if babel is used.
15209 \begin_layout Description
15210 \begin_inset Flex Code
15213 \begin_layout Plain Layout
15219 These tags control the XHTML output.
15221 \begin_inset space ~
15225 \begin_inset CommandInset ref
15227 reference "sec:Tags-for-XHTML"
15234 \begin_layout Description
15235 \begin_inset Flex Code
15238 \begin_layout Plain Layout
15247 \begin_inset Flex Code
15250 \begin_layout Plain Layout
15259 \begin_inset space \thinspace{}
15263 \begin_inset Flex Code
15266 \begin_layout Plain Layout
15272 ] Indicates whether the float is already defined in the document class or
15273 if instead the LaTeX package
15274 \begin_inset Flex Code
15277 \begin_layout Plain Layout
15283 needs to be loaded to define it on-the-fly.
15285 \begin_inset Flex Code
15288 \begin_layout Plain Layout
15295 \begin_inset Flex Code
15298 \begin_layout Plain Layout
15305 It should be set to
15306 \begin_inset Flex Code
15309 \begin_layout Plain Layout
15315 if the float is already defined by the LaTeX document class.
15318 \begin_layout Description
15319 \begin_inset Flex Code
15322 \begin_layout Plain Layout
15329 \begin_inset Flex Code
15332 \begin_layout Plain Layout
15339 \begin_inset Quotes erd
15343 \begin_inset Quotes erd
15346 ] The command used to generate a list of floats of this type; the leading
15355 \begin_inset Flex Code
15358 \begin_layout Plain Layout
15364 is false, since there is no standard way to generate this command.
15366 \begin_inset Flex Code
15369 \begin_layout Plain Layout
15375 is true, since in that case there is a standard way to define the command.
15378 \begin_layout Description
15379 \begin_inset Flex Code
15382 \begin_layout Plain Layout
15389 \begin_inset Flex Code
15392 \begin_layout Plain Layout
15399 \begin_inset Quotes erd
15403 \begin_inset Quotes erd
15406 ] A title for a list of floats of this kind (list of figures, tables, or
15408 It is used for the screen label within LyX, it is used by LaTeX for the
15409 title and it is used as the title in the XHTML output.
15410 It will be translated to the document language.
15413 \begin_layout Description
15414 \begin_inset Flex Code
15417 \begin_layout Plain Layout
15424 \begin_inset Flex Code
15427 \begin_layout Plain Layout
15434 \begin_inset Quotes erd
15438 \begin_inset Quotes erd
15441 ] This (optional) argument determines whether floats of this class will
15442 be numbered within some sectional unit of the document.
15444 \begin_inset Flex Code
15447 \begin_layout Plain Layout
15454 \begin_inset Quotes eld
15458 \begin_inset Flex Code
15461 \begin_layout Plain Layout
15468 \begin_inset Quotes erd
15471 , the floats will be numbered within chapters.
15475 \begin_layout Description
15476 \begin_inset Flex Code
15479 \begin_layout Plain Layout
15486 \begin_inset Flex Code
15489 \begin_layout Plain Layout
15496 \begin_inset Quotes erd
15500 \begin_inset Quotes erd
15503 ] The default placement for the given class of floats.
15504 The string should be as in standard LaTeX:
15505 \begin_inset Flex Code
15508 \begin_layout Plain Layout
15515 \begin_inset Flex Code
15518 \begin_layout Plain Layout
15525 \begin_inset Flex Code
15528 \begin_layout Plain Layout
15535 \begin_inset Flex Code
15538 \begin_layout Plain Layout
15544 for top, bottom, page, and here, respectively.
15548 \begin_layout Plain Layout
15549 Note that the order of these letters in the string is irrelevant, like in
15555 On top of that there is a new type,
15556 \begin_inset Flex Code
15559 \begin_layout Plain Layout
15565 , which does not really correspond to a float, since it means: put it
15566 \begin_inset Quotes eld
15570 \begin_inset Quotes erd
15574 Note however that the
15575 \begin_inset Flex Code
15578 \begin_layout Plain Layout
15584 specifier is special and, because of implementation details, cannot be
15585 used in non-built in float types.
15586 If you do not understand what this means, just use
15587 \begin_inset Quotes eld
15591 \begin_inset Flex Code
15594 \begin_layout Plain Layout
15601 \begin_inset Quotes erd
15607 \begin_layout Description
15608 \begin_inset Flex Code
15611 \begin_layout Plain Layout
15618 \begin_inset Flex Code
15621 \begin_layout Plain Layout
15627 ] The prefix to use when creating labels referring to floats of this type.
15628 This allows the use of formatted references.
15629 Note that you can remove any
15630 \begin_inset Flex Code
15633 \begin_layout Plain Layout
15639 set by a copied style by using the special value
15640 \begin_inset Quotes eld
15644 \begin_inset Quotes erd
15647 , which must be all caps.
15650 \begin_layout Description
15651 \begin_inset Flex Code
15654 \begin_layout Plain Layout
15661 \begin_inset Flex Code
15664 \begin_layout Plain Layout
15671 \begin_inset Quotes erd
15675 \begin_inset Quotes erd
15678 ] The style used when defining the float using
15679 \begin_inset Flex Code
15682 \begin_layout Plain Layout
15693 \begin_layout Description
15694 \begin_inset Flex Code
15697 \begin_layout Plain Layout
15704 \begin_inset Flex Code
15707 \begin_layout Plain Layout
15714 \begin_inset Quotes erd
15718 \begin_inset Quotes erd
15722 \begin_inset Quotes eld
15726 \begin_inset Quotes erd
15729 of the new class of floats, like program or algorithm.
15730 After the appropriate
15731 \begin_inset Flex Code
15734 \begin_layout Plain Layout
15743 \begin_inset Flex Code
15746 \begin_layout Plain Layout
15755 \begin_inset Flex Code
15758 \begin_layout Plain Layout
15769 \begin_layout Description
15770 \begin_inset Flex Code
15773 \begin_layout Plain Layout
15780 \begin_inset Flex Code
15783 \begin_layout Plain Layout
15790 \begin_inset space \thinspace{}
15794 \begin_inset Flex Code
15797 \begin_layout Plain Layout
15805 ] Specifies whether this float is defined using the LaTeX package
15806 \begin_inset Flex Code
15809 \begin_layout Plain Layout
15815 , either by the class file, another package or on-the-fly by LyX itself.
15818 \begin_layout Standard
15819 Note that defining a float with type
15820 \begin_inset Flex Code
15823 \begin_layout Plain Layout
15831 automatically defines the corresponding counter with name
15832 \begin_inset Flex Code
15835 \begin_layout Plain Layout
15846 \begin_layout Subsection
15847 Flex insets and InsetLayout
15848 \begin_inset CommandInset label
15850 name "sub:Flex-insets-and"
15857 \begin_layout Standard
15858 Flex insets come in three different kinds:
15861 \begin_layout Itemize
15863 \begin_inset Flex Code
15866 \begin_layout Plain Layout
15872 ): These define semantic markup corresponding to such LaTeX commands as
15874 \begin_inset Flex Code
15877 \begin_layout Plain Layout
15886 \begin_inset Flex Code
15889 \begin_layout Plain Layout
15900 \begin_layout Itemize
15902 \begin_inset Flex Code
15905 \begin_layout Plain Layout
15911 ): These can be used to define custom collapsible insets, similar to TeX
15912 code, footnote, and the like.
15913 An obvious example is an endnote inset, which is defined in the
15914 \begin_inset Flex Code
15917 \begin_layout Plain Layout
15926 \begin_layout Itemize
15928 \begin_inset Flex Code
15931 \begin_layout Plain Layout
15937 ): For use with DocBook classes.
15940 \begin_layout Standard
15941 Flex insets are defined using the
15942 \begin_inset Flex Code
15945 \begin_layout Plain Layout
15951 tag, which shall be explained in a moment.
15954 \begin_layout Standard
15956 \begin_inset Flex Code
15959 \begin_layout Plain Layout
15965 tag also serves another function: It can be used to customize the general
15966 layout of many different types of insets.
15968 \begin_inset Flex Code
15971 \begin_layout Plain Layout
15977 can be used to customize the layout parameters for footnotes, marginal
15978 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
15979 boxes, tables, algorithms, URLs, and optional arguments, as well as to
15980 define Flex insets.
15983 \begin_layout Standard
15985 \begin_inset Flex Code
15988 \begin_layout Plain Layout
15994 definition must begin with a line of the form:
15997 \begin_layout LyX-Code
16001 \begin_layout Standard
16003 \begin_inset Flex Code
16006 \begin_layout Plain Layout
16012 indicates the inset whose layout is being defined, and here there are
16013 \change_inserted 5863208 1334489266
16015 \change_deleted 5863208 1334489267
16021 \begin_layout Enumerate
16022 The layout for a pre-existing inset is being modified.
16023 In this case, can be
16024 \begin_inset Flex Code
16027 \begin_layout Plain Layout
16033 any one of the following:
16034 \begin_inset Flex Code
16037 \begin_layout Plain Layout
16044 \begin_inset Flex Code
16047 \begin_layout Plain Layout
16054 \begin_inset Flex Code
16057 \begin_layout Plain Layout
16064 \begin_inset Flex Code
16067 \begin_layout Plain Layout
16074 \begin_inset Flex Code
16077 \begin_layout Plain Layout
16084 \begin_inset Flex Code
16087 \begin_layout Plain Layout
16094 \begin_inset Flex Code
16097 \begin_layout Plain Layout
16104 \begin_inset Flex Code
16107 \begin_layout Plain Layout
16114 \begin_inset Flex Code
16117 \begin_layout Plain Layout
16124 \begin_inset Flex Code
16127 \begin_layout Plain Layout
16134 \begin_inset Flex Code
16137 \begin_layout Plain Layout
16144 \begin_inset Flex Code
16147 \begin_layout Plain Layout
16154 \begin_inset Flex Code
16157 \begin_layout Plain Layout
16164 \begin_inset Flex Code
16167 \begin_layout Plain Layout
16174 \begin_inset Flex Code
16177 \begin_layout Plain Layout
16184 \begin_inset Flex Code
16187 \begin_layout Plain Layout
16194 \begin_inset Flex Code
16197 \begin_layout Plain Layout
16204 \begin_inset Flex Code
16207 \begin_layout Plain Layout
16209 \change_deleted -712698321 1353866704
16213 \change_inserted -712698321 1353866707
16222 \begin_inset Flex Code
16225 \begin_layout Plain Layout
16232 \begin_inset Flex Code
16235 \begin_layout Plain Layout
16244 \begin_layout Enumerate
16245 The layout for a Flex inset is being defined.
16247 \begin_inset Flex Code
16250 \begin_layout Plain Layout
16256 must be of the form
16257 \begin_inset Quotes eld
16261 \begin_inset Flex Code
16264 \begin_layout Plain Layout
16271 \begin_inset Quotes erd
16275 \begin_inset Flex Code
16278 \begin_layout Plain Layout
16284 may be be any valid identifier not used by a pre-existing Flex inset.
16285 The identifier may include spaces, but in that case the whole thing must
16286 be wrapped in quotes.
16287 Note that the definition of a flex inset
16292 \begin_inset Flex Code
16295 \begin_layout Plain Layout
16301 entry, declaring which type of inset it defines.
16302 \change_inserted 5863208 1334489312
16306 \begin_layout Enumerate
16308 \change_inserted 5863208 1334492248
16309 The layout for user specific branch is being defined.
16311 \begin_inset Flex Code
16314 \begin_layout Plain Layout
16316 \change_inserted 5863208 1334489384
16322 must be of the form
16323 \begin_inset Quotes eld
16327 \begin_inset Flex Code
16330 \begin_layout Plain Layout
16332 \change_inserted 5863208 1334489392
16339 \begin_inset Quotes erd
16343 \begin_inset Flex Code
16346 \begin_layout Plain Layout
16348 \change_inserted 5863208 1334489384
16354 may be be any valid identifier of branch defined in user's document.
16355 The identifier may include spaces, but in that case the whole thing must
16356 be wrapped in quotes.
16357 The main purpose of this feature is to allow LaTeX wrapping around specific
16358 branches as user needs.
16363 \begin_layout Standard
16365 \begin_inset Flex Code
16368 \begin_layout Plain Layout
16374 definition can contain the following entries:
16377 \begin_layout Description
16379 \change_inserted -712698321 1353681390
16380 \begin_inset Flex Code
16383 \begin_layout Plain Layout
16385 \change_inserted -712698321 1353681344
16392 \begin_inset Flex Code
16395 \begin_layout Plain Layout
16397 \change_inserted -712698321 1353681344
16403 ] Defines argument number <int> of a command\SpecialChar \slash{}
16404 environment associated with
16405 the current layout.
16406 The definition must end with
16407 \begin_inset Flex Code
16410 \begin_layout Plain Layout
16412 \change_inserted -712698321 1353681344
16420 \begin_inset space ~
16424 \begin_inset CommandInset ref
16426 reference "sub:Paragraph-Styles"
16433 \begin_layout Description
16435 \change_inserted -195340706 1333913893
16436 \begin_inset Flex Code
16439 \begin_layout Plain Layout
16445 Preamble for changing languages.
16447 \begin_inset space ~
16451 \begin_inset CommandInset ref
16453 reference "sub:I18n"
16460 \begin_layout Description
16461 \begin_inset Flex Code
16464 \begin_layout Plain Layout
16471 \begin_inset Flex Code
16474 \begin_layout Plain Layout
16480 ] The color for the inset's background.
16481 The valid color names are defined in
16482 \begin_inset Flex Code
16485 \begin_layout Plain Layout
16494 \begin_layout Description
16495 \begin_inset Flex Code
16498 \begin_layout Plain Layout
16505 \begin_inset Flex Code
16508 \begin_layout Plain Layout
16517 \begin_inset space \thinspace{}
16521 \begin_inset Flex Code
16524 \begin_layout Plain Layout
16530 ] Whether to use the content of the inset as the label, when the inset is
16535 \begin_layout Description
16536 \begin_inset Flex Code
16539 \begin_layout Plain Layout
16546 \begin_inset Flex Code
16549 \begin_layout Plain Layout
16555 ] As with paragraph styles, see sec.
16556 \begin_inset space ~
16560 \begin_inset CommandInset ref
16562 reference "sub:Paragraph-Styles"
16567 Note that you need to specify the complete type, e.
16568 \begin_inset space \thinspace{}
16572 \begin_inset space ~
16576 \begin_inset Flex Code
16579 \begin_layout Plain Layout
16580 CopyStyle Flex:<name>
16588 \begin_layout Description
16589 \begin_inset Flex Code
16592 \begin_layout Plain Layout
16599 \begin_inset Flex Code
16602 \begin_layout Plain Layout
16611 \begin_inset space \thinspace{}
16615 \begin_inset Flex Code
16618 \begin_layout Plain Layout
16624 ] Indicates whether the user may employ the Paragraph Settings dialog to
16625 customize the paragraph.
16628 \begin_layout Description
16629 \begin_inset Flex Code
16632 \begin_layout Plain Layout
16639 \begin_inset Flex Code
16642 \begin_layout Plain Layout
16649 \begin_inset Flex Code
16652 \begin_layout Plain Layout
16659 \begin_inset Flex Code
16662 \begin_layout Plain Layout
16668 , describing the rendering style used for the inset's frame and buttons.
16669 Footnotes generally use
16670 \begin_inset Flex Code
16673 \begin_layout Plain Layout
16679 , ERT insets generally
16680 \begin_inset Flex Code
16683 \begin_layout Plain Layout
16689 , and character styles
16690 \begin_inset Flex Code
16693 \begin_layout Plain Layout
16702 \begin_layout Description
16703 \begin_inset Flex Code
16706 \begin_layout Plain Layout
16713 \begin_inset Flex Code
16716 \begin_layout Plain Layout
16725 \begin_inset space \thinspace{}
16731 \begin_inset Flex Code
16734 \begin_layout Plain Layout
16743 \begin_inset Flex Code
16746 \begin_layout Plain Layout
16753 \begin_inset Flex Code
16756 \begin_layout Plain Layout
16763 Indicates whether the environment will stand on its own in the output or
16764 will appear inline with the surrounding text.
16765 If set to false, it is supposed that the LaTeX environment ignores white
16766 space (including one newline character) after the
16767 \begin_inset Flex Code
16770 \begin_layout Plain Layout
16783 \begin_inset Flex Code
16786 \begin_layout Plain Layout
16802 \begin_layout Description
16803 \begin_inset Flex Code
16806 \begin_layout Plain Layout
16812 Required at the end of the
16813 \begin_inset Flex Code
16816 \begin_layout Plain Layout
16825 \begin_layout Description
16826 \begin_inset Flex Code
16829 \begin_layout Plain Layout
16835 The font used for both the text body
16841 \begin_inset space ~
16845 \begin_inset CommandInset ref
16847 reference "sub:Font-description"
16852 Note that defining this font automatically defines the
16853 \begin_inset Flex Code
16856 \begin_layout Plain Layout
16862 to the same value, so define this first and define
16863 \begin_inset Flex Code
16866 \begin_layout Plain Layout
16872 later if you want them to be different.
16873 \change_inserted 155139281 1354130923
16877 \begin_layout Description
16879 \change_inserted 155139281 1354130923
16880 \begin_inset Flex Code
16883 \begin_layout Plain Layout
16885 \change_inserted 155139281 1354130923
16886 ForceLocalFontSwitch
16892 \begin_inset Flex Code
16895 \begin_layout Plain Layout
16897 \change_inserted 155139281 1354130923
16906 \begin_inset Flex Code
16909 \begin_layout Plain Layout
16911 \change_inserted 155139281 1354130923
16917 ] When using babel, always use a local font switch (
16918 \begin_inset Flex Code
16921 \begin_layout Plain Layout
16923 \change_inserted 155139281 1354130923
16931 ), never a global one (such as
16932 \begin_inset Flex Code
16935 \begin_layout Plain Layout
16937 \change_inserted 155139281 1354130923
16950 \begin_layout Description
16951 \begin_inset Flex Code
16954 \begin_layout Plain Layout
16961 \begin_inset Flex Code
16964 \begin_layout Plain Layout
16973 \begin_inset space \thinspace{}
16977 \begin_inset Flex Code
16980 \begin_layout Plain Layout
16987 \begin_inset Quotes eld
16991 \begin_inset Quotes erd
16994 language, leading to Left-to-Right (Latin) output, e.
16995 \begin_inset space \thinspace{}
16999 \begin_inset space \space{}
17002 in TeX code or URL.
17006 \begin_layout Description
17007 \begin_inset Flex Code
17010 \begin_layout Plain Layout
17017 \begin_inset Flex Code
17020 \begin_layout Plain Layout
17029 \begin_inset space \thinspace{}
17033 \begin_inset Flex Code
17036 \begin_layout Plain Layout
17042 ] Indicates whether the
17043 \begin_inset Flex Code
17046 \begin_layout Plain Layout
17052 should be used or, instead, the user can change the paragraph style used
17057 \begin_layout Description
17058 \begin_inset Flex Code
17061 \begin_layout Plain Layout
17068 \begin_inset Flex Code
17071 \begin_layout Plain Layout
17080 \begin_inset space \thinspace{}
17084 \begin_inset Flex Code
17087 \begin_layout Plain Layout
17093 ] As with paragraph styles, see sec.
17094 \begin_inset space ~
17098 \begin_inset CommandInset ref
17100 reference "sub:Paragraph-Styles"
17107 \begin_layout Description
17108 \begin_inset Flex Code
17111 \begin_layout Plain Layout
17117 These tags control the XHTML output.
17119 \begin_inset space ~
17123 \begin_inset CommandInset ref
17125 reference "sec:Tags-for-XHTML"
17132 \begin_layout Description
17133 \begin_inset Flex Code
17136 \begin_layout Plain Layout
17143 \begin_inset Flex Code
17146 \begin_layout Plain Layout
17155 \begin_inset space \thinspace{}
17159 \begin_inset Flex Code
17162 \begin_layout Plain Layout
17168 ] Whether to include the contents of this inset in the strings generated
17169 for the `Outline' pane.
17170 One would not, for example, want the content of a footnote in a section
17171 header to be included in the TOC displayed in the outline, but one would
17172 normally want the content of a character style displayed.
17173 Default is false: not to include.
17176 \begin_layout Description
17177 \begin_inset Flex Code
17180 \begin_layout Plain Layout
17189 \begin_inset Flex Code
17192 \begin_layout Plain Layout
17201 \begin_inset space \thinspace{}
17205 \begin_inset Flex Code
17208 \begin_layout Plain Layout
17214 ] As with paragraph styles, see sec.
17215 \begin_inset space ~
17219 \begin_inset CommandInset ref
17221 reference "sub:Paragraph-Styles"
17228 \begin_layout Description
17229 \begin_inset Flex Code
17232 \begin_layout Plain Layout
17238 The font used for the label.
17240 \begin_inset space ~
17244 \begin_inset CommandInset ref
17246 reference "sub:Font-description"
17251 Note that this definition can never appear before
17252 \begin_inset Flex Code
17255 \begin_layout Plain Layout
17261 , lest it be ineffective.
17264 \begin_layout Description
17265 \begin_inset Flex Code
17268 \begin_layout Plain Layout
17275 \begin_inset Flex Code
17278 \begin_layout Plain Layout
17285 \begin_inset Quotes erd
17289 \begin_inset Quotes erd
17292 ] What will be displayed on the button or elsewhere as the inset label.
17294 \begin_inset Flex Code
17297 \begin_layout Plain Layout
17304 \begin_inset Flex Code
17307 \begin_layout Plain Layout
17313 ) modify this label on the fly.
17316 \begin_layout Description
17318 \change_inserted -195340706 1333913893
17319 \begin_inset Flex Code
17322 \begin_layout Plain Layout
17328 Language dependent preamble.
17330 \begin_inset space ~
17334 \begin_inset CommandInset ref
17336 reference "sub:I18n"
17343 \begin_layout Description
17344 \begin_inset Flex Code
17347 \begin_layout Plain Layout
17354 \begin_inset Flex Code
17357 \begin_layout Plain Layout
17363 ] The name of the corresponding LaTeX stuff.
17364 Either the environment or command name.
17367 \begin_layout Description
17368 \begin_inset Flex Code
17371 \begin_layout Plain Layout
17378 \begin_inset Flex Code
17381 \begin_layout Plain Layout
17387 ] The optional parameter for the corresponding
17388 \begin_inset Flex Code
17391 \begin_layout Plain Layout
17397 stuff, including possible bracket pairs like
17398 \begin_inset Flex Code
17401 \begin_layout Plain Layout
17409 \change_inserted -712698321 1355144715
17410 This will be output as is after all LaTeX
17411 \begin_inset Flex Code
17414 \begin_layout Plain Layout
17416 \change_inserted -712698321 1355144713
17425 This parameter cannot be changed from within LyX
17426 \change_inserted -712698321 1355144775
17428 \begin_inset Flex Code
17431 \begin_layout Plain Layout
17433 \change_inserted -712698321 1355144747
17439 for customizable parameters)
17444 \begin_layout Description
17445 \begin_inset Flex Code
17448 \begin_layout Plain Layout
17455 \begin_inset Flex Code
17458 \begin_layout Plain Layout
17460 \change_deleted -712698321 1353867544
17467 Command, Environment,
17468 \change_inserted -712698321 1353867573
17470 \change_deleted -712698321 1353867557
17479 \begin_inset Flex Code
17482 \begin_layout Plain Layout
17484 \change_deleted -712698321 1353867564
17488 \change_deleted -712698321 1353867569
17496 ] How the style should be translated into LaTeX.
17500 \begin_layout Plain Layout
17501 \begin_inset Flex Code
17504 \begin_layout Plain Layout
17510 is perhaps a bit misleading, since these rules apply to SGML classes, too.
17511 Visit the SGML class files for specific examples.
17520 \begin_layout Description
17521 \begin_inset Flex Code
17524 \begin_layout Plain Layout
17526 \change_deleted -712698321 1353867582
17528 \change_inserted -712698321 1353867583
17536 means nothing special.
17540 \begin_layout Description
17541 \begin_inset Flex Code
17544 \begin_layout Plain Layout
17551 \begin_inset Flex Code
17554 \begin_layout Plain Layout
17561 {\SpecialChar \ldots{}
17570 \begin_layout Description
17571 \begin_inset Flex Code
17574 \begin_layout Plain Layout
17581 \begin_inset Flex Code
17584 \begin_layout Plain Layout
17591 }\SpecialChar \ldots{}
17607 \begin_layout Description
17609 \change_deleted -712698321 1353867600
17610 \begin_inset Flex Code
17613 \begin_layout Plain Layout
17620 \begin_inset Flex Code
17623 \begin_layout Plain Layout
17630 \begin_inset Flex Code
17633 \begin_layout Plain Layout
17641 is generated for each paragraph of this environment.
17645 \begin_layout Description
17647 \change_deleted -712698321 1353867600
17648 \begin_inset Flex Code
17651 \begin_layout Plain Layout
17658 \begin_inset Flex Code
17661 \begin_layout Plain Layout
17668 \begin_inset Flex Code
17671 \begin_layout Plain Layout
17677 is passed as an argument to the environment.
17679 \begin_inset Flex Code
17682 \begin_layout Plain Layout
17688 can be defined in the
17689 \begin_inset Flex MenuItem
17692 \begin_layout Plain Layout
17697 \SpecialChar \menuseparator
17703 \begin_inset space ~
17717 \begin_layout Standard
17718 Putting the last few things together, the LaTeX output will be either:
17721 \begin_layout LyX-Code
17725 \change_deleted 2090807402 1356919073
17727 \change_inserted 2090807402 1356919073
17731 \change_deleted 2090807402 1356919073
17733 \change_inserted 2090807402 1356919002
17736 ]{\SpecialChar \ldots{}
17740 \begin_layout Standard
17744 \begin_layout LyX-Code
17748 \change_deleted 2090807402 1356919013
17750 \change_inserted 2090807402 1356919014
17754 \change_deleted 2090807402 1356919013
17756 \change_inserted 2090807402 1356919008
17759 ] \SpecialChar \ldots{}
17763 \change_deleted 2090807402 1356919016
17765 \change_inserted 2090807402 1356919016
17771 \begin_layout Standard
17772 depending upon the LaTeX type.
17776 \begin_layout Description
17778 \change_inserted -712698321 1354263128
17779 \begin_inset Flex Code
17782 \begin_layout Plain Layout
17784 \change_inserted -712698321 1353866742
17793 \begin_inset Flex Code
17796 \begin_layout Plain Layout
17798 \change_inserted -712698321 1353866752
17804 ] A string that is put at the beginning of the layout content.
17805 A line break in the output can be indicated by
17806 \begin_inset Flex Code
17809 \begin_layout Plain Layout
17811 \change_inserted -712698321 1354263128
17822 \begin_layout Description
17823 \begin_inset Flex Code
17826 \begin_layout Plain Layout
17833 \begin_inset Flex Code
17836 \begin_layout Plain Layout
17843 \begin_inset Flex Code
17846 \begin_layout Plain Layout
17853 \begin_inset Flex Code
17856 \begin_layout Plain Layout
17863 \begin_inset Flex Code
17866 \begin_layout Plain Layout
17872 (indicating a dummy definition ending definitions of charstyles, etc).
17873 This entry is required in and is only meaningful for Flex insets.
17874 Among other things, it determines on which menu this inset will appear.
17876 \begin_inset Flex Code
17879 \begin_layout Plain Layout
17886 \begin_inset Flex Code
17889 \begin_layout Plain Layout
17895 will automatically set
17896 \begin_inset Flex Code
17899 \begin_layout Plain Layout
17907 \begin_inset Flex Code
17910 \begin_layout Plain Layout
17916 can be set to true for
17917 \begin_inset Flex Code
17920 \begin_layout Plain Layout
17926 insets by setting it
17931 \begin_inset Flex Code
17934 \begin_layout Plain Layout
17943 \begin_layout Description
17944 \begin_inset Flex Code
17947 \begin_layout Plain Layout
17954 \begin_inset Flex Code
17957 \begin_layout Plain Layout
17966 \begin_inset space \thinspace{}
17970 \begin_inset Flex Code
17973 \begin_layout Plain Layout
17979 ] Whether multiple paragraphs are permitted in this inset.
17981 \begin_inset Flex Code
17984 \begin_layout Plain Layout
17990 to the same value and
17991 \begin_inset Flex Code
17994 \begin_layout Plain Layout
18000 to the opposite value.
18001 These can be reset to other values, if they are used
18006 \begin_inset Flex Code
18009 \begin_layout Plain Layout
18019 \begin_layout Description
18020 \begin_inset Flex Code
18023 \begin_layout Plain Layout
18030 \begin_inset Flex Code
18033 \begin_layout Plain Layout
18042 \begin_inset space \thinspace{}
18046 \begin_inset Flex Code
18049 \begin_layout Plain Layout
18055 ] Whether fragile commands in this inset should be
18056 \begin_inset Flex Code
18059 \begin_layout Plain Layout
18072 whether the command should itself be protected.) Default is false.
18075 \begin_layout Description
18076 \begin_inset Flex Code
18079 \begin_layout Plain Layout
18086 \begin_inset Flex Code
18089 \begin_layout Plain Layout
18098 \begin_inset space \thinspace{}
18102 \begin_inset Flex Code
18105 \begin_layout Plain Layout
18111 ] As with paragraph styles, see sec.
18112 \begin_inset space ~
18116 \begin_inset CommandInset ref
18118 reference "sub:Paragraph-Styles"
18126 \begin_layout Description
18127 \begin_inset Flex Code
18130 \begin_layout Plain Layout
18137 \begin_inset Flex Code
18140 \begin_layout Plain Layout
18149 \begin_inset space \thinspace{}
18153 \begin_inset Flex Code
18156 \begin_layout Plain Layout
18162 ] As with paragraph styles, see sec.
18163 \begin_inset space ~
18167 \begin_inset CommandInset ref
18169 reference "sub:Paragraph-Styles"
18177 \begin_layout Description
18178 \begin_inset Flex Code
18181 \begin_layout Plain Layout
18187 As with paragraph styles, see sec.
18188 \begin_inset space ~
18192 \begin_inset CommandInset ref
18194 reference "sub:Paragraph-Styles"
18201 \begin_layout Description
18202 \begin_inset Flex Code
18205 \begin_layout Plain Layout
18212 \begin_inset Flex Code
18215 \begin_layout Plain Layout
18221 ] The prefix to use when creating labels referring to insets of this type.
18222 This allows the use of formatted references.
18225 \begin_layout Description
18226 \begin_inset Flex Code
18229 \begin_layout Plain Layout
18236 \begin_inset Flex Code
18239 \begin_layout Plain Layout
18245 ] As with paragraph styles, see sec.
18246 \begin_inset space ~
18250 \begin_inset CommandInset ref
18252 reference "sub:Paragraph-Styles"
18257 \change_inserted -712698321 1354439699
18261 \begin_layout Description
18263 \change_inserted -712698321 1354439705
18264 \begin_inset Flex Code
18267 \begin_layout Plain Layout
18269 \change_inserted -712698321 1354439699
18276 \begin_inset Flex Code
18279 \begin_layout Plain Layout
18281 \change_inserted -712698321 1354439699
18290 \begin_inset Flex Code
18293 \begin_layout Plain Layout
18295 \change_inserted -712698321 1354439699
18301 ] Resets the LaTeX arguments of this layout (as defined via the
18302 \begin_inset Flex Code
18305 \begin_layout Plain Layout
18307 \change_inserted -712698321 1354439699
18314 This is useful if you have copied a style via
18315 \begin_inset Flex Code
18318 \begin_layout Plain Layout
18320 \change_inserted -712698321 1354439699
18326 , but you do not want to inherit its (required and optional) arguments.
18328 \change_deleted -712698321 1354439698
18334 \begin_layout Description
18335 \begin_inset Flex Code
18338 \begin_layout Plain Layout
18345 \begin_inset Flex Code
18348 \begin_layout Plain Layout
18355 \begin_inset space \thinspace{}
18359 \begin_inset Flex Code
18362 \begin_layout Plain Layout
18370 ] Whether this inset should use the font of its surrounding environment
18372 Default is true: uses its own.
18375 \begin_layout Description
18377 \change_inserted -712698321 1354263134
18378 \begin_inset Flex Code
18381 \begin_layout Plain Layout
18383 \change_inserted -712698321 1353866810
18390 \begin_inset Flex Code
18393 \begin_layout Plain Layout
18395 \change_inserted -712698321 1353866806
18401 ] A string that is put at the end of the layout content.
18402 A line break in the output can be indicated by
18403 \begin_inset Flex Code
18406 \begin_layout Plain Layout
18408 \change_inserted -712698321 1354263134
18419 \begin_layout Description
18420 \begin_inset Flex Code
18423 \begin_layout Plain Layout
18430 \begin_inset Flex Code
18433 \begin_layout Plain Layout
18440 \begin_inset space \thinspace{}
18444 \begin_inset Flex Code
18447 \begin_layout Plain Layout
18455 ] Allow spell-checking the contents of this inset.
18459 \begin_layout Subsection
18461 \begin_inset CommandInset label
18463 name "sub:Counters"
18470 \begin_layout Standard
18471 It is necessary to define the counters (
18472 \begin_inset Flex MenuItem
18475 \begin_layout Plain Layout
18482 \begin_inset Flex MenuItem
18485 \begin_layout Plain Layout
18491 , \SpecialChar \ldots{}
18492 ) in the text class itself.
18493 The standard counters are defined in the file
18494 \begin_inset Flex Code
18497 \begin_layout Plain Layout
18503 , so you may have to do no more than add
18506 \begin_layout LyX-Code
18507 Input stdcounters.inc
18510 \begin_layout Standard
18511 to your layout file to get them to work.
18512 But if you want to define custom counters, then you can do so.
18513 The counter declaration must begin with:
18516 \begin_layout LyX-Code
18517 Counter CounterName
18520 \begin_layout Standard
18522 \begin_inset Flex Code
18525 \begin_layout Plain Layout
18531 ' is replaced by the name of the counter.
18532 And it must end with
18533 \begin_inset Quotes eld
18537 \begin_inset Flex Code
18540 \begin_layout Plain Layout
18547 \begin_inset Quotes erd
18551 The following parameters can also be used:
18554 \begin_layout Description
18555 \begin_inset Flex Code
18558 \begin_layout Plain Layout
18565 \begin_inset Flex Code
18568 \begin_layout Plain Layout
18575 \begin_inset Quotes erd
18579 \begin_inset Quotes erd
18582 ] When defined, this string defines how the counter is displayed.
18583 Setting this value sets
18584 \begin_inset Flex Code
18587 \begin_layout Plain Layout
18588 LabelStringAppendix
18594 The following special constructs can be used in the string:
18598 \begin_layout Itemize
18599 \begin_inset Flex Code
18602 \begin_layout Plain Layout
18610 will be replaced by the expansion of the
18611 \begin_inset Flex Code
18614 \begin_layout Plain Layout
18621 \begin_inset Flex Code
18624 \begin_layout Plain Layout
18625 LabelStringAppendix
18631 \begin_inset Flex Code
18634 \begin_layout Plain Layout
18644 \begin_layout Itemize
18645 counter values can be expressed using LaTeX-like macros
18646 \begin_inset Newline newline
18650 \begin_inset Flex Code
18653 \begin_layout Plain Layout
18670 \begin_inset Flex Code
18673 \begin_layout Plain Layout
18685 \begin_layout Plain Layout
18695 Actually, the situation is a bit more complicated: any
18714 other than those described below will produce arabic numerals.
18715 It would not be surprising to see this change in the future.
18721 \begin_inset Flex Code
18724 \begin_layout Plain Layout
18730 : 1, 2, 3,\SpecialChar \ldots{}
18732 \begin_inset Flex Code
18735 \begin_layout Plain Layout
18741 for lower-case letters: a, b, c, \SpecialChar \ldots{}
18743 \begin_inset Flex Code
18746 \begin_layout Plain Layout
18752 for upper-case letters: A, B, C, \SpecialChar \ldots{}
18754 \begin_inset Flex Code
18757 \begin_layout Plain Layout
18763 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
18765 \begin_inset Flex Code
18768 \begin_layout Plain Layout
18774 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
18776 \begin_inset Flex Code
18779 \begin_layout Plain Layout
18785 for hebrew numerals.
18789 \begin_layout Standard
18790 If LabelString is not defined, a default value is constructed as follows:
18791 if the counter has a master counter
18792 \begin_inset Flex Code
18795 \begin_layout Plain Layout
18802 \begin_inset Flex Code
18805 \begin_layout Plain Layout
18812 \begin_inset Newline newline
18816 \begin_inset Flex Code
18819 \begin_layout Plain Layout
18829 is used; otherwise the string
18830 \begin_inset Flex Code
18833 \begin_layout Plain Layout
18844 \begin_layout Description
18845 \begin_inset Flex Code
18848 \begin_layout Plain Layout
18849 LabelStringAppendix
18855 \begin_inset Flex Code
18858 \begin_layout Plain Layout
18865 \begin_inset Quotes erd
18869 \begin_inset Quotes erd
18873 \begin_inset Flex Code
18876 \begin_layout Plain Layout
18882 , but for use in the Appendix.
18885 \begin_layout Description
18886 \begin_inset Flex Code
18889 \begin_layout Plain Layout
18896 \begin_inset Flex Code
18899 \begin_layout Plain Layout
18906 \begin_inset Quotes erd
18910 \begin_inset Quotes erd
18913 ] A format for use with formatted references to this counter.
18914 For example, one might want to have references to section numbers appear
18916 \begin_inset Quotes eld
18920 \begin_inset Quotes erd
18924 The string should contain
18925 \begin_inset Quotes eld
18929 \begin_inset Quotes erd
18933 This will be replaced by the counter number itself.
18934 So, for sections, it would be: Section ##.
18937 \begin_layout Description
18938 \begin_inset Flex Code
18941 \begin_layout Plain Layout
18948 \begin_inset Flex Code
18951 \begin_layout Plain Layout
18958 \begin_inset Quotes erd
18962 \begin_inset Quotes erd
18965 ] If this is set to the name of another counter, the present counter will
18966 be reset every time the other one is increased.
18968 \begin_inset Flex Code
18971 \begin_layout Plain Layout
18978 \begin_inset Flex Code
18981 \begin_layout Plain Layout
18990 \begin_layout Subsection
18992 \begin_inset CommandInset label
18994 name "sub:Font-description"
19001 \begin_layout Standard
19002 A font description looks like this:
19005 \begin_layout LyX-Code
19015 \begin_layout LyX-Code
19019 \begin_layout LyX-Code
19023 \begin_layout Standard
19024 The following commands are available:
19027 \begin_layout Description
19028 \begin_inset Flex Code
19031 \begin_layout Plain Layout
19038 \begin_inset Flex Code
19041 \begin_layout Plain Layout
19050 \begin_inset Flex Code
19053 \begin_layout Plain Layout
19060 \begin_inset Flex Code
19063 \begin_layout Plain Layout
19070 \begin_inset Flex Code
19073 \begin_layout Plain Layout
19080 \begin_inset Flex Code
19083 \begin_layout Plain Layout
19090 \begin_inset Flex Code
19093 \begin_layout Plain Layout
19100 \begin_inset Flex Code
19103 \begin_layout Plain Layout
19110 \begin_inset Flex Code
19113 \begin_layout Plain Layout
19120 \begin_inset Flex Code
19123 \begin_layout Plain Layout
19132 \begin_layout Description
19133 \begin_inset Flex Code
19136 \begin_layout Plain Layout
19143 \begin_inset Flex Code
19146 \begin_layout Plain Layout
19155 \begin_inset Flex Code
19158 \begin_layout Plain Layout
19165 \begin_inset Flex Code
19168 \begin_layout Plain Layout
19177 \begin_layout Description
19178 \begin_inset Flex Code
19181 \begin_layout Plain Layout
19188 \begin_inset Flex Code
19191 \begin_layout Plain Layout
19197 ] Valid arguments are:
19198 \begin_inset Flex Code
19201 \begin_layout Plain Layout
19208 \begin_inset Flex Code
19211 \begin_layout Plain Layout
19218 \begin_inset Flex Code
19221 \begin_layout Plain Layout
19228 \begin_inset Flex Code
19231 \begin_layout Plain Layout
19238 \begin_inset Flex Code
19241 \begin_layout Plain Layout
19248 \begin_inset Flex Code
19251 \begin_layout Plain Layout
19258 \begin_inset Flex Code
19261 \begin_layout Plain Layout
19268 \begin_inset Flex Code
19271 \begin_layout Plain Layout
19278 \begin_inset Flex Code
19281 \begin_layout Plain Layout
19288 \begin_inset Flex Code
19291 \begin_layout Plain Layout
19298 \begin_inset Flex Code
19301 \begin_layout Plain Layout
19308 \begin_inset Flex Code
19311 \begin_layout Plain Layout
19318 Each of these turns on or off the corresponding attribute.
19320 \begin_inset Flex Code
19323 \begin_layout Plain Layout
19329 turns on emphasis, and
19330 \begin_inset Flex Code
19333 \begin_layout Plain Layout
19341 \begin_inset Newline newline
19344 If the latter seems puzzling, remember that the font settings for the present
19345 context are generally inherited from the surrounding context.
19347 \begin_inset Flex Code
19350 \begin_layout Plain Layout
19356 would turn off the emphasis that was anyway in effect, say, in a theorem
19360 \begin_layout Description
19361 \begin_inset Flex Code
19364 \begin_layout Plain Layout
19371 \begin_inset Flex Code
19374 \begin_layout Plain Layout
19383 \begin_inset Flex Code
19386 \begin_layout Plain Layout
19395 \begin_layout Description
19396 \begin_inset Flex Code
19399 \begin_layout Plain Layout
19406 \begin_inset Flex Code
19409 \begin_layout Plain Layout
19418 \begin_inset Flex Code
19421 \begin_layout Plain Layout
19428 \begin_inset Flex Code
19431 \begin_layout Plain Layout
19438 \begin_inset Flex Code
19441 \begin_layout Plain Layout
19450 \begin_layout Description
19451 \begin_inset Flex Code
19454 \begin_layout Plain Layout
19461 \begin_inset Flex Code
19464 \begin_layout Plain Layout
19471 \begin_inset Flex Code
19474 \begin_layout Plain Layout
19481 \begin_inset Flex Code
19484 \begin_layout Plain Layout
19493 \begin_inset Flex Code
19496 \begin_layout Plain Layout
19503 \begin_inset Flex Code
19506 \begin_layout Plain Layout
19513 \begin_inset Flex Code
19516 \begin_layout Plain Layout
19523 \begin_inset Flex Code
19526 \begin_layout Plain Layout
19533 \begin_inset Flex Code
19536 \begin_layout Plain Layout
19545 \begin_layout Subsection
19546 \begin_inset CommandInset label
19548 name "sub:Citation-format-description"
19552 Citation format description
19555 \begin_layout Standard
19557 \begin_inset Flex Code
19560 \begin_layout Plain Layout
19566 blocks are used to describe how bibliographic information should be displayed,
19567 both within LyX itself (in the citation dialog and in tooltips, for example)
19568 and in XHTML output.
19569 Such a block might look like this:
19572 \begin_layout LyX-Code
19576 \begin_layout LyX-Code
19580 \begin_layout LyX-Code
19584 \begin_layout LyX-Code
19588 \begin_layout Standard
19589 The individual lines define how the bibliographic information associated
19590 with an article or book, respectively, is to be displayed, and such a definitio
19591 n can be given for any `entry type' that might be present in a BibTeX file.
19592 LyX defines a default format in the source code that will be used if no
19593 specific definition has been given.
19594 LyX predefines several formats in the file
19595 \begin_inset Flex Code
19598 \begin_layout Plain Layout
19604 , which is included in most of LyX's document classes.
19607 \begin_layout Standard
19608 The definitions use a simple language that allows BibTeX keys to be replaced
19610 Keys should be enclosed in
19611 \begin_inset Flex Code
19614 \begin_layout Plain Layout
19621 \begin_inset Flex Code
19624 \begin_layout Plain Layout
19631 So a simple definition might look like this:
19634 \begin_layout LyX-Code
19636 \begin_inset Quotes eld
19640 \begin_inset Quotes erd
19646 \begin_layout Standard
19647 This would print the author, followed by a comma, followed by the title,
19648 in quotes, followed by a period.
19651 \begin_layout Standard
19652 Of course, sometimes you may want to print a key only if it exists.
19653 This can be done by using a conditional construction, such as:
19654 \begin_inset Flex Code
19657 \begin_layout Plain Layout
19659 \begin_inset space ~
19669 \begin_inset Flex Code
19672 \begin_layout Plain Layout
19678 key exists, then print
19679 \begin_inset Quotes eld
19683 \begin_inset space ~
19687 \begin_inset Quotes erd
19690 followed by the volume key.
19691 It is also possible to have an else clause in the conditional, such as:
19692 \begin_inset Newline newline
19696 \begin_inset Flex Code
19699 \begin_layout Plain Layout
19700 {%author%[[%author%]][[%editor%, ed.]]}
19706 \begin_inset Newline newline
19710 \begin_inset Flex Code
19713 \begin_layout Plain Layout
19719 key is printed if it exists; otherwise, the editor key is printed, followed
19721 \begin_inset Quotes eld
19725 \begin_inset space ~
19729 \begin_inset Quotes erd
19732 Note that the key is again enclosed in
19733 \begin_inset Flex Code
19736 \begin_layout Plain Layout
19742 signs; the entire conditional is enclosed in braces; and the if and else
19743 clauses are enclosed in double brackets,
19744 \begin_inset Quotes eld
19748 \begin_inset Flex Code
19751 \begin_layout Plain Layout
19758 \begin_inset Quotes eld
19762 \begin_inset Quotes eld
19766 \begin_inset Flex Code
19769 \begin_layout Plain Layout
19776 \begin_inset Quotes erd
19780 There must be no space between any of these.
19783 \begin_layout Standard
19784 There is one other piece of syntax available in definitions, which looks
19786 \begin_inset Flex Code
19789 \begin_layout Plain Layout
19796 This defines a piece of formatting information that is to be used when
19798 \begin_inset Quotes eld
19802 \begin_inset Quotes erd
19806 Obviously, we do not want to output HTML tags when writing plain text,
19807 so they should be wrapped in
19808 \begin_inset Quotes eld
19812 \begin_inset Quotes erd
19816 \begin_inset Quotes eld
19820 \begin_inset Quotes erd
19826 \begin_layout Standard
19827 Two special sorts of definitions are also possible in a
19828 \begin_inset Flex Code
19831 \begin_layout Plain Layout
19838 An example of the first would be:
19841 \begin_layout LyX-Code
19843 \begin_inset Quotes eld
19847 \begin_inset Quotes erd
19853 \begin_layout Standard
19854 This is an abbreviation, or macro, and it can be used by treating it as
19856 \begin_inset Flex Code
19859 \begin_layout Plain Layout
19867 \begin_inset Flex Code
19870 \begin_layout Plain Layout
19876 exactly as it would treat its definition.
19877 So, let us issue the obvious
19885 \begin_layout LyX-Code
19889 \begin_layout Standard
19890 or anything like it.
19891 LyX shouldn't go into an infinite loop, but it may go into a long one before
19895 \begin_layout Standard
19896 The second sort of special definition might look like this:
19899 \begin_layout LyX-Code
19903 \begin_layout Standard
19904 This defines a translatable piece of text, which allows relevant parts of
19905 the bibliography to be translated.
19906 It can be included in a definition by treating it as a key:
19907 \begin_inset Flex Code
19910 \begin_layout Plain Layout
19917 Several of these are predefined in
19918 \begin_inset Flex Code
19921 \begin_layout Plain Layout
19928 Note that these are not macros, in the sense just defined.
19929 They will not be expanded.
19932 \begin_layout Standard
19933 So here then is an example that use all these features:
19934 \begin_inset VSpace defskip
19940 \begin_layout Standard
19944 !authoredit {%author%[[%author%, ]][[{%editor%[[%editor%, %_edtext%, ]]}]]}
19947 \begin_layout Standard
19948 \begin_inset VSpace defskip
19951 This defines a macro that prints the author, followed by a comma, if the
19953 \begin_inset Flex Code
19956 \begin_layout Plain Layout
19962 key is defined, or else prints the name of the editor, followed by the
19964 \begin_inset Flex Code
19967 \begin_layout Plain Layout
19973 or its translation (it is by default
19974 \begin_inset Quotes eld
19978 \begin_inset Quotes erd
19982 \begin_inset Flex Code
19985 \begin_layout Plain Layout
19992 Note that this is in fact defined in
19993 \begin_inset Flex Code
19996 \begin_layout Plain Layout
20002 , so you can use it in your own definitions, or re-definitions, if you load
20006 \begin_layout Section
20007 \begin_inset CommandInset label
20009 name "sec:Tags-for-XHTML"
20013 Tags for XHTML output
20016 \begin_layout Standard
20017 As with LaTeX or DocBook, the format of LyX's XHTML output is also controlled
20018 by layout information.
20019 In general, LyX provides sensible defaults and, as mentioned earlier, it
20020 will even construct default CSS style rules from the other layout tags.
20021 For example, LyX will attempt to use the information provided in the
20022 \begin_inset Flex Code
20025 \begin_layout Plain Layout
20031 declaration for the Chapter style to write CSS that will appropriately
20032 format chapter headings.
20035 \begin_layout Standard
20036 In many cases, then, you may not have to do anything at all to get acceptable
20037 XHTML output for your own environments, custom insets, and so forth.
20038 But in some cases you will, and so LyX provides a number of layout tags
20039 that can be used to customize the XHTML and CSS that are generated.
20042 \begin_layout Standard
20043 Note that there are two tags,
20044 \begin_inset Flex Code
20047 \begin_layout Plain Layout
20054 \begin_inset Flex Code
20057 \begin_layout Plain Layout
20063 that may appear outside style and inset declarations.
20065 \begin_inset CommandInset ref
20067 reference "sub:General-text-class"
20071 for details on these.
20074 \begin_layout Subsection
20075 \begin_inset CommandInset label
20077 name "sub:Paragraph-Style-XHTML"
20084 \begin_layout Standard
20085 The sort of XHTML LyX outputs for a paragraph depends upon whether we are
20086 dealing with a normal paragraph, a command, or an environment, where this
20087 is itself determined by the contents of the corresponding
20088 \begin_inset Flex Code
20091 \begin_layout Plain Layout
20101 \begin_layout Standard
20102 For a command or normal paragraph, the output XHTML has the following form:
20105 \begin_layout LyX-Code
20107 \begin_inset Quotes erd
20111 \begin_inset Quotes erd
20117 \begin_layout LyX-Code
20119 \begin_inset Quotes erd
20123 \begin_inset Quotes erd
20129 \begin_layout LyX-Code
20130 Contents of the paragraph.
20133 \begin_layout LyX-Code
20137 \begin_layout Standard
20138 The label tags are of course omitted if the paragraph does not have a label.
20141 \begin_layout Standard
20142 For an environment that is not some sort of list, the XHTML takes this form:
20145 \begin_layout LyX-Code
20147 \begin_inset Quotes erd
20151 \begin_inset Quotes erd
20157 \begin_layout LyX-Code
20159 \begin_inset Quotes erd
20163 \begin_inset Quotes erd
20167 \begin_inset Quotes erd
20171 \begin_inset Quotes erd
20174 >Environment Label</labeltag>First paragraph.</itemtag>
20177 \begin_layout LyX-Code
20178 <itemtag>Second paragraph.</itemtag>
20181 \begin_layout LyX-Code
20185 \begin_layout Standard
20186 Note that the label is output only for the first paragraph, as it should
20187 be for a theorem, for example.
20191 \begin_layout Standard
20192 For a list, we have one of these forms:
20195 \begin_layout LyX-Code
20197 \begin_inset Quotes erd
20201 \begin_inset Quotes erd
20207 \begin_layout LyX-Code
20209 \begin_inset Quotes erd
20213 \begin_inset Quotes erd
20217 \begin_inset Quotes erd
20221 \begin_inset Quotes erd
20224 >List Label</labeltag>First item.</itemtag>
20227 \begin_layout LyX-Code
20229 \begin_inset Quotes erd
20233 \begin_inset Quotes erd
20237 \begin_inset Quotes erd
20241 \begin_inset Quotes erd
20244 >List Label</labeltag>Second item.</itemtag>
20247 \begin_layout LyX-Code
20251 \begin_layout LyX-Code
20255 \begin_layout LyX-Code
20257 \begin_inset Quotes erd
20261 \begin_inset Quotes erd
20267 \begin_layout LyX-Code
20269 \begin_inset Quotes erd
20273 \begin_inset Quotes erd
20276 >List Label</labeltag><itemtag attr=
20277 \begin_inset Quotes erd
20281 \begin_inset Quotes erd
20284 >First item.</itemtag>
20287 \begin_layout LyX-Code
20289 \begin_inset Quotes erd
20293 \begin_inset Quotes erd
20296 >List Label</labeltag><itemtag attr=
20297 \begin_inset Quotes erd
20301 \begin_inset Quotes erd
20304 >Second item.</itemtag>
20307 \begin_layout LyX-Code
20311 \begin_layout Standard
20312 Note the different orders of
20313 \begin_inset Flex Code
20316 \begin_layout Plain Layout
20323 \begin_inset Flex Code
20326 \begin_layout Plain Layout
20333 Which order we get depends upon the setting of
20334 \begin_inset Flex Code
20337 \begin_layout Plain Layout
20344 \begin_inset Flex Code
20347 \begin_layout Plain Layout
20353 is false (the default), you get the first of these, with the label within
20354 the item; if true, you get the second, with the label outside the item.
20357 \begin_layout Standard
20358 The specific tags and attributes output for each paragraph type can be controlle
20359 d by means of the layout tags we are about to describe.
20360 As mentioned earlier, however, LyX uses sensible defaults for many of these,
20361 so you often may not need to do very much to get good XHTML output.
20362 Think of the available tags as there so you can tweak things to your liking.
20365 \begin_layout Description
20366 \begin_inset Flex Code
20369 \begin_layout Plain Layout
20376 \begin_inset Flex Code
20379 \begin_layout Plain Layout
20385 ] Specifies attribute information to be output with the main tag.
20387 \begin_inset Quotes eld
20391 \begin_inset Flex Code
20394 \begin_layout Plain Layout
20401 \begin_inset Quotes erd
20405 By default, LyX will output
20406 \begin_inset Quotes eld
20410 \begin_inset Flex Code
20413 \begin_layout Plain Layout
20420 \begin_inset Quotes erd
20424 \begin_inset Flex Code
20427 \begin_layout Plain Layout
20433 is the LyX name of the layout, made lowercase, for example: chapter.
20438 contain any style information.
20440 \begin_inset Flex Code
20443 \begin_layout Plain Layout
20452 \begin_layout Description
20453 \begin_inset Flex Code
20456 \begin_layout Plain Layout
20463 \begin_inset Flex Code
20466 \begin_layout Plain Layout
20476 ] Whether to output the default CSS information LyX generates for this layout,
20477 even if additional information is explicitly provided via
20478 \begin_inset Flex Code
20481 \begin_layout Plain Layout
20489 \begin_inset Flex Code
20492 \begin_layout Plain Layout
20498 allows you to alter or augment the generated CSS, rather than to override
20501 \begin_inset Flex Code
20504 \begin_layout Plain Layout
20513 \begin_layout Description
20514 \begin_inset Flex Code
20517 \begin_layout Plain Layout
20524 \begin_inset Flex Code
20527 \begin_layout Plain Layout
20533 ] The tag to be used for individual paragraphs of environments, replacing
20535 \begin_inset Flex Code
20538 \begin_layout Plain Layout
20544 in the examples above.
20546 \begin_inset Flex Code
20549 \begin_layout Plain Layout
20558 \begin_layout Description
20559 \begin_inset Flex Code
20562 \begin_layout Plain Layout
20569 \begin_inset Flex Code
20572 \begin_layout Plain Layout
20578 ] Attributes for the item tag.
20580 \begin_inset Quotes eld
20584 \begin_inset Flex Code
20587 \begin_layout Plain Layout
20588 class=`layoutname_item'
20594 \begin_inset Quotes erd
20602 contain any style information.
20604 \begin_inset Flex Code
20607 \begin_layout Plain Layout
20616 \begin_layout Description
20617 \begin_inset Flex Code
20620 \begin_layout Plain Layout
20627 \begin_inset Flex Code
20630 \begin_layout Plain Layout
20636 ] The tag to be used for paragraph and item labels, replacing
20637 \begin_inset Flex Code
20640 \begin_layout Plain Layout
20646 in the examples above.
20648 \begin_inset Flex Code
20651 \begin_layout Plain Layout
20658 \begin_inset Flex Code
20661 \begin_layout Plain Layout
20668 \begin_inset Flex Code
20671 \begin_layout Plain Layout
20678 \begin_inset Flex Code
20681 \begin_layout Plain Layout
20682 Centered_Top_Environment
20687 , in which case it defaults to
20688 \begin_inset Flex Code
20691 \begin_layout Plain Layout
20700 \begin_layout Description
20701 \begin_inset Flex Code
20704 \begin_layout Plain Layout
20711 \begin_inset Flex Code
20714 \begin_layout Plain Layout
20720 ] Attributes for the label tag.
20722 \begin_inset Quotes eld
20726 \begin_inset Flex Code
20729 \begin_layout Plain Layout
20730 class=`layoutname_label'
20736 \begin_inset Quotes erd
20744 contain any style information.
20746 \begin_inset Flex Code
20749 \begin_layout Plain Layout
20758 \begin_layout Description
20759 \begin_inset Flex Code
20762 \begin_layout Plain Layout
20769 \begin_inset Flex Code
20772 \begin_layout Plain Layout
20782 ] Meaningful only for list-like environments, this tag controls whether
20783 the label tag is output before or inside the item tag.
20784 This is used, for example, in the description environment, where we want
20786 \begin_inset Flex Code
20789 \begin_layout Plain Layout
20790 <dt>\SpecialChar \ldots{}
20791 </dt><dd>\SpecialChar \ldots{}
20799 \begin_inset Flex Code
20802 \begin_layout Plain Layout
20808 : The label tag is output inside the item tag.
20811 \begin_layout Description
20812 \begin_inset Flex Code
20815 \begin_layout Plain Layout
20821 Information to be output in the
20822 \begin_inset Flex Code
20825 \begin_layout Plain Layout
20831 section when this style is used.
20832 This might, for example, be used to include a
20833 \begin_inset Flex Code
20836 \begin_layout Plain Layout
20843 \begin_inset Flex Code
20846 \begin_layout Plain Layout
20855 \begin_layout Description
20856 \begin_inset Flex Code
20859 \begin_layout Plain Layout
20865 CSS style information to be included when this style is used.
20866 Note that this will automatically be wrapped in a layout-generated
20867 \begin_inset Flex Code
20870 \begin_layout Plain Layout
20876 block, so only the CSS itself need be included.
20879 \begin_layout Description
20880 \begin_inset Flex Code
20883 \begin_layout Plain Layout
20890 \begin_inset Flex Code
20893 \begin_layout Plain Layout
20899 ] The tag to be used for the main label, replacing
20900 \begin_inset Flex Code
20903 \begin_layout Plain Layout
20909 in the examples above.
20911 \begin_inset Flex Code
20914 \begin_layout Plain Layout
20923 \begin_layout Description
20924 \begin_inset Flex Code
20927 \begin_layout Plain Layout
20934 \begin_inset Flex Code
20937 \begin_layout Plain Layout
20947 ] Marks this style as the one to be used to generate the
20948 \begin_inset Flex Code
20951 \begin_layout Plain Layout
20957 tag for the XHTML file.
20958 By default, it is false.
20960 \begin_inset Flex Code
20963 \begin_layout Plain Layout
20969 file sets it to true for the
20970 \begin_inset Flex Code
20973 \begin_layout Plain Layout
20983 \begin_layout Subsection
20987 \begin_layout Standard
20988 The XHTML output of insets can also be controlled by information in layout
20993 \begin_layout Plain Layout
20994 At present, this is true only for
20995 \begin_inset Quotes eld
20999 \begin_inset Quotes erd
21002 insets (insets you can type into) and is not true for
21003 \begin_inset Quotes eld
21007 \begin_inset Quotes erd
21010 insets (insets that are associated with dialog boxes).
21015 Here, too, LyX tries to provide sensible defaults, and it constructs default
21017 But everything can be customized.
21020 \begin_layout Standard
21021 The XHTML LyX outputs for an inset has the following form:
21024 \begin_layout LyX-Code
21026 \begin_inset Quotes erd
21030 \begin_inset Quotes erd
21036 \begin_layout LyX-Code
21037 <labeltag>Label</labeltag>
21040 \begin_layout LyX-Code
21042 \begin_inset Quotes erd
21046 \begin_inset Quotes erd
21049 >Contents of the inset.</innertag>
21052 \begin_layout LyX-Code
21056 \begin_layout Standard
21057 If the inset permits multiple paragraphs---that is, if
21058 \begin_inset Flex Code
21061 \begin_layout Plain Layout
21067 is true---then the contents of the inset will itself be output as paragraphs
21068 formatted according to the styles used for those paragraphs (standard,
21069 quote, and the like).
21070 The label tag is of course omitted if the paragraph does not have a label
21071 and, at present, is always
21072 \begin_inset Flex Code
21075 \begin_layout Plain Layout
21082 The inner tag is optional and, by default, does not appear.
21085 \begin_layout Standard
21086 The specific tags and attributes output for each inset can be controlled
21087 by means of the following layout tags.
21090 \begin_layout Description
21091 \begin_inset Flex Code
21094 \begin_layout Plain Layout
21101 \begin_inset Flex Code
21104 \begin_layout Plain Layout
21110 ] Specifies attribute information to be output with the main tag.
21112 \begin_inset Quotes eld
21116 \begin_inset Flex Code
21119 \begin_layout Plain Layout
21120 class=`myinset' onclick=`\SpecialChar \ldots{}
21127 \begin_inset Quotes erd
21131 By default, LyX will output
21132 \begin_inset Quotes eld
21136 \begin_inset Flex Code
21139 \begin_layout Plain Layout
21146 \begin_inset Quotes erd
21150 \begin_inset Flex Code
21153 \begin_layout Plain Layout
21159 is the LyX name of the inset, made lowercase and with non-alphanumeric
21160 characters converted to underscores, for example: footnote.
21163 \begin_layout Description
21164 \begin_inset Flex Code
21167 \begin_layout Plain Layout
21174 \begin_inset Flex Code
21177 \begin_layout Plain Layout
21187 ] Whether to output the default CSS information LyX generates for this layout,
21188 even if additional information is explicitly provided via
21189 \begin_inset Flex Code
21192 \begin_layout Plain Layout
21200 \begin_inset Flex Code
21203 \begin_layout Plain Layout
21209 allows you to alter or augment the generated CSS, rather than to override
21214 \begin_layout Description
21215 \begin_inset Flex Code
21218 \begin_layout Plain Layout
21225 \begin_inset Flex Code
21228 \begin_layout Plain Layout
21234 ] Attributes for the inner tag.
21236 \begin_inset Quotes eld
21240 \begin_inset Flex Code
21243 \begin_layout Plain Layout
21244 class=`insetname_inner'
21250 \begin_inset Quotes erd
21256 \begin_layout Description
21257 \begin_inset Flex Code
21260 \begin_layout Plain Layout
21267 \begin_inset Flex Code
21270 \begin_layout Plain Layout
21276 ] The inner tag, replacing
21277 \begin_inset Flex Code
21280 \begin_layout Plain Layout
21286 in the examples above.
21287 By default, there is none.
21290 \begin_layout Description
21291 \begin_inset Flex Code
21294 \begin_layout Plain Layout
21301 \begin_inset Flex Code
21304 \begin_layout Plain Layout
21312 ] Whether this inset represents a standalone block of text (such as a footnote)
21313 or instead represents material that is included in the surrounding text
21314 (such as a branch).
21318 \begin_layout Description
21319 \begin_inset Flex Code
21322 \begin_layout Plain Layout
21329 \begin_inset Flex Code
21332 \begin_layout Plain Layout
21338 ] A label for this inset, possibly including a reference to a counter.
21339 For example, for footnote, it might be:
21340 \begin_inset Flex Code
21343 \begin_layout Plain Layout
21352 This is optional, and there is no default.
21355 \begin_layout Description
21356 \begin_inset Flex Code
21359 \begin_layout Plain Layout
21365 Information to be output in the
21366 \begin_inset Flex Code
21369 \begin_layout Plain Layout
21375 section when this style is used.
21376 This might, for example, be used to include a
21377 \begin_inset Flex Code
21380 \begin_layout Plain Layout
21387 \begin_inset Flex Code
21390 \begin_layout Plain Layout
21399 \begin_layout Description
21400 \begin_inset Flex Code
21403 \begin_layout Plain Layout
21409 CSS style information to be included when this style is used.
21410 Note that this will automatically be wrapped in a layout-generated
21411 \begin_inset Flex Code
21414 \begin_layout Plain Layout
21420 block, so only the CSS itself need be included.
21423 \begin_layout Description
21424 \begin_inset Flex Code
21427 \begin_layout Plain Layout
21434 \begin_inset Flex Code
21437 \begin_layout Plain Layout
21443 ] The tag to be used for the main label, replacing
21444 \begin_inset Flex Code
21447 \begin_layout Plain Layout
21453 in the examples above.
21454 The default depends upon the setting of
21455 \begin_inset Flex Code
21458 \begin_layout Plain Layout
21465 \begin_inset Flex Code
21468 \begin_layout Plain Layout
21474 is true, the default is
21475 \begin_inset Flex Code
21478 \begin_layout Plain Layout
21484 ; if it is false, the default is
21485 \begin_inset Flex Code
21488 \begin_layout Plain Layout
21497 \begin_layout Subsection
21501 \begin_layout Standard
21502 The XHTML output for floats too can be controlled by layout information.
21503 The output has the following form:
21506 \begin_layout LyX-Code
21508 \begin_inset Quotes erd
21512 \begin_inset Quotes erd
21518 \begin_layout LyX-Code
21519 Contents of the float.
21522 \begin_layout LyX-Code
21526 \begin_layout Standard
21527 The caption, if there is one, is a separate inset and will be output as
21529 Its appearance can be controlled via the InsetLayout for caption insets.
21533 \begin_layout Description
21534 \begin_inset Flex Code
21537 \begin_layout Plain Layout
21544 \begin_inset Flex Code
21547 \begin_layout Plain Layout
21553 ] Specifies attribute information to be output with the main tag.
21555 \begin_inset Quotes eld
21559 \begin_inset Flex Code
21562 \begin_layout Plain Layout
21563 class=`myfloat' onclick=`\SpecialChar \ldots{}
21570 \begin_inset Quotes erd
21574 By default, LyX will output
21575 \begin_inset Quotes eld
21579 \begin_inset Flex Code
21582 \begin_layout Plain Layout
21583 class=`float float-floattype'
21589 \begin_inset Quotes erd
21593 \begin_inset Flex Code
21596 \begin_layout Plain Layout
21602 is LyX's name for this type of float, as determined by the float declaration
21604 \begin_inset CommandInset ref
21606 reference "sub:Floats"
21610 ), though made lowercase and with non-alphanumeric characters converted
21611 to underscores, for example: float-table.
21614 \begin_layout Description
21615 \begin_inset Flex Code
21618 \begin_layout Plain Layout
21624 CSS style information to be included when this float is used.
21625 Note that this will automatically be wrapped in a layout-generated
21626 \begin_inset Flex Code
21629 \begin_layout Plain Layout
21635 block, so only the CSS itself need be included.
21638 \begin_layout Description
21639 \begin_inset Flex Code
21642 \begin_layout Plain Layout
21649 \begin_inset Flex Code
21652 \begin_layout Plain Layout
21658 ] The tag to be used for this float, replacing
21659 \begin_inset Quotes eld
21663 \begin_inset Flex Code
21666 \begin_layout Plain Layout
21673 \begin_inset Quotes erd
21676 in the example above.
21678 \begin_inset Flex Code
21681 \begin_layout Plain Layout
21687 and will rarely need changing.
21690 \begin_layout Subsection
21691 Bibliography formatting
21694 \begin_layout Standard
21695 The bibliography can be formatted using
21696 \begin_inset Flex Code
21699 \begin_layout Plain Layout
21707 \begin_inset CommandInset ref
21709 reference "sub:Citation-format-description"
21716 \begin_layout Subsection
21720 \begin_layout Standard
21721 We have several times mentioned that LyX will generate default CSS style
21722 rules for both insets and paragraph styles, based upon the other layout
21723 information that is provided.
21724 In this section, we shall say a word about which layout information LyX
21728 \begin_layout Standard
21729 At present, LyX auto-generates CSS only for font information, making use
21731 \begin_inset Flex Code
21734 \begin_layout Plain Layout
21741 \begin_inset Flex Code
21744 \begin_layout Plain Layout
21751 \begin_inset Flex Code
21754 \begin_layout Plain Layout
21761 \begin_inset Flex Code
21764 \begin_layout Plain Layout
21771 \begin_inset Flex Code
21774 \begin_layout Plain Layout
21782 \begin_inset CommandInset ref
21784 reference "sub:Font-description"
21788 .) The translation is mostly straightforward and obvious.
21790 \begin_inset Quotes eld
21794 \begin_inset Flex Code
21797 \begin_layout Plain Layout
21804 \begin_inset Quotes erd
21808 \begin_inset Quotes eld
21812 \begin_inset Flex Code
21815 \begin_layout Plain Layout
21816 font-family: sans-serif;
21822 \begin_inset Quotes erd
21826 The correspondence of LyX sizes and CSS sizes is a little less obvious
21827 but nonetheless intuitive.
21829 \begin_inset Flex Code
21832 \begin_layout Plain Layout
21839 \begin_inset Flex URL
21842 \begin_layout Plain Layout
21852 \begin_layout Chapter
21853 Including External Material
21856 \begin_layout Standard
21857 \begin_inset Box Shadowbox
21867 height_special "totalheight"
21870 \begin_layout Plain Layout
21871 WARNING: This portion of the documentation has not been updated for some
21873 We certainly hope that it is still accurate, but there are no guarantees.
21881 \begin_layout Standard
21882 The use of material from sources external to LyX is covered in detail in
21888 This part of the manual covers what needs to happen behind the scenes for
21889 new sorts of material to be included.
21892 \begin_layout Section
21896 \begin_layout Standard
21897 The external material feature is based on the concept of a
21902 A template is a specification of how LyX should interface with a certain
21904 As bundled, LyX comes with predefined templates for Xfig figures, various
21905 raster format images, chess diagrams, and LilyPond music notation.
21906 You can check the actual list by using the menu
21907 \begin_inset Flex MenuItem
21910 \begin_layout Plain Layout
21911 Insert\SpecialChar \menuseparator
21912 File\SpecialChar \menuseparator
21919 Furthermore, it is possible to roll your own template to support a specific
21921 Later we'll describe in more detail what is involved, and hopefully you
21922 will submit all the templates you create so we can include them in a later
21926 \begin_layout Standard
21927 Another basic idea of the external material feature is to distinguish between
21928 the original file that serves as a base for final material and the produced
21929 file that is included in your exported or printed document.
21930 For example, consider the case of a figure produced with
21931 \begin_inset Flex Code
21934 \begin_layout Plain Layout
21941 The Xfig application itself works on an original file with the
21942 \begin_inset Flex Code
21945 \begin_layout Plain Layout
21952 Within Xfig, you create and change your figure, and when you are done,
21954 \begin_inset Flex Code
21957 \begin_layout Plain Layout
21964 When you want to include the figure in your document, you invoke
21965 \begin_inset Flex Code
21968 \begin_layout Plain Layout
21974 in order to create a PostScript file that can readily be included in your
21977 \begin_inset Flex Code
21980 \begin_layout Plain Layout
21986 file is the original file, and the PostScript file is the produced file.
21989 \begin_layout Standard
21990 This distinction is important in order to allow updating of the material
21991 while you are in the process of writing the document.
21992 Furthermore, it provides us with the flexibility that is needed to support
21993 multiple export formats.
21994 For instance, in the case of a plain text file, it is not exactly an award-winn
21995 ing idea to include the figure as raw PostScript.
21996 Instead, you would either prefer to just include a reference to the figure
21997 or try to invoke some graphics to ASCII converter to make the final result
21998 look similar to the real graphics.
21999 The external material management allows you to do this, because it is parametri
22000 zed on the different export formats that LyX supports.
22003 \begin_layout Standard
22004 Besides supporting the production of different products according to the
22005 exported format, it supports tight integration with editing and viewing
22007 In the case of an Xfig figure, you are able to invoke Xfig on the original
22008 file with a single click from within the external material dialog in LyX,
22009 and also preview the produced PostScript file with Ghostview with another
22011 No more fiddling around with the command line and/or file browsers to locate
22012 and manipulate the original or produced files.
22013 In this way, you are finally able to take full advantage of the many different
22014 applications that are relevant to use when you write your documents, and
22015 ultimately be more productive.
22018 \begin_layout Section
22019 The external template configuration file
22022 \begin_layout Standard
22023 It is relatively easy to add custom external template definitions to LyX.
22024 However, be aware that doing this in an careless manner most probably
22028 introduce an easily exploitable security hole.
22029 So before you do this, please read the discussion about security in section
22031 \begin_inset CommandInset ref
22033 reference "sec:Security-discussion"
22040 \begin_layout Standard
22041 Having said that, we encourage you to submit any interesting templates that
22046 \begin_layout Standard
22047 The external templates are defined in the
22048 \begin_inset Flex Code
22051 \begin_layout Plain Layout
22052 LyXDir/lib/external_templates
22058 You can place your own version in
22059 \begin_inset Flex Code
22062 \begin_layout Plain Layout
22063 UserDir/external_templates
22071 \begin_layout Standard
22072 A typical template looks like this:
22075 \begin_layout LyX-Code
22079 \begin_layout LyX-Code
22080 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
22083 \begin_layout LyX-Code
22087 \begin_layout LyX-Code
22091 \begin_layout LyX-Code
22095 \begin_layout LyX-Code
22099 \begin_layout LyX-Code
22103 \begin_layout LyX-Code
22104 AutomaticProduction true
22107 \begin_layout LyX-Code
22111 \begin_layout LyX-Code
22115 \begin_layout LyX-Code
22119 \begin_layout LyX-Code
22120 TransformCommand Rotate RotationLatexCommand
22123 \begin_layout LyX-Code
22124 TransformCommand Resize ResizeLatexCommand
22127 \begin_layout LyX-Code
22128 Product "$$RotateFront$$ResizeFront
22131 \begin_layout LyX-Code
22136 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
22139 \begin_layout LyX-Code
22140 $$ResizeBack$$RotateBack"
22143 \begin_layout LyX-Code
22147 \begin_layout LyX-Code
22148 UpdateResult "$$AbsPath$$Basename.pstex_t"
22151 \begin_layout LyX-Code
22152 Requirement "graphicx"
22155 \begin_layout LyX-Code
22156 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
22159 \begin_layout LyX-Code
22160 ReferencedFile latex "$$AbsPath$$Basename.eps"
22163 \begin_layout LyX-Code
22164 ReferencedFile dvi "$$AbsPath$$Basename.eps"
22167 \begin_layout LyX-Code
22171 \begin_layout LyX-Code
22175 \begin_layout LyX-Code
22176 TransformCommand Rotate RotationLatexCommand
22179 \begin_layout LyX-Code
22180 TransformCommand Resize ResizeLatexCommand
22183 \begin_layout LyX-Code
22184 Product "$$RotateFront$$ResizeFront
22187 \begin_layout LyX-Code
22192 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
22195 \begin_layout LyX-Code
22196 $$ResizeBack$$RotateBack"
22199 \begin_layout LyX-Code
22200 UpdateFormat pdftex
22203 \begin_layout LyX-Code
22204 UpdateResult "$$AbsPath$$Basename.pdftex_t"
22207 \begin_layout LyX-Code
22208 Requirement "graphicx"
22211 \begin_layout LyX-Code
22212 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
22215 \begin_layout LyX-Code
22216 ReferencedFile latex "$$AbsPath$$Basename.pdf"
22219 \begin_layout LyX-Code
22223 \begin_layout LyX-Code
22227 \begin_layout LyX-Code
22228 Product "$$Contents(
22230 "$$AbsPath$$Basename.asc
22235 \begin_layout LyX-Code
22236 UpdateFormat asciixfig
22239 \begin_layout LyX-Code
22240 UpdateResult "$$AbsPath$$Basename.asc"
22243 \begin_layout LyX-Code
22247 \begin_layout LyX-Code
22251 \begin_layout LyX-Code
22252 Product "<graphic fileref=
22254 "$$AbsOrRelPathMaster$$Basename.eps
22259 \begin_layout LyX-Code
22263 \begin_layout LyX-Code
22267 \begin_layout LyX-Code
22268 UpdateResult "$$AbsPath$$Basename.eps"
22271 \begin_layout LyX-Code
22272 ReferencedFile docbook "$$AbsPath$$Basename.eps"
22275 \begin_layout LyX-Code
22276 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
22279 \begin_layout LyX-Code
22283 \begin_layout LyX-Code
22284 Product "[XFig: $$FName]"
22287 \begin_layout LyX-Code
22291 \begin_layout LyX-Code
22295 \begin_layout Standard
22296 As you can see, the template is enclosed in
22297 \begin_inset Flex Code
22300 \begin_layout Plain Layout
22306 \SpecialChar \ldots{}
22308 \begin_inset Flex Code
22311 \begin_layout Plain Layout
22318 It contains a header specifying some general settings and, for each supported
22319 primary document file format, a section
22320 \begin_inset Flex Code
22323 \begin_layout Plain Layout
22329 \SpecialChar \ldots{}
22331 \begin_inset Flex Code
22334 \begin_layout Plain Layout
22343 \begin_layout Subsection
22344 The template header
22347 \begin_layout Description
22348 \begin_inset Flex Code
22351 \begin_layout Plain Layout
22352 AutomaticProduction
22353 \begin_inset space ~
22361 Whether the file represented by the template must be generated by LyX.
22362 This command must occur exactly once.
22365 \begin_layout Description
22366 \begin_inset Flex Code
22369 \begin_layout Plain Layout
22371 \begin_inset space ~
22379 A glob pattern that is used in the file dialog to filter out the desired
22381 If there is more than one possible file extension (e.
22382 \begin_inset space \thinspace{}
22386 \begin_inset space \space{}
22390 \begin_inset Flex Code
22393 \begin_layout Plain Layout
22400 \begin_inset Flex Code
22403 \begin_layout Plain Layout
22409 ), use something like
22410 \begin_inset Flex Code
22413 \begin_layout Plain Layout
22420 This command must occur exactly once.
22423 \begin_layout Description
22424 \begin_inset Flex Code
22427 \begin_layout Plain Layout
22429 \begin_inset space ~
22437 The text that is displayed on the button.
22438 This command must occur exactly once.
22441 \begin_layout Description
22442 \begin_inset Flex Code
22445 \begin_layout Plain Layout
22447 \begin_inset space ~
22451 \begin_inset space ~
22459 The help text that is used in the External dialog.
22460 Provide enough information to explain to the user just what the template
22461 can provide him with.
22462 This command must occur exactly once.
22465 \begin_layout Description
22466 \begin_inset Flex Code
22469 \begin_layout Plain Layout
22471 \begin_inset space ~
22479 The file format of the original file.
22480 This must be the name of a format that is known to LyX (see section
22481 \begin_inset space ~
22485 \begin_inset CommandInset ref
22487 reference "sec:Formats"
22493 \begin_inset Quotes eld
22497 \begin_inset Flex Code
22500 \begin_layout Plain Layout
22507 \begin_inset Quotes erd
22510 if the template can handle original files of more than one format.
22511 LyX will attempt to interrogate the file itself in order to deduce its
22512 format in this case.
22513 This command must occur exactly once.
22516 \begin_layout Description
22517 \begin_inset Flex Code
22520 \begin_layout Plain Layout
22522 \begin_inset space ~
22530 A unique name for the template.
22531 It must not contain substitution macros (see below).
22534 \begin_layout Description
22535 \begin_inset Flex Code
22538 \begin_layout Plain Layout
22540 \begin_inset space ~
22543 Rotate|Resize|Clip|Extra
22548 This command specifies which transformations are supported by this template.
22549 It may occur zero or more times.
22550 This command enables the corresponding tabs in the external dialog.
22552 \begin_inset Flex Code
22555 \begin_layout Plain Layout
22561 command must have either a corresponding
22562 \begin_inset Flex Code
22565 \begin_layout Plain Layout
22572 \begin_inset Flex Code
22575 \begin_layout Plain Layout
22582 \begin_inset Flex Code
22585 \begin_layout Plain Layout
22592 Otherwise the transformation will not be supported by that format.
22595 \begin_layout Subsection
22599 \begin_layout Description
22600 \begin_inset Flex Code
22603 \begin_layout Plain Layout
22605 \begin_inset space ~
22608 LaTeX|PDFLaTeX|PlainText|DocBook
22613 The primary document file format that this format definition is for.
22614 Not every template has a sensible representation in all document file formats.
22615 Please define nevertheless a
22616 \begin_inset Flex Code
22619 \begin_layout Plain Layout
22625 section for all templates.
22626 Use a dummy text when no representation is available.
22627 Then you can at least see a reference to the external material in the exported
22631 \begin_layout Description
22632 \begin_inset Flex Code
22635 \begin_layout Plain Layout
22637 \begin_inset space ~
22641 \begin_inset space ~
22649 This command defines an additional macro
22650 \begin_inset Flex Code
22653 \begin_layout Plain Layout
22659 for substitution in
22660 \begin_inset Flex Code
22663 \begin_layout Plain Layout
22671 \begin_inset Flex Code
22674 \begin_layout Plain Layout
22680 itself may contain substitution macros.
22681 The advantage over using
22682 \begin_inset Flex Code
22685 \begin_layout Plain Layout
22692 \begin_inset Flex Code
22695 \begin_layout Plain Layout
22701 is that the substituted value of
22702 \begin_inset Flex Code
22705 \begin_layout Plain Layout
22711 is sanitized so that it is a valid optional argument in the document format.
22712 This command may occur zero or more times.
22715 \begin_layout Description
22716 \begin_inset Flex Code
22719 \begin_layout Plain Layout
22721 \begin_inset space ~
22729 The text that is inserted in the exported document.
22730 This is actually the most important command and can be quite complex.
22731 This command must occur exactly once.
22734 \begin_layout Description
22735 \begin_inset Flex Code
22738 \begin_layout Plain Layout
22740 \begin_inset space ~
22748 This command specifies a preamble snippet that will be included in the
22750 It has to be defined using
22751 \begin_inset Flex Code
22754 \begin_layout Plain Layout
22760 \SpecialChar \ldots{}
22762 \begin_inset Flex Code
22765 \begin_layout Plain Layout
22772 This command may occur zero or more times.
22775 \begin_layout Description
22776 \begin_inset Flex Code
22779 \begin_layout Plain Layout
22781 \begin_inset space ~
22785 \begin_inset space ~
22793 This command denotes files that are created by the conversion process and
22794 are needed for a particular export format.
22795 If the filename is relative, it is interpreted relative to the master document.
22796 This command may be given zero or more times.
22799 \begin_layout Description
22800 \begin_inset Flex Code
22803 \begin_layout Plain Layout
22805 \begin_inset space ~
22813 The name of a required LaTeX package.
22814 The package is included via
22815 \begin_inset Flex Code
22818 \begin_layout Plain Layout
22826 in the LaTeX preamble.
22827 This command may occur zero or more times.
22830 \begin_layout Description
22831 \begin_inset Flex Code
22834 \begin_layout Plain Layout
22836 \begin_inset space ~
22840 \begin_inset space ~
22843 RotationLatexCommand
22848 This command specifies that the built in LaTeX command should be used for
22850 This command may occur once or not at all.
22853 \begin_layout Description
22854 \begin_inset Flex Code
22857 \begin_layout Plain Layout
22859 \begin_inset space ~
22863 \begin_inset space ~
22871 This command specifies that the built in LaTeX command should be used for
22873 This command may occur once or not at all.
22876 \begin_layout Description
22877 \begin_inset Flex Code
22880 \begin_layout Plain Layout
22882 \begin_inset space ~
22886 \begin_inset space ~
22889 RotationLatexOption
22894 This command specifies that rotation is done via an optional argument.
22895 This command may occur once or not at all.
22898 \begin_layout Description
22899 \begin_inset Flex Code
22902 \begin_layout Plain Layout
22904 \begin_inset space ~
22908 \begin_inset space ~
22916 This command specifies that resizing is done via an optional argument.
22917 This command may occur once or not at all.
22920 \begin_layout Description
22921 \begin_inset Flex Code
22924 \begin_layout Plain Layout
22926 \begin_inset space ~
22930 \begin_inset space ~
22938 This command specifies that clipping is done via an optional argument.
22939 This command may occur once or not at all.
22942 \begin_layout Description
22943 \begin_inset Flex Code
22946 \begin_layout Plain Layout
22948 \begin_inset space ~
22952 \begin_inset space ~
22960 This command specifies that an extra optional argument is used.
22961 This command may occur once or not at all.
22964 \begin_layout Description
22965 \begin_inset Flex Code
22968 \begin_layout Plain Layout
22970 \begin_inset space ~
22978 The file format of the converted file.
22979 This must be the name of a format that is known to LyX (see the
22980 \begin_inset Flex MenuItem
22983 \begin_layout Plain Layout
22988 ools\SpecialChar \menuseparator
22993 references\SpecialChar \menuseparator
22994 File Handling\SpecialChar \menuseparator
23001 This command must occur exactly once.
23004 \begin_layout Description
23005 \begin_inset Flex Code
23008 \begin_layout Plain Layout
23010 \begin_inset space ~
23018 The file name of the converted file.
23019 The file name must be absolute.
23020 This command must occur exactly once.
23023 \begin_layout Subsection
23024 Preamble definitions
23027 \begin_layout Standard
23028 The external template configuration file may contain additional preamble
23029 definitions enclosed by
23030 \begin_inset Flex Code
23033 \begin_layout Plain Layout
23039 \SpecialChar \ldots{}
23041 \begin_inset Flex Code
23044 \begin_layout Plain Layout
23051 They can be used by the templates in the
23052 \begin_inset Flex Code
23055 \begin_layout Plain Layout
23064 \begin_layout Section
23065 The substitution mechanism
23068 \begin_layout Standard
23069 When the external material facility invokes an external program, it is done
23070 on the basis of a command defined in the template configuration file.
23071 These commands can contain various macros that are expanded before execution.
23072 Execution always take place in the directory of the containing document.
23075 \begin_layout Standard
23076 Also, whenever external material is to be displayed, the name will be produced
23077 by the substitution mechanism, and most other commands in the template
23078 definition support substitution as well.
23081 \begin_layout Standard
23082 The available macros are the following:
23085 \begin_layout Description
23086 \begin_inset Flex Code
23089 \begin_layout Plain Layout
23090 $$AbsOrRelPathMaster
23095 The file path, absolute or relative to the master LyX document.
23098 \begin_layout Description
23099 \begin_inset Flex Code
23102 \begin_layout Plain Layout
23103 $$AbsOrRelPathParent
23108 The file path, absolute or relative to the LyX document.
23111 \begin_layout Description
23112 \begin_inset Flex Code
23115 \begin_layout Plain Layout
23121 The absolute file path.
23124 \begin_layout Description
23125 \begin_inset Flex Code
23128 \begin_layout Plain Layout
23134 The filename without path and without the extension.
23137 \begin_layout Description
23138 \begin_inset Flex Code
23141 \begin_layout Plain Layout
23143 \begin_inset Quotes eld
23147 \begin_inset Quotes erd
23155 This macro will expand to the contents of the file with the name
23156 \begin_inset Flex Code
23159 \begin_layout Plain Layout
23168 \begin_layout Description
23169 \begin_inset Flex Code
23172 \begin_layout Plain Layout
23178 The file extension (including the dot).
23181 \begin_layout Description
23182 \begin_inset Flex Code
23185 \begin_layout Plain Layout
23191 The filename of the file specified in the external material dialog.
23192 This is either an absolute name, or it is relative to the LyX document.
23195 \begin_layout Description
23196 \begin_inset Flex Code
23199 \begin_layout Plain Layout
23206 \begin_inset Flex Code
23209 \begin_layout Plain Layout
23215 (absolute name or relative to the LyX document).
23218 \begin_layout Description
23219 \begin_inset Flex Code
23222 \begin_layout Plain Layout
23228 The file path, relative to the master LyX document.
23231 \begin_layout Description
23232 \begin_inset Flex Code
23235 \begin_layout Plain Layout
23241 The file path, relative to the LyX document.
23244 \begin_layout Description
23245 \begin_inset Flex Code
23248 \begin_layout Plain Layout
23254 This macro will expand to the absolute path of the system directory.
23255 This is typically used to point to the various helper scripts that are
23259 \begin_layout Description
23260 \begin_inset Flex Code
23263 \begin_layout Plain Layout
23269 A name and full path to a temporary file which will be automatically deleted
23270 whenever the containing document is closed, or the external material insertion
23274 \begin_layout Standard
23275 All path macros contain a trailing directory separator, so you can construct
23277 \begin_inset space \thinspace{}
23281 \begin_inset space \space{}
23284 the absolute filename with
23285 \begin_inset Flex Code
23288 \begin_layout Plain Layout
23289 $$AbsPath$$Basename$$Extension
23297 \begin_layout Standard
23298 The macros above are substituted in all commands unless otherwise noted.
23300 \begin_inset Flex Code
23303 \begin_layout Plain Layout
23309 supports additionally the following substitutions if they are enabled by
23311 \begin_inset Flex Code
23314 \begin_layout Plain Layout
23321 \begin_inset Flex Code
23324 \begin_layout Plain Layout
23333 \begin_layout Description
23334 \begin_inset Flex Code
23337 \begin_layout Plain Layout
23343 The front part of the resize command.
23346 \begin_layout Description
23347 \begin_inset Flex Code
23350 \begin_layout Plain Layout
23356 The back part of the resize command.
23359 \begin_layout Description
23360 \begin_inset Flex Code
23363 \begin_layout Plain Layout
23369 The front part of the rotation command.
23372 \begin_layout Description
23373 \begin_inset Flex Code
23376 \begin_layout Plain Layout
23382 The back part of the rotation command.
23385 \begin_layout Standard
23386 The value string of the
23387 \begin_inset Flex Code
23390 \begin_layout Plain Layout
23396 command supports additionally the following substitutions if they are enabled
23398 \begin_inset Flex Code
23401 \begin_layout Plain Layout
23408 \begin_inset Flex Code
23411 \begin_layout Plain Layout
23420 \begin_layout Description
23421 \begin_inset Flex Code
23424 \begin_layout Plain Layout
23433 \begin_layout Description
23434 \begin_inset Flex Code
23437 \begin_layout Plain Layout
23446 \begin_layout Description
23447 \begin_inset Flex Code
23450 \begin_layout Plain Layout
23459 \begin_layout Description
23460 \begin_inset Flex Code
23463 \begin_layout Plain Layout
23469 The rotation option.
23472 \begin_layout Standard
23473 You may ask why there are so many path macros.
23474 There are mainly two reasons:
23477 \begin_layout Enumerate
23478 Relative and absolute file names should remain relative or absolute, respectivel
23480 Users may have reasons to prefer either form.
23481 Relative names are useful for portable documents that should work on different
23482 machines, for example.
23483 Absolute names may be required by some programs.
23486 \begin_layout Enumerate
23487 LaTeX treats relative file names differently than LyX and other programs
23488 in nested included files.
23489 For LyX, a relative file name is always relative to the document that contains
23491 For LaTeX, it is always relative to the master document.
23492 These two definitions are identical if you have only one document, but
23493 differ if you have a master document that includes part documents.
23494 That means that relative filenames must be transformed when presented to
23496 Fortunately LyX does this automatically for you if you choose the right
23500 \begin_layout Standard
23501 So which path macro should be used in new template definitions? The rule
23505 \begin_layout Itemize
23507 \begin_inset Flex Code
23510 \begin_layout Plain Layout
23516 if an absolute path is required.
23519 \begin_layout Itemize
23521 \begin_inset Flex Code
23524 \begin_layout Plain Layout
23525 $$AbsOrRelPathMaster
23530 if the substituted string is some kind of LaTeX input.
23533 \begin_layout Itemize
23535 \begin_inset Flex Code
23538 \begin_layout Plain Layout
23539 $$AbsOrRelPathParent
23544 in order to preserve the user's choice.
23547 \begin_layout Standard
23548 There are special cases where this rule does not work and e.
23549 \begin_inset space \thinspace{}
23553 \begin_inset space \space{}
23556 relative names are needed, but normally it will work just fine.
23557 One example for such a case is the command
23558 \begin_inset Flex Code
23561 \begin_layout Plain Layout
23562 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
23567 in the XFig template above: We can't use the absolute name because the
23569 \begin_inset Flex Code
23572 \begin_layout Plain Layout
23578 files needs the relative name in order to rewrite the file content.
23581 \begin_layout Section
23582 Security discussion
23583 \begin_inset CommandInset label
23585 name "sec:Security-discussion"
23592 \begin_layout Standard
23593 The external material feature interfaces with a lot of external programs
23594 and does so automatically, so we have to consider the security implications
23596 In particular, since you have the option of including your own filenames
23597 and/or parameter strings and those are expanded into a command, it seems
23598 that it would be possible to create a malicious document which executes
23599 arbitrary commands when a user views or prints the document.
23600 This is something we definitely want to avoid.
23603 \begin_layout Standard
23604 However, since the external program commands are specified in the template
23605 configuration file only, there are no security issues if LyX is properly
23606 configured with safe templates only.
23607 This is so because the external programs are invoked with the
23608 \begin_inset Flex Code
23611 \begin_layout Plain Layout
23617 -system call rather than the
23618 \begin_inset Flex Code
23621 \begin_layout Plain Layout
23627 system-call, so it's not possible to execute arbitrary commands from the
23628 filename or parameter section via the shell.
23631 \begin_layout Standard
23632 This also implies that you are restricted in what command strings you can
23633 use in the external material templates.
23634 In particular, pipes and redirection are not readily available.
23635 This has to be so if LyX should remain safe.
23636 If you want to use some of the shell features, you should write a safe
23637 script to do this in a controlled manner, and then invoke the script from
23638 the command string.
23642 \begin_layout Standard
23643 It is possible to design a template that interacts directly with the shell,
23644 but since this would allow a malicious user to execute arbitrary commands
23645 by writing clever filenames and/or parameters, we generally recommend that
23646 you only use safe scripts that work with the
23647 \begin_inset Flex Code
23650 \begin_layout Plain Layout
23656 system call in a controlled manner.
23657 Of course, for use in a controlled environment, it can be tempting to just
23658 fall back to use ordinary shell scripts.
23659 If you do so, be aware that you
23663 provide an easily exploitable security hole in your system.
23664 Of course it stands to reason that such unsafe templates will never be
23665 included in the standard LyX distribution, although we do encourage people
23666 to submit new templates in the open source tradition.
23667 But LyX as shipped from the official distribution channels will never have
23671 \begin_layout Standard
23672 Including external material provides a lot of power, and you have to be
23673 careful not to introduce security hazards with this power.
23674 A subtle error in a single line in an innocent looking script can open
23675 the door to huge security problems.
23676 So if you do not fully understand the issues, we recommend that you consult
23677 a knowledgeable security professional or the LyX development team if you
23678 have any questions about whether a given template is safe or not.
23679 And do this before you use it in an uncontrolled environment.