1 #LyX 2.0 created this file. For more info see http://www.lyx.org/
7 % DO NOT ALTER THIS PREAMBLE!!!
9 % This preamble is designed to ensure that this document prints
10 % out as advertised. If you mess with this preamble,
11 % parts of this document may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 % redefine the \LyX macro for PDF bookmarks
35 \def\LyX{\texorpdfstring{%
36 L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
39 % used for multi-column text
42 \options fleqn,bibliography=totoc,index=totoc,BCOR7.5mm,titlepage,captions=tableheading
43 \use_default_options false
47 \maintain_unincluded_children false
50 InsetLayout Flex:MenuItem
59 \newcommand*{\menuitem}[1]{{\sffamily #1}}
62 # In case we need to do with sans...
63 #InsetLayout CharStyle:Code
68 #\renewcommand{\code}[1]{{\sffamily #1}}
73 \language_package default
78 \font_typewriter default
79 \font_default_family default
80 \use_non_tex_fonts false
87 \default_output_format default
89 \bibtex_command default
90 \index_command default
94 \pdf_title "LyX Configuration Manual"
95 \pdf_author "LyX Team"
96 \pdf_subject "LyX-documentation Customization"
97 \pdf_keywords "LyX, documentation, customization"
99 \pdf_bookmarksnumbered true
100 \pdf_bookmarksopen true
101 \pdf_bookmarksopenlevel 1
102 \pdf_breaklinks false
106 \pdf_pdfusetitle false
107 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
117 \paperorientation portrait
131 \paragraph_separation indent
132 \paragraph_indentation default
133 \quotes_language english
136 \paperpagestyle headings
137 \tracking_changes true
138 \output_changes false
142 \author 1414654397 "Richard Heck"
148 Customizing LyX: Features for the Advanced User
156 \begin_layout Plain Layout
158 If you have comments or error corrections, please send them to the LyX Documenta
160 \begin_inset CommandInset href
162 target "lyx-docs@lists.lyx.org"
169 \begin_inset Quotes eld
173 \begin_inset Quotes erd
176 in the subject header, and please cc the current maintainer of this file,
177 Richard Heck <rgheck@comcast.net>.
183 \begin_inset Newline newline
187 \begin_inset Newline newline
193 \begin_layout Standard
194 \begin_inset CommandInset toc
195 LatexCommand tableofcontents
202 \begin_layout Standard
203 \begin_inset Note Note
206 \begin_layout Plain Layout
207 Please use change tracking when modifying this document.
208 This makes it easier for our translators to recognize things that have
209 been changed, and it helps the maintainer keep up-to-date with what's been
218 \begin_layout Chapter
222 \begin_layout Standard
223 This manual covers the customization features present in LyX.
224 In it, we discuss issues like keyboard shortcuts, screen previewing options,
225 printer options, sending commands to LyX via the LyX Server, internationalizati
226 on, installing new LaTeX classes and LyX layouts, etc.
227 We can't possibly hope to touch on everything you can change—our developers
228 add new features faster than we can document them—but we will explain the
229 most common customizations and hopefully point you in the right direction
230 for some of the more obscure ones.
233 \begin_layout Standard
234 \begin_inset Branch OutDated
237 \begin_layout Standard
238 Information from previous versions of this document that now seems to be
239 outdated is contained in the OutDated branch of this document.
240 By default, this information will not appear in the LaTeX output.
248 \begin_layout Chapter
249 LyX configuration files
252 \begin_layout Standard
253 This chapter aims to help you to find your way through the LyX configuration
255 Before continuing to read this chapter, you should find out where your
256 LyX library and user directories are by using
257 \begin_inset Flex MenuItem
260 \begin_layout Plain Layout
261 Help\SpecialChar \menuseparator
272 The library directory is the place where LyX places its system-wide configurati
273 on files; the user directory is where you can place your modified versions.
274 We will call the former
275 \begin_inset Flex Code
278 \begin_layout Plain Layout
285 \begin_inset Flex MenuItem
288 \begin_layout Plain Layout
294 in the remainder of this document.
298 \begin_layout Section
300 \begin_inset Flex Code
303 \begin_layout Plain Layout
312 \begin_layout Standard
313 \begin_inset Flex Code
316 \begin_layout Plain Layout
322 and its sub-directories contain a number of files and that can be used
323 to customize LyX's behavior.
324 You can change many of these files from within LyX itself through the
325 \begin_inset Flex MenuItem
328 \begin_layout Plain Layout
329 Tools\SpecialChar \menuseparator
336 Most customization that you will want to do in LyX is possible through
338 However, many other inner aspects of LyX can be customized by modifying
340 \begin_inset Flex Code
343 \begin_layout Plain Layout
350 These files fall in different categories, described in the following subsection
354 \begin_layout Subsection
355 Automatically generated files
358 \begin_layout Standard
359 The files, which are to be found in
360 \begin_inset Flex MenuItem
363 \begin_layout Plain Layout
369 , are generated when you configure LyX.
370 They contain various default values that are guessed by inspection.
371 In general, it is not a good idea to modify them, since they might be overwritt
375 \begin_layout Labeling
376 \labelwidthstring 00.00.0000
377 \begin_inset Flex Code
380 \begin_layout Plain Layout
386 contains defaults for various commands.
389 \begin_layout Labeling
390 \labelwidthstring 00.00.0000
391 \begin_inset Flex Code
394 \begin_layout Plain Layout
400 contains the list of packages that have been recognized by LyX.
401 It is currently unused by the LyX program itself, but the information extracted
402 , and more, is made available with
403 \begin_inset Flex MenuItem
406 \begin_layout Plain Layout
407 Help\SpecialChar \menuseparator
420 \begin_layout Labeling
421 \labelwidthstring 00.00.0000
422 \begin_inset Flex Code
425 \begin_layout Plain Layout
431 the list of text classes that have been found in your
432 \begin_inset Flex Code
435 \begin_layout Plain Layout
441 directories, along with the associated LaTeX document class and their descripti
445 \begin_layout Labeling
446 \labelwidthstring 00.00.0000
447 \begin_inset Flex Code
450 \begin_layout Plain Layout
456 the list of layout modules found in your
457 \begin_inset Flex Code
460 \begin_layout Plain Layout
469 \begin_layout Labeling
470 \labelwidthstring 00.00.0000
471 \begin_inset Flex Code
474 \begin_layout Plain Layout
480 lists of various sorts of LaTeX-related files found on your system
483 \begin_layout Labeling
484 \labelwidthstring 00.00.0000
485 \begin_inset Flex Code
488 \begin_layout Plain Layout
494 is automatically generated during configuration from the file
495 \begin_inset Flex Code
498 \begin_layout Plain Layout
505 It contains information on your LaTeX configuration.
508 \begin_layout Subsection
512 \begin_layout Standard
513 These directories are duplicated between
514 \begin_inset Flex Code
517 \begin_layout Plain Layout
524 \begin_inset Flex Code
527 \begin_layout Plain Layout
534 If a particular files exists in both places, the one in
535 \begin_inset Flex Code
538 \begin_layout Plain Layout
547 \begin_layout Labeling
548 \labelwidthstring 00.00.0000
549 \begin_inset Flex Code
552 \begin_layout Plain Layout
558 this directory contains files with the extension
559 \begin_inset Flex Code
562 \begin_layout Plain Layout
568 that define the keybindings used in LyX.
569 If there exists an internationalized version of the bind file named
570 \begin_inset Flex Code
573 \begin_layout Plain Layout
579 , that will be used first.
582 \begin_layout Labeling
583 \labelwidthstring 00.00.0000
584 \begin_inset Flex Code
587 \begin_layout Plain Layout
593 contains graphics files that can be included in documents.
597 \begin_layout Labeling
598 \labelwidthstring 00.00.0000
599 \begin_inset Flex Code
602 \begin_layout Plain Layout
608 contains LyX documentation files (including the one you are currently reading).
610 \begin_inset Flex Code
613 \begin_layout Plain Layout
619 deserves special attention, as noted above.
620 The internationalized help docs are in subdirectories
621 \begin_inset Flex Code
624 \begin_layout Plain Layout
631 \begin_inset Quotes eld
635 \begin_inset Quotes erd
638 is the ISO language code.
644 \begin_inset CommandInset ref
646 reference "cha:Internationalizing-LyX"
653 \begin_layout Labeling
654 \labelwidthstring 00.00.0000
655 \begin_inset Flex Code
658 \begin_layout Plain Layout
664 contains example files that explain how to use some features.
665 In the file browser, press the
666 \begin_inset Flex MenuItem
669 \begin_layout Plain Layout
678 \begin_layout Labeling
679 \labelwidthstring 00.00.0000
680 \begin_inset Flex Code
683 \begin_layout Plain Layout
689 contains image files that are used by the
690 \begin_inset Flex MenuItem
693 \begin_layout Plain Layout
700 In addition, it also contains the individual icons used in the toolbar
701 and the banners that can be shown when LyX is launched.
704 \begin_layout Labeling
705 \labelwidthstring 00.00.0000
706 \begin_inset Flex Code
709 \begin_layout Plain Layout
715 contains keyboard keymapping files.
721 \begin_inset CommandInset ref
723 reference "sec:International-Keymap-Stuff"
730 \begin_layout Labeling
731 \labelwidthstring 00.00.0000
732 \begin_inset Flex Code
735 \begin_layout Plain Layout
741 contains the text class and module files described in Chapter
746 \begin_inset CommandInset ref
748 reference "cha:Installing-New-Document"
755 \begin_layout Labeling
756 \labelwidthstring 00.00.0000
757 \begin_inset Flex Code
760 \begin_layout Plain Layout
767 \begin_inset Flex Code
770 \begin_layout Plain Layout
776 Python scripts used to convert between LyX versions.
777 These can be run from the command line if, say, you want to batch-convert
781 \begin_layout Labeling
782 \labelwidthstring 00.00.0000
783 \begin_inset Flex Code
786 \begin_layout Plain Layout
792 contains some files that demonstrate the capabilities of the
793 \begin_inset Flex MenuItem
796 \begin_layout Plain Layout
807 Also contains some scripts used by LyX itself.
810 \begin_layout Labeling
811 \labelwidthstring 00.00.0000
812 \begin_inset Flex Code
815 \begin_layout Plain Layout
821 contains the standard LyX template files described in Chapter
826 \begin_inset CommandInset ref
828 reference "sub:Creating-Templates"
835 \begin_layout Labeling
836 \labelwidthstring 00.00.0000
837 \begin_inset Flex Code
840 \begin_layout Plain Layout
846 contains files with the extension
847 \begin_inset Flex Code
850 \begin_layout Plain Layout
856 that define the user interface to LyX.
857 That is, the files define which items appear in which menus and the items
858 appearing on the toolbar.
861 \begin_layout Subsection
862 Files you don't want to modify
865 \begin_layout Standard
866 These files are used internally by LyX and you generally do not need to
867 modify them unless you are a developer.
870 \begin_layout Labeling
871 \labelwidthstring 00.00.0000
872 \begin_inset Flex Code
875 \begin_layout Plain Layout
881 this file contains the list of LyX developers.
882 The contents are displayed with the menu entry
883 \begin_inset Flex MenuItem
886 \begin_layout Plain Layout
887 Help\SpecialChar \menuseparator
900 \begin_layout Labeling
901 \labelwidthstring 00.00.0000
902 \begin_inset Flex Code
905 \begin_layout Plain Layout
911 this is a LaTeX script used during the configuration process.
915 \begin_layout Labeling
916 \labelwidthstring 00.00.0000
917 \begin_inset Flex Code
920 \begin_layout Plain Layout
926 this is the script that is used to re-configure LyX.
927 It creates configuration files in the directory it was run from.
930 \begin_layout Subsection
931 Other files needing a line or two...
934 \begin_layout Labeling
935 \labelwidthstring 00.00.0000
936 \begin_inset Flex Code
939 \begin_layout Plain Layout
945 this contains tables describing how different character encodings can be
949 \begin_layout Labeling
950 \labelwidthstring 00.00.0000
951 \begin_inset Flex Code
954 \begin_layout Plain Layout
960 this file contains the templates available to the new
961 \begin_inset Flex MenuItem
964 \begin_layout Plain Layout
977 \begin_layout Labeling
978 \labelwidthstring 00.00.0000
979 \begin_inset Flex Code
982 \begin_layout Plain Layout
988 this file contains a list of all the languages currently supported by LyX.
991 \begin_layout Section
992 Your local configuration directory
995 \begin_layout Standard
996 Even if you are using LyX as an unprivileged user, you might want to change
997 LyX configuration for your own use.
999 \begin_inset Flex Code
1002 \begin_layout Plain Layout
1008 directory contains all your personal configuration files.
1009 This is the directory described as
1010 \begin_inset Quotes eld
1014 \begin_inset Quotes erd
1018 \begin_inset Flex MenuItem
1021 \begin_layout Plain Layout
1022 Help\SpecialChar \menuseparator
1024 \begin_inset space ~
1033 This directory is used as a mirror of
1034 \begin_inset Flex Code
1037 \begin_layout Plain Layout
1043 , which means that every file in
1044 \begin_inset Flex Code
1047 \begin_layout Plain Layout
1053 is a replacement for the corresponding file in
1054 \begin_inset Flex Code
1057 \begin_layout Plain Layout
1064 Any configuration file described in the above sections can be placed either
1065 in the system-wide directory, in which case it will affect all users, or
1066 in your local directory for your own use.
1069 \begin_layout Standard
1070 To make things clearer, let's provide a few examples:
1073 \begin_layout Itemize
1074 The preferences set in the
1075 \begin_inset Flex MenuItem
1078 \begin_layout Plain Layout
1079 Tools\SpecialChar \menuseparator
1085 dialog are saved to a file
1086 \begin_inset Flex Code
1089 \begin_layout Plain Layout
1096 \begin_inset Flex Code
1099 \begin_layout Plain Layout
1108 \begin_layout Itemize
1109 When you reconfigure using
1110 \begin_inset Flex MenuItem
1113 \begin_layout Plain Layout
1114 Tools\SpecialChar \menuseparator
1121 \begin_inset Flex Code
1124 \begin_layout Plain Layout
1130 script, and the resulting files are written in your local configuration
1132 This means that any additional text class file that you might have added
1134 \begin_inset Flex Code
1137 \begin_layout Plain Layout
1143 will be added to the list of classes in the
1144 \begin_inset Flex MenuItem
1147 \begin_layout Plain Layout
1148 Document\SpecialChar \menuseparator
1157 \begin_layout Itemize
1158 If you get some updated documentation from LyX ftp site and cannot install
1159 it because you do not have sysadmin rights on your system, you can just
1161 \begin_inset Flex Code
1164 \begin_layout Plain Layout
1170 and the items in the
1171 \begin_inset Flex MenuItem
1174 \begin_layout Plain Layout
1180 menu will open them!
1183 \begin_layout Section
1184 Running LyX with multiple configurations
1187 \begin_layout Standard
1188 The configuration freedom of the local configuration directory may not suffice
1189 if you want to have more than one configuration at your disposal.
1190 For example, you may want to be use different key bindings or printer settings
1192 You can achieve this by having several such directories.
1193 You then specify which directory to use at run-time.
1196 \begin_layout Standard
1197 Invoking LyX with the command line switch
1198 \begin_inset Flex Code
1201 \begin_layout Plain Layout
1211 instructs the program to read the configuration from that directory, and
1212 not from the default directory.
1213 (You can determine the default directory by running LyX without the
1214 \begin_inset Flex Code
1217 \begin_layout Plain Layout
1223 switch.) If the specified directory does not exist, LyX offers to create
1224 it for you, just like it does for the default directory on the first time
1225 you run the program.
1226 You can modify the configuration options in this additional user directory
1227 exactly as you would for the default directory.
1228 These directories are completely independent (but read on).
1229 Note that setting the environment variable
1230 \begin_inset Flex Code
1233 \begin_layout Plain Layout
1239 to some value has exactly the same effect.
1242 \begin_layout Standard
1243 Having several configurations also requires more maintenance: if you want
1244 to add a new layout to
1245 \begin_inset Flex Code
1248 \begin_layout Plain Layout
1254 which you want available from all your configurations, you must add it
1255 to each directory separately.
1256 You can avoid this with the following trick: after LyX creates the additional
1257 directory, most of the subdirectories (see above) are empty.
1258 If you want the new configuration to mirror an existing one, replace the
1259 empty subdirectory with a symbolic link to the matching subdirectory in
1260 the existing configuration.
1262 \begin_inset Flex Code
1265 \begin_layout Plain Layout
1271 subdirectory, however, since it contains a file written by the configuration
1272 script (also accessible through
1273 \begin_inset Flex MenuItem
1276 \begin_layout Plain Layout
1277 Tools\SpecialChar \menuseparator
1283 ) which is configuration-specific.
1286 \begin_layout Chapter
1287 The Preferences dialog
1290 \begin_layout Standard
1291 All options of the preferences dialog are described in the Appendix
1293 The Preferences Dialog
1300 For some options you might find here more details.
1303 \begin_layout Section
1305 \begin_inset CommandInset label
1314 \begin_layout Standard
1315 The first step is to define your file formats if they are not already defined.
1317 \begin_inset Flex MenuItem
1320 \begin_layout Plain Layout
1321 Tools\SpecialChar \menuseparator
1329 \begin_inset Flex MenuItem
1332 \begin_layout Plain Layout
1333 File Handling\SpecialChar \menuseparator
1340 \begin_inset Flex MenuItem
1343 \begin_layout Plain Layout
1344 New\SpecialChar \ldots{}
1350 button to define your new format.
1352 \begin_inset Flex MenuItem
1355 \begin_layout Plain Layout
1361 field contains the name used to identify the format in the GUI.
1363 \begin_inset Flex MenuItem
1366 \begin_layout Plain Layout
1372 is used to identify the format internally.
1373 You will also need to enter a file extension.
1374 These are all required.
1376 \begin_inset Flex MenuItem
1379 \begin_layout Plain Layout
1385 field is used to provide a keyboard shortcut on the menus.
1386 (For example, pressing
1387 \begin_inset Flex MenuItem
1390 \begin_layout Plain Layout
1397 \begin_inset Flex MenuItem
1400 \begin_layout Plain Layout
1401 View\SpecialChar \menuseparator
1402 View (Other Formats)\SpecialChar \menuseparator
1411 \begin_layout Standard
1413 \begin_inset Flex MenuItem
1416 \begin_layout Plain Layout
1423 \begin_inset Flex MenuItem
1426 \begin_layout Plain Layout
1433 For example, you might want to use
1434 \begin_inset Flex MenuItem
1437 \begin_layout Plain Layout
1443 to view PostScript files.
1444 You can enter the command needed to start the program in the corresponding
1446 In defining this command, you can use the four variables listed in the
1448 The viewer is launched when you view an image in LyX or use the
1449 \begin_inset Flex MenuItem
1452 \begin_layout Plain Layout
1459 The editor is for example launched when you right-click on an image and
1461 \begin_inset Flex MenuItem
1464 \begin_layout Plain Layout
1470 in the appearing context menu.
1473 \begin_layout Standard
1475 \begin_inset Flex MenuItem
1478 \begin_layout Plain Layout
1484 option tells LyX that a format is suitable for document export.
1485 If this is set and if a suitable conversion route exists (see sec.
1486 \begin_inset space \thinspace{}
1490 \begin_inset CommandInset ref
1492 reference "sec:Converters"
1496 ), the format will appear in the
1497 \begin_inset Flex MenuItem
1500 \begin_layout Plain Layout
1501 File\SpecialChar \menuseparator
1508 The format will also appear in the
1509 \begin_inset Flex MenuItem
1512 \begin_layout Plain Layout
1518 menu if a viewer is specified for the format.
1519 Pure image formats, such as
1520 \begin_inset Flex Code
1523 \begin_layout Plain Layout
1529 , should not use this option.
1530 Formats that can both represent vector graphics and documents like
1531 \begin_inset Flex Code
1534 \begin_layout Plain Layout
1543 \begin_layout Standard
1545 \begin_inset Flex MenuItem
1548 \begin_layout Plain Layout
1549 Vector graphics format
1554 tells LyX that a format can contain vector graphics.
1555 This information is used to determine the target format of included graphics
1557 \begin_inset Flex MenuItem
1560 \begin_layout Plain Layout
1567 Included graphics may need to be converted to either
1568 \begin_inset Flex MenuItem
1571 \begin_layout Plain Layout
1578 \begin_inset Flex MenuItem
1581 \begin_layout Plain Layout
1588 \begin_inset Flex MenuItem
1591 \begin_layout Plain Layout
1598 \begin_inset Flex MenuItem
1601 \begin_layout Plain Layout
1607 cannot handle other image formats.
1608 If an included graphic is not already in
1609 \begin_inset Flex MenuItem
1612 \begin_layout Plain Layout
1619 \begin_inset Flex MenuItem
1622 \begin_layout Plain Layout
1629 \begin_inset Flex MenuItem
1632 \begin_layout Plain Layout
1638 format, it is converted to
1639 \begin_inset Flex MenuItem
1642 \begin_layout Plain Layout
1648 if the vector format option is set, and otherwise to
1649 \begin_inset Flex MenuItem
1652 \begin_layout Plain Layout
1661 \begin_layout Section
1665 \begin_layout Standard
1666 Since all conversions from one format to another take place in LyX's temporary
1667 directory, it is sometimes necessary to modify a file before copying it
1668 to the temporary directory in order that the conversion may be performed.
1672 \begin_layout Plain Layout
1673 For example, the file may refer to other files—images, for example—using
1674 relative file names, and these may become invalid when the file is copied
1675 to the temporary directory.
1680 This is done by a Copier: It copies a file to (or from) the temporary directory
1681 and may modify it in the process.
1684 \begin_layout Standard
1685 The definitions of the copiers may use four variables:
1688 \begin_layout Labeling
1689 \labelwidthstring 00.00.0000
1690 \begin_inset Flex Code
1693 \begin_layout Plain Layout
1699 The LyX system directory (e.
1700 \begin_inset space \thinspace{}
1704 \begin_inset space \space{}
1708 \begin_inset Flex MenuItem
1711 \begin_layout Plain Layout
1720 \begin_layout Labeling
1721 \labelwidthstring 00.00.0000
1722 \begin_inset Flex Code
1725 \begin_layout Plain Layout
1734 \begin_layout Labeling
1735 \labelwidthstring 00.00.0000
1736 \begin_inset Flex Code
1739 \begin_layout Plain Layout
1748 \begin_layout Labeling
1749 \labelwidthstring 00.00.0000
1750 \begin_inset Flex Code
1753 \begin_layout Plain Layout
1762 \begin_layout Standard
1763 The latter should be the filename as it would be used in a LaTeX's
1770 It is relevant only when exporting files suitable for such inclusion.
1773 \begin_layout Standard
1774 Copiers can be used to do almost anything with output files.
1775 For example, suppose you want generated pdf files to be copied to a special
1777 \begin_inset Flex Code
1780 \begin_layout Plain Layout
1787 Then you could write a shell script such as this one:
1790 \begin_layout Standard
1791 \begin_inset listings
1795 \begin_layout Plain Layout
1800 \begin_layout Plain Layout
1805 \begin_layout Plain Layout
1807 TOFILE=`basename $2`
1810 \begin_layout Plain Layout
1812 cp $FROMFILE /home/you/pdf/$TOFILE
1817 Save it in your local LyX directory—say,
1818 \begin_inset Flex Code
1821 \begin_layout Plain Layout
1822 /home/you/.lyx/scripts/pdfcopier.sh
1827 —and make it executable, if you need to do so on your platform.
1829 \begin_inset Flex MenuItem
1832 \begin_layout Plain Layout
1833 Tools\SpecialChar \menuseparator
1839 dialog, select under
1840 \begin_inset Flex MenuItem
1843 \begin_layout Plain Layout
1844 File Handling\SpecialChar \menuseparator
1851 \begin_inset Flex MenuItem
1854 \begin_layout Plain Layout
1860 format—or one of the other pdf formats—and enter
1861 \begin_inset Flex Code
1864 \begin_layout Plain Layout
1865 pdfcopier.sh $$i $$o
1871 \begin_inset Flex MenuItem
1874 \begin_layout Plain Layout
1884 \begin_layout Standard
1885 Copiers are used by LyX in various of its own conversions.
1886 For example, if appropriate programs are found, LyX will automatically
1887 install copiers for the
1888 \begin_inset Flex MenuItem
1891 \begin_layout Plain Layout
1898 \begin_inset Flex MenuItem
1901 \begin_layout Plain Layout
1903 \begin_inset space ~
1912 When these formats are exported, the copier sees that not just the main
1913 HTML file but various associated files (style files, images, etc.) are also
1915 All these files are written to a subdirectory of the directory in which
1916 the original LyX file was found.
1920 \begin_layout Plain Layout
1921 This copier can be customized.
1923 \begin_inset Quotes eld
1927 \begin_inset Quotes erd
1930 argument takes a comma-separated list of extensions to be copied; if it
1931 is omitted, all files will be copied.
1933 \begin_inset Quotes eld
1937 \begin_inset Quotes erd
1940 argument determines the extension added to the generated directory.
1942 \begin_inset Quotes eld
1946 \begin_inset Flex MenuItem
1949 \begin_layout Plain Layout
1956 \begin_inset Quotes erd
1959 , so HTML generated from
1960 \begin_inset Flex MenuItem
1963 \begin_layout Plain Layout
1964 /path/to/filename.lyx
1970 \begin_inset Flex MenuItem
1973 \begin_layout Plain Layout
1974 /path/to/filename.html.LyXconv
1988 \begin_layout Section
1990 \begin_inset CommandInset label
1992 name "sec:Converters"
1999 \begin_layout Standard
2000 You can define your own Converters to convert files between different formats.
2002 \begin_inset Flex MenuItem
2005 \begin_layout Plain Layout
2006 Tools\SpecialChar \menuseparator
2007 Preferences\SpecialChar \menuseparator
2008 File Handling\SpecialChar \menuseparator
2017 \begin_layout Standard
2018 To define a new converter, select the
2019 \begin_inset Flex MenuItem
2022 \begin_layout Plain Layout
2024 \begin_inset space ~
2033 \begin_inset Flex MenuItem
2036 \begin_layout Plain Layout
2038 \begin_inset space ~
2046 from the drop-down lists, enter the command needed for the conversion,
2048 \begin_inset Flex MenuItem
2051 \begin_layout Plain Layout
2058 Several variables can be used in the definition of converters:
2061 \begin_layout Labeling
2062 \labelwidthstring 00.00.0000
2063 \begin_inset Flex Code
2066 \begin_layout Plain Layout
2072 The LyX system directory
2075 \begin_layout Labeling
2076 \labelwidthstring 00.00.0000
2077 \begin_inset Flex Code
2080 \begin_layout Plain Layout
2089 \begin_layout Labeling
2090 \labelwidthstring 00.00.0000
2091 \begin_inset Flex Code
2094 \begin_layout Plain Layout
2103 \begin_layout Labeling
2104 \labelwidthstring 00.00.0000
2105 \begin_inset Flex Code
2108 \begin_layout Plain Layout
2114 The base filename of the input file (i.
2115 \begin_inset space \thinspace{}
2118 g., without the extension)
2121 \begin_layout Labeling
2122 \labelwidthstring 00.00.0000
2123 \begin_inset Flex Code
2126 \begin_layout Plain Layout
2132 The path to the input file
2135 \begin_layout Labeling
2136 \labelwidthstring 00.00.0000
2137 \begin_inset Flex Code
2140 \begin_layout Plain Layout
2146 The path to the original input file (this is different from $$p when a
2147 chain of converters is called)
2150 \begin_layout Labeling
2151 \labelwidthstring 00.00.0000
2152 \begin_inset Flex Code
2155 \begin_layout Plain Layout
2161 The iconv name for the encoding of the document.
2164 \begin_layout Standard
2166 \begin_inset Flex MenuItem
2169 \begin_layout Plain Layout
2171 \begin_inset space ~
2179 field you can enter the following flags, separated by commas:
2182 \begin_layout Labeling
2183 \labelwidthstring 00.00.0000
2184 \begin_inset Flex Code
2187 \begin_layout Plain Layout
2193 This converter runs some form of LaTeX.
2194 This will make LyX's LaTeX error logs available.
2197 \begin_layout Labeling
2198 \labelwidthstring 00.00.0000
2199 \begin_inset Flex Code
2202 \begin_layout Plain Layout
2209 \begin_inset Flex MenuItem
2212 \begin_layout Plain Layout
2218 file for the conversion.
2221 \begin_layout Labeling
2222 \labelwidthstring 00.00.0000
2223 \begin_inset Flex Code
2226 \begin_layout Plain Layout
2235 \begin_layout Standard
2236 The following three flags are not really flags at all because they take
2238 \begin_inset Flex MenuItem
2241 \begin_layout Plain Layout
2243 \begin_inset space ~
2247 \begin_inset space ~
2258 \begin_layout Labeling
2259 \labelwidthstring 00.00.0000
2260 \begin_inset Flex Code
2263 \begin_layout Plain Layout
2269 If set, the converter's standard error will be redirected to a file
2270 \begin_inset Flex Code
2273 \begin_layout Plain Layout
2279 , and the script given as argument will be run as:
2280 \begin_inset Flex Code
2283 \begin_layout Plain Layout
2284 script < infile.out > infile.log
2290 The argument may contain
2291 \begin_inset Flex Code
2294 \begin_layout Plain Layout
2303 \begin_layout Labeling
2304 \labelwidthstring 00.00.0000
2305 \begin_inset Flex Code
2308 \begin_layout Plain Layout
2314 The name of the directory in which the converter will dump the generated
2316 LyX will not create this directory, and it does not copy anything into
2317 it, though it will copy this directory to the destination.
2318 The argument may contain
2319 \begin_inset Flex Code
2322 \begin_layout Plain Layout
2328 , which will be replaced by the base name of the input and output files,
2329 respectively, when the directory is copied.
2330 \begin_inset Newline newline
2333 Note that resultdir and usetempdir make no sense together.
2334 The latter will be ignored if the former is given.
2337 \begin_layout Labeling
2338 \labelwidthstring 00.00.0000
2339 \begin_inset Flex Code
2342 \begin_layout Plain Layout
2348 Determines the output file name and may, contain
2349 \begin_inset Flex Code
2352 \begin_layout Plain Layout
2359 Sensible only with resultdir and optional even then; if not given, it defaults
2363 \begin_layout Standard
2364 None of these last three are presently used in any of the converters that
2365 are installed with LyX.
2369 \begin_layout Standard
2370 You do not have to define converters for all formats between which you want
2372 For example, you will note that there is no `LyX to PostScript' converter,
2373 but LyX will export PostScript.
2374 It does so by first creating a LaTeX file (no converter needs to be defined
2375 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2376 and finally converting the resulting DVI file to PostScript.
2377 LyX finds such `chains' of converters automatically, and it will always
2378 choose the shortest possible chain.
2379 You can, though, still define multiple conversion methods between file
2381 For example, the standard LyX configuration provides three ways to convert
2382 LaTeX to PDF: Directly, using
2383 \begin_inset Flex MenuItem
2386 \begin_layout Plain Layout
2392 ; via (DVI and) PostScript, using
2393 \begin_inset Flex MenuItem
2396 \begin_layout Plain Layout
2403 \begin_inset Flex MenuItem
2406 \begin_layout Plain Layout
2413 To define such alternate chains, you must define multiple target `file
2414 formats', as described in section
2415 \begin_inset CommandInset ref
2417 reference "sec:Formats"
2422 For example, in the standard configuration, the formats named
2423 \begin_inset Flex MenuItem
2426 \begin_layout Plain Layout
2433 \begin_inset Flex MenuItem
2436 \begin_layout Plain Layout
2443 \begin_inset Flex MenuItem
2446 \begin_layout Plain Layout
2452 are defined, all of which share the extension
2453 \begin_inset Flex MenuItem
2456 \begin_layout Plain Layout
2462 , and which correspond to the conversion methods just mentioned.
2465 \begin_layout Chapter
2466 Internationalizing LyX
2467 \begin_inset CommandInset label
2469 name "cha:Internationalizing-LyX"
2476 \begin_layout Standard
2477 LyX supports using a translated interface.
2478 Last time we checked, LyX provided text in thirty languages.
2479 The language of choice is called your
2484 (For further reading on locale settings, see also the documentation for
2485 locale that comes with your operating system.
2486 For Linux, the manual page for
2487 \begin_inset Flex Code
2490 \begin_layout Plain Layout
2496 could be a good place to start).
2499 \begin_layout Standard
2500 Notice that these translations will work, but do contain a few flaws.
2501 In particular, all dialogs have been designed with the English text in
2502 mind, which means that some of the translated text will be too large to
2503 fit within the space allocated.
2504 This is only a display problem and will not cause any harm.
2505 Also, you will find that some of the translations do not define shortcut
2506 keys for everything.
2507 Sometimes, there are simply not enough free letters to do it.
2508 Other times, the translator just hasn't got around to doing it yet.
2509 Our localization team, which you may wish to join,
2513 \begin_layout Plain Layout
2514 If you are a fluent speaker of a language other than English, joining these
2515 teams is a great way to give back to the LyX community!
2520 will of course try to fix these shortcomings in future versions of LyX.
2523 \begin_layout Section
2527 \begin_layout Subsection
2528 Translating the graphical user interface (text messages).
2531 \begin_layout Standard
2533 \begin_inset Flex Code
2536 \begin_layout Plain Layout
2542 library to handle the internationalization of the interface.
2543 To have LyX speak your favorite language in all menus and dialogs, you
2545 \begin_inset Flex Code
2548 \begin_layout Plain Layout
2554 -file for that language.
2555 When this is available, you'll have to generate a
2556 \begin_inset Flex Code
2559 \begin_layout Plain Layout
2565 -file from it and install the
2566 \begin_inset Flex Code
2569 \begin_layout Plain Layout
2576 The process of doing all of this is explained in the documentation for
2578 \begin_inset Flex Code
2581 \begin_layout Plain Layout
2588 It is possible to do this just for yourself, but if you're going to do
2589 it, you might as well share the results of your labors with the rest of
2591 Send a message to the LyX developers' list for more information about how
2595 \begin_layout Standard
2596 In short, this is what you should do (xx denotes the language code):
2599 \begin_layout Itemize
2600 Check out the LyX source code.
2602 \begin_inset CommandInset href
2604 name "information on the web"
2605 target "http://www.lyx.org/HowToUseSVN"
2612 \begin_layout Itemize
2614 \begin_inset Flex Code
2617 \begin_layout Plain Layout
2623 to the folder of the
2624 \begin_inset Flex Code
2627 \begin_layout Plain Layout
2635 \begin_inset Flex Code
2638 \begin_layout Plain Layout
2646 \begin_inset Flex Code
2649 \begin_layout Plain Layout
2655 doesn't exist anywhere, it can be remade with the console command
2656 \begin_inset Flex Code
2659 \begin_layout Plain Layout
2665 in that directory, or you can use an existing po-file for some other language
2669 \begin_layout Itemize
2671 \begin_inset Flex Code
2674 \begin_layout Plain Layout
2684 \begin_layout Plain Layout
2685 This is just a text file, so it can be edited in any text editor.
2686 But there are also specialized programs that support such editing, such
2691 (for all platforms) or
2700 contains a `mode' for editing
2701 \begin_inset Flex Code
2704 \begin_layout Plain Layout
2715 For some menu- and widget-labels, there are also shortcut keys that should
2717 Those keys are marked after a `|', and should be translated according to
2718 the words and phrases of the language.
2719 You should also fill also out the information at the beginning of the new
2721 \begin_inset Flex Code
2724 \begin_layout Plain Layout
2730 -file with your email-address, etc., so people know where to reach you with
2731 suggestions and entertaining flames.
2734 \begin_layout Standard
2735 If you are just doing this on your own, then:
2738 \begin_layout Itemize
2740 \begin_inset Flex Code
2743 \begin_layout Plain Layout
2750 This can be done with
2751 \begin_inset Flex Code
2754 \begin_layout Plain Layout
2755 msgfmt -o xx.mo < xx.po
2763 \begin_layout Itemize
2765 \begin_inset Flex Code
2768 \begin_layout Plain Layout
2774 -file to your locale-tree, at the correct directory for application messages
2779 xx, and under the name
2780 \begin_inset Flex Code
2783 \begin_layout Plain Layout
2790 \begin_inset space \thinspace{}
2794 \begin_inset space \space{}
2798 \begin_inset Flex Code
2801 \begin_layout Plain Layout
2802 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2812 \begin_layout Standard
2813 As said, however, it would be best if the new
2814 \begin_inset Flex Code
2817 \begin_layout Plain Layout
2823 -file could be added to the LyX distribution, so others can use it.
2824 Adding it involves making additional changes to LyX.
2825 So send an email to the developers' mailing list if you're interested in
2829 \begin_layout Subsubsection
2833 \begin_layout Standard
2834 Sometimes it turns out that one English message needs to be translated into
2835 different messages in the target language.
2836 One example is the message
2837 \begin_inset Flex Code
2840 \begin_layout Plain Layout
2846 which has the German translation
2854 , depending upon exactly what the English
2855 \begin_inset Quotes eld
2859 \begin_inset Quotes erd
2864 \begin_inset Flex Code
2867 \begin_layout Plain Layout
2873 does not handle such ambiguous translations.
2874 Therefore you have to add some context information to the message: Instead
2876 \begin_inset Flex Code
2879 \begin_layout Plain Layout
2886 \begin_inset Flex Code
2889 \begin_layout Plain Layout
2890 To[[as in 'From format x to format y']]
2896 \begin_inset Flex Code
2899 \begin_layout Plain Layout
2900 To[[as in 'From page x to page y']].
2905 Now the two occurrences of
2906 \begin_inset Flex Code
2909 \begin_layout Plain Layout
2916 \begin_inset Flex Code
2919 \begin_layout Plain Layout
2925 and can be translated correctly to
2936 \begin_layout Standard
2937 Of course the context information needs to be stripped off the original
2938 message when no translation is used.
2939 Therefore you have to put it in double square brackets at the end of the
2940 message (see the example above).
2941 The translation mechanism of LyX ensures that everything in double square
2942 brackets at the end of messages is removed before displaying the message.
2945 \begin_layout Subsection
2946 Translating the documentation.
2949 \begin_layout Standard
2950 The online documentation (in the
2951 \begin_inset Flex MenuItem
2954 \begin_layout Plain Layout
2960 -menu) can (and should!) be translated.
2961 If there are translated versions of the documentation available
2965 \begin_layout Plain Layout
2966 As of March 2008, at least some of the documents have been translated into
2967 fourteen languages, with the Tutorial available in a few more.
2972 and the locale is set accordingly, these will be used automagically by
2974 LyX looks for translated versions as
2975 \begin_inset Flex Code
2978 \begin_layout Plain Layout
2979 LyXDir/doc/xx/DocName.lyx
2985 \begin_inset Flex Code
2988 \begin_layout Plain Layout
2994 is the code for the language currently in use.
2995 If there are no translated documents, the default English versions will
2997 Note that the translated versions must have the same filenames (
2998 \begin_inset Flex Code
3001 \begin_layout Plain Layout
3007 above) as the original.
3008 If you feel up to translating the documentation (an excellent way to proof-read
3009 the original documentation by the way!), there are a few things you should
3013 \begin_layout Itemize
3014 Check out the documentation translation web page at
3015 \begin_inset CommandInset href
3017 name "http://www.lyx.org/Translation"
3018 target "http://www.lyx.org/Translation"
3023 That way, you can find out which (if any) documents have already been translate
3024 d into your language.
3025 You can also find out who (if anyone) is organizing the effort to translate
3026 the documentation into your language.
3027 If no one is organizing the effort, please let us know that you're interested.
3030 \begin_layout Standard
3031 Once you get to actually translating, here's a few hints for you that may
3035 \begin_layout Itemize
3036 Join the documentation team! There is information on how to do that in
3037 \begin_inset Flex Code
3040 \begin_layout Plain Layout
3047 \begin_inset Flex MenuItem
3050 \begin_layout Plain Layout
3051 Help\SpecialChar \menuseparator
3057 ), which by the way is the first document you should translate.
3060 \begin_layout Itemize
3061 Learn the typographic conventions for the language you are translating to.
3062 Typography is an ancient art and over the centuries, a great variety of
3063 conventions have developed throughout different parts of the world.
3064 Also study the professional terminology amongst typographers in your country.
3065 Inventing your own terminology will only confuse the users.
3068 (Warning! Typography is addictive!)
3071 \begin_layout Itemize
3072 Make a copy of the document.
3073 This will be your working copy.
3074 You can use this as your personal translated help-file by placing it in
3076 \begin_inset Flex Code
3079 \begin_layout Plain Layout
3088 \begin_layout Itemize
3089 Sometimes the original document (from the LyX-team) will be updated.
3090 Use the source viewer at
3091 \begin_inset CommandInset href
3093 name "http://www.lyx.org/trac/timeline"
3094 target "http://www.lyx.org/trac/timeline"
3098 to see what has been changed.
3099 That way you can easily see which parts of the translated document need
3103 \begin_layout Standard
3104 If you ever find an error in the original document, fix it and notify the
3105 rest of the documentation team of the changes! (You didn't forget to join
3106 the documentation team, did you?)
3109 \begin_layout Standard
3110 \begin_inset Branch OutDated
3113 \begin_layout Section
3114 International Keyboard Support
3117 \begin_layout Standard
3120 [Editor's Note: The following section is by
3128 It needs to be fixed to conform to the new Documentation Style sheet and
3129 to make use of the new v1.0 features.
3130 The whole thing also needs to be merged with the section following it.-jw
3131 It may also be badly out of date.-rh (2008)]
3134 \begin_layout Subsection
3135 Defining Own Keymaps: Keymap File Format
3138 \begin_layout Standard
3139 Let's look at a keyboard definition file a little closer.
3140 It is a plain text file defining
3143 \begin_layout Itemize
3144 key-to-key or key-to-string translations
3147 \begin_layout Itemize
3151 \begin_layout Itemize
3152 dead keys exceptions
3155 \begin_layout Standard
3156 To define key-to-key or key-to-string translation, use this command:
3159 \begin_layout Quotation
3160 \begin_inset Flex Code
3163 \begin_layout Plain Layout
3172 \begin_inset Flex Code
3175 \begin_layout Plain Layout
3184 \begin_layout Standard
3186 \begin_inset Flex Code
3189 \begin_layout Plain Layout
3195 is the key to be translated and
3196 \begin_inset Flex Code
3199 \begin_layout Plain Layout
3205 is the string to be inserted into the document.
3206 To define dead keys, use:
3209 \begin_layout Quotation
3210 \begin_inset Flex Code
3213 \begin_layout Plain Layout
3222 \begin_inset Flex Code
3225 \begin_layout Plain Layout
3234 \begin_layout Standard
3236 \begin_inset Flex Code
3239 \begin_layout Plain Layout
3245 is a keyboard key and
3246 \begin_inset Flex Code
3249 \begin_layout Plain Layout
3256 The following dead keys are supported (shortcut name is in parentheses):
3259 \begin_layout Quotation
3263 \begin_inset space \hfill{}
3269 \begin_layout Quotation
3271 \begin_inset space \hfill{}
3277 \begin_layout Quotation
3279 \begin_inset space \hfill{}
3285 \begin_layout Quotation
3287 \begin_inset space \hfill{}
3293 \begin_layout Quotation
3295 \begin_inset space \hfill{}
3301 \begin_layout Quotation
3303 \begin_inset space \hfill{}
3310 \begin_layout Plain Layout
3322 \begin_layout Quotation
3324 \begin_inset space \hfill{}
3330 \begin_layout Quotation
3332 \begin_inset space \hfill{}
3339 \begin_layout Plain Layout
3351 \begin_layout Quotation
3353 \begin_inset space \hfill{}
3359 \begin_layout Quotation
3361 \begin_inset space \hfill{}
3367 \begin_layout Quotation
3369 \begin_inset space \hfill{}
3376 \begin_layout Plain Layout
3388 \begin_layout Quotation
3390 \begin_inset space \hfill{}
3397 \begin_layout Plain Layout
3409 \begin_layout Quotation
3411 \begin_inset space \hfill{}
3417 \begin_layout Quotation
3418 hungarian umlaut (hug)
3419 \begin_inset space \hfill{}
3425 \begin_layout Quotation
3427 \begin_inset space \hfill{}
3433 \begin_layout Quotation
3435 \begin_inset space \hfill{}
3442 \begin_layout Plain Layout
3454 \begin_layout Standard
3455 Since in many international keyboards there are exceptions to what some
3456 dead keys should do, you can define them using
3459 \begin_layout Quotation
3460 \begin_inset Flex Code
3463 \begin_layout Plain Layout
3471 deadkey key outstring
3474 \begin_layout Standard
3475 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3479 \begin_layout Quotation
3480 \begin_inset Flex Code
3483 \begin_layout Plain Layout
3496 \begin_layout Standard
3497 to make it work correctly.
3498 Also, you have to define as exceptions dead keys over i and j, to remove
3499 the dot from them before inserting an accent mark.
3500 I will change this when the time comes, but so far I haven't had time.
3503 \begin_layout Standard
3504 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3507 \begin_inset Flex Code
3510 \begin_layout Plain Layout
3516 have different meaning.
3518 \begin_inset Flex Code
3521 \begin_layout Plain Layout
3527 marks comments, quotes start and end LaTeX-style commands.
3528 To enter quote, you'll need to use
3529 \begin_inset Flex Code
3532 \begin_layout Plain Layout
3541 \begin_inset Flex Code
3544 \begin_layout Plain Layout
3551 \begin_inset Flex Code
3554 \begin_layout Plain Layout
3565 \begin_layout Standard
3566 If you make a keyboard description file that works for your language, please
3567 mail it to me, so I can include it in the next keymap distribution.
3570 \begin_layout Standard
3571 More keywords will be supported in keymap configuration file in future,
3575 \begin_layout Itemize
3576 \begin_inset Flex Code
3579 \begin_layout Plain Layout
3590 \begin_inset space \hfill{}
3594 \begin_inset Flex Code
3597 \begin_layout Plain Layout
3606 \begin_layout Itemize
3607 \begin_inset Flex Code
3610 \begin_layout Plain Layout
3621 \begin_inset space \hfill{}
3625 \begin_inset Flex Code
3628 \begin_layout Plain Layout
3634 an external keymap translation program
3637 \begin_layout Standard
3638 Also, it should look into
3639 \begin_inset Flex Code
3642 \begin_layout Plain Layout
3648 file for defaults, too (for example, a
3649 \begin_inset Flex Code
3652 \begin_layout Plain Layout
3660 option to include default keyboard).
3668 \begin_layout Section
3669 International Keymap Stuff
3670 \begin_inset CommandInset label
3672 name "sec:International-Keymap-Stuff"
3679 \begin_layout Standard
3680 \begin_inset Note Note
3683 \begin_layout Plain Layout
3684 In doing the revisions on this document in March 2008, I did not look over
3685 this stuff, as I do not understand it.
3686 It would be good if someone else could do so.
3695 \begin_layout Standard
3696 The next two sections describe the
3697 \begin_inset Flex Code
3700 \begin_layout Plain Layout
3709 \begin_inset Flex Code
3712 \begin_layout Plain Layout
3720 file syntax in detail.
3721 These sections should help you design your own key map if the ones provided
3722 do not meet your needs.
3725 \begin_layout Subsection
3729 \begin_layout Standard
3733 \begin_inset Flex Code
3736 \begin_layout Plain Layout
3742 file maps keystrokes to characters or strings.
3743 As the name suggests, it sets a keyboard mapping.
3745 \begin_inset Flex Code
3748 \begin_layout Plain Layout
3759 \begin_inset Flex Code
3762 \begin_layout Plain Layout
3777 \begin_inset Flex Code
3780 \begin_layout Plain Layout
3793 \begin_inset Flex Code
3796 \begin_layout Plain Layout
3805 \begin_inset Flex Code
3808 \begin_layout Plain Layout
3816 are described in this section.
3819 \begin_layout Labeling
3820 \labelwidthstring 00.00.0000
3821 \begin_inset Flex Code
3824 \begin_layout Plain Layout
3832 Map a character to a string
3835 \begin_layout LyX-Code
3850 \begin_layout Standard
3883 the double-quote (")
3900 must be escaped with a preceding backslash (
3911 \begin_layout Standard
3913 \begin_inset Flex MenuItem
3916 \begin_layout Plain Layout
3924 statement to cause the symbol
3925 \begin_inset Flex MenuItem
3928 \begin_layout Plain Layout
3936 to be output for the keystroke
3937 \begin_inset Flex MenuItem
3940 \begin_layout Plain Layout
3951 \begin_layout LyX-Code
3957 \begin_layout Labeling
3958 \labelwidthstring 00.00.0000
3959 \begin_inset Flex Code
3962 \begin_layout Plain Layout
3970 Specify an accent character
3973 \begin_layout LyX-Code
3982 \begin_layout Standard
3983 This will make the cha
4021 This is the dead key
4025 \begin_layout Plain Layout
4032 refers to a key that does not produce a character by itself, but when followed
4033 with another key, produces the desired accent character.
4034 For example, a German characte
4036 r with an umlaut like
4046 can be produced in this manner.
4055 \begin_layout Standard
4068 and then another key not in
4085 followed by the other, not allowed key, as output.
4089 \begin_inset Flex MenuItem
4092 \begin_layout Plain Layout
4100 cancels a dead key, so if
4111 \begin_inset Flex MenuItem
4114 \begin_layout Plain Layout
4123 , the cursor will not go one position backwards but will instead cancel
4139 might have had on the next keystroke.
4143 \begin_layout Standard
4144 The following example specifies that the character ' is to be an acute accent,
4145 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4148 \begin_layout LyX-Code
4151 kmod ' acute aeiouAEIOU
4154 \begin_layout Labeling
4155 \labelwidthstring 00.00.0000
4156 \begin_inset Flex Code
4159 \begin_layout Plain Layout
4165 Specify an exception to the accent character
4168 \begin_layout LyX-Code
4177 \begin_layout Standard
4178 This defines an exce
4219 have been assigned a keystroke with a previous
4222 \begin_inset Flex Code
4225 \begin_layout Plain Layout
4249 must not belong in the
4296 If such a declaration does not exist in
4304 \begin_inset Flex Code
4307 \begin_layout Plain Layout
4341 \begin_inset Flex Code
4344 \begin_layout Plain Layout
4358 \begin_layout Standard
4359 The following command produces causes äi to be produced when you enter acute-i
4363 \begin_layout LyX-Code
4377 \begin_layout Labeling
4378 \labelwidthstring 00.00.0000
4379 \begin_inset Flex Code
4382 \begin_layout Plain Layout
4388 Combine two accent characters
4391 \begin_layout LyX-Code
4397 accent1 accent2 allowed
4400 \begin_layout Standard
4401 This one is getting pretty esoteric.
4402 It allows you to combine the effect
4458 \begin_inset Flex Code
4461 \begin_layout Plain Layout
4489 \begin_layout Standard
4490 Consider this example from the
4491 \begin_inset Flex Code
4494 \begin_layout Plain Layout
4505 \begin_layout LyX-Code
4508 kmod ; acute aeioyvhAEIOYVH
4512 kcomb acute umlaut iyIY
4515 \begin_layout Standard
4516 This allows you to press
4517 \begin_inset Flex MenuItem
4520 \begin_layout Plain Layout
4528 and get the effect of
4529 \begin_inset Flex Code
4532 \begin_layout Plain Layout
4551 in this case cancels the last dead key, so if you press
4552 \begin_inset Flex MenuItem
4555 \begin_layout Plain Layout
4564 \begin_inset Flex Code
4567 \begin_layout Plain Layout
4580 \begin_layout Subsection
4584 \begin_layout Standard
4586 \begin_inset Flex Code
4589 \begin_layout Plain Layout
4597 mapping is performed, a
4598 \begin_inset Flex Code
4601 \begin_layout Plain Layout
4611 file maps the strings that the symbols generate to characters in the current
4613 The LyX distribution currently includes at least the
4614 \begin_inset Flex Code
4617 \begin_layout Plain Layout
4626 \begin_inset Flex Code
4629 \begin_layout Plain Layout
4640 \begin_layout Standard
4642 \begin_inset Flex Code
4645 \begin_layout Plain Layout
4653 file is a sequence of declarations of the form
4656 \begin_layout LyX-Code
4669 \begin_layout Standard
4670 For example, in order to map
4671 \begin_inset Flex MenuItem
4674 \begin_layout Plain Layout
4684 to the corresponding character in the iso-8859-1 set (233), the following
4688 \begin_layout LyX-Code
4696 \begin_layout Standard
4698 \begin_inset Flex Code
4701 \begin_layout Plain Layout
4710 \begin_inset Flex Code
4713 \begin_layout Plain Layout
4731 the same character can apply to more than one string.
4733 \begin_inset Flex Code
4736 \begin_layout Plain Layout
4747 \begin_layout LyX-Code
4759 \begin_inset Newline newline
4775 \begin_layout Standard
4776 If LyX cannot find a mapping for the string produced by the keystroke or
4777 a deadkey sequence, it will check if it looks like an accented char and
4778 try to draw an accent over the character on screen.
4781 \begin_layout Subsection
4785 \begin_layout Standard
4786 There is a second way to add support for international characters through
4787 so-called dead-keys.
4788 A dead-key works in combination with a letter to produce an accented character.
4789 Here, we'll explain how to create a really simple dead-key to illustrate
4793 \begin_layout Standard
4794 Suppose you happen to need the circumflex character,
4795 \begin_inset Quotes eld
4799 \begin_inset Quotes erd
4804 \begin_inset Flex MenuItem
4807 \begin_layout Plain Layout
4814 \begin_inset space ~
4818 \begin_inset Flex MenuItem
4821 \begin_layout Plain Layout
4827 ] to the LyX command
4828 \begin_inset Flex Code
4831 \begin_layout Plain Layout
4838 \begin_inset Flex Code
4841 \begin_layout Plain Layout
4848 Now, whenever you type the
4849 \begin_inset Flex MenuItem
4852 \begin_layout Plain Layout
4858 -key followed by a letter, that letter will have a circumflex accent on
4860 For example, the sequence
4861 \begin_inset Quotes eld
4865 \begin_inset Flex MenuItem
4868 \begin_layout Plain Layout
4875 \begin_inset Quotes erd
4878 produces the letter:
4879 \begin_inset Quotes eld
4883 \begin_inset Quotes erd
4887 If you tried to type
4888 \begin_inset Quotes eld
4892 \begin_inset Flex MenuItem
4895 \begin_layout Plain Layout
4902 \begin_inset Quotes erd
4905 , however, LyX will complain with a beep, since a
4906 \begin_inset Quotes eld
4910 \begin_inset Flex MenuItem
4913 \begin_layout Plain Layout
4920 \begin_inset Quotes erd
4923 never takes a circumflex accent.
4925 \begin_inset Flex MenuItem
4928 \begin_layout Plain Layout
4934 after a dead-key produces the bare-accent.
4935 Please note this last point! If you bind a key to a dead-key, you'll need
4936 to rebind the character on that key to yet another key.
4938 \begin_inset Flex MenuItem
4941 \begin_layout Plain Layout
4947 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
4950 \begin_layout Standard
4951 One common way to bind dead-keys is to use
4952 \begin_inset Flex MenuItem
4955 \begin_layout Plain Layout
4962 \begin_inset Flex MenuItem
4965 \begin_layout Plain Layout
4972 \begin_inset Flex MenuItem
4975 \begin_layout Plain Layout
4981 in combination with an accent, like
4982 \begin_inset Quotes eld
4986 \begin_inset Flex MenuItem
4989 \begin_layout Plain Layout
4996 \begin_inset Quotes erd
5000 \begin_inset Quotes eld
5004 \begin_inset Flex MenuItem
5007 \begin_layout Plain Layout
5014 \begin_inset Quotes erd
5018 \begin_inset Quotes eld
5022 \begin_inset Flex MenuItem
5025 \begin_layout Plain Layout
5032 \begin_inset Quotes erd
5036 Another way involves using
5037 \begin_inset Flex Code
5040 \begin_layout Plain Layout
5047 \begin_inset Flex Code
5050 \begin_layout Plain Layout
5056 to set up the special
5057 \begin_inset Flex Code
5060 \begin_layout Plain Layout
5068 \begin_inset Flex Code
5071 \begin_layout Plain Layout
5077 acts in some ways just like
5078 \begin_inset Flex MenuItem
5081 \begin_layout Plain Layout
5087 and permits you to bind keys to accented characters.
5088 You can also turn keys into dead-keys by binding them to something like
5090 \begin_inset Flex Code
5093 \begin_layout Plain Layout
5099 and then binding this symbolic key to the corresponding LyX command.
5103 \begin_layout Plain Layout
5108 : This is exactly what I do in my
5109 \begin_inset Flex Code
5112 \begin_layout Plain Layout
5119 \begin_inset Flex Code
5122 \begin_layout Plain Layout
5130 \begin_inset Flex MenuItem
5133 \begin_layout Plain Layout
5135 \begin_inset space ~
5144 \begin_inset Flex Code
5147 \begin_layout Plain Layout
5153 and a bunch of these
5154 \begin_inset Quotes eld
5158 \begin_inset Flex Code
5161 \begin_layout Plain Layout
5168 \begin_inset Quotes erd
5171 symbolic keys bound such things as
5172 \begin_inset Flex MenuItem
5175 \begin_layout Plain Layout
5177 \begin_inset space ~
5186 \begin_inset Flex MenuItem
5189 \begin_layout Plain Layout
5191 \begin_inset space ~
5200 This is how I produce my accented characters.
5205 You can make just about anything into the
5206 \begin_inset Flex Code
5209 \begin_layout Plain Layout
5216 \begin_inset Flex MenuItem
5219 \begin_layout Plain Layout
5225 keys, a spare function key, etc.
5226 As for the LyX commands that produce accents, check the entry for
5227 \begin_inset Flex Code
5230 \begin_layout Plain Layout
5241 You'll find the complete list there.
5244 \begin_layout Subsection
5245 Saving your Language Configuration
5248 \begin_layout Standard
5249 You can edit your preferences so that your desired language environment
5250 is automatically configured when LyX starts up, via the
5251 \begin_inset Flex MenuItem
5254 \begin_layout Plain Layout
5255 Edit\SpecialChar \menuseparator
5264 \begin_layout Chapter
5265 Installing New Document Classes, Layouts, and Templates
5266 \begin_inset CommandInset label
5268 name "cha:Installing-New-Document"
5273 \begin_inset Argument
5276 \begin_layout Plain Layout
5277 Installing New Document Classes
5285 \begin_layout Standard
5286 In this chapter, we describe the procedures for creating and installing
5287 new LyX layout and template files, as well as offer a refresher on correctly
5288 installing new LaTeX document classes.
5292 \begin_layout Standard
5293 First, let us a say a few words about how one ought to think about the relation
5294 between LyX and LaTeX.
5295 The thing to understand is that, in a certain sense, LyX doesn't know anything
5297 Indeed, from LyX's point of view, LaTeX is just one of several
5298 \begin_inset Quotes eld
5302 \begin_inset Quotes erd
5305 in which it is capable of producing output.
5306 Other such formats are DocBook, plaintext, and XHTML.
5307 LaTeX is, of course, a particularly important format, but very little of
5308 the information LyX has about LaTeX is actually contained in the program
5313 \begin_layout Plain Layout
5314 Some commands are sufficiently complex that they are
5315 \begin_inset Quotes eld
5319 \begin_inset Quotes erd
5323 But the developers generally regard this as a Bad Thing.
5328 Rather, that information, even for the standard classes like
5329 \begin_inset Flex Code
5332 \begin_layout Plain Layout
5338 , is contained in `layout files'.
5339 Similarly, LyX itself does not know much about DocBook or XHTML.
5340 What it knows is contained in layout files.
5343 \begin_layout Standard
5344 You can think of the layout file for a given document class as a translation
5345 manual between LyX constructs---paragraphs with their corresponding styles,
5346 certain sorts of insets, etc---and the corresponding LaTeX, DocBook, or
5348 Almost everything LyX knows about
5349 \begin_inset Flex Code
5352 \begin_layout Plain Layout
5358 , for example, is contained in the file
5359 \begin_inset Flex Code
5362 \begin_layout Plain Layout
5368 and in various other files it includes.
5369 For this reason, anyone intending to write layout files should plan to
5370 study the existing files.
5371 A good place to start is with
5372 \begin_inset Flex Code
5375 \begin_layout Plain Layout
5381 , which is included in
5382 \begin_inset Flex Code
5385 \begin_layout Plain Layout
5392 \begin_inset Flex Code
5395 \begin_layout Plain Layout
5401 , and many of the other layout files for document classes.
5402 This file is where sections and the like are defined:
5403 \begin_inset Flex Code
5406 \begin_layout Plain Layout
5412 tells LyX how paragraphs that are marked with the Section, Subsection,
5413 etc, styles can be translated into corresponding LaTeX, DocBook, and XHTML
5416 \begin_inset Flex Code
5419 \begin_layout Plain Layout
5425 file basically just includes several of these
5426 \begin_inset Flex Code
5429 \begin_layout Plain Layout
5438 \begin_layout Standard
5439 Defining the LyX--LaTeX correspondence is not the only thing layout files
5441 Their other job is to define how the LyX constructs themselves will appear
5443 The fact that layout files have these two jobs is often a source of confusion,
5444 because they are completely separate.
5445 Telling LyX how to translate a certain paragraph style into LaTeX does
5446 not tell LyX how to display it; conversely, telling LyX how to display
5447 a certain paragraph style does not tell LyX how to translate it into LaTeX
5448 (let alone tell LaTeX how to display it).
5449 So, in general, when you define a new LyX construct, you must always do
5450 two quite separate things: (i)
5451 \begin_inset space ~
5454 tell LyX how to translate it into LaTeX and (ii)
5455 \begin_inset space ~
5458 tell LyX how to display it.
5461 \begin_layout Standard
5462 Much the same is true, of course, as regards LyX's other backend formats,
5463 though XHTML is in some ways different, because in that case LyX
5467 able, to some extent, to use information about how it should display a
5468 paragraph on the screen to output information (in the form of CSS) about
5469 how the paragraph should be displayed in a browser.
5470 Even in this case, however, the distinction between what LyX does internally
5471 and how things are rendered externally remains in force, and the two can
5472 be controlled separately.
5474 \begin_inset CommandInset ref
5476 reference "sec:Tags-for-XHTML"
5483 \begin_layout Section
5484 Installing new LaTeX files
5487 \begin_layout Standard
5488 Some installations may not include a LaTeX package or class file that you
5489 would like to use within LyX.
5490 For example, you might need FoilTeX, a package for preparing slides for
5491 overhead projectors.
5492 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5493 a user interface for installing such packages.
5494 For example, with MiKTeX, you start the program
5495 \begin_inset Quotes eld
5499 \begin_inset space ~
5503 \begin_inset Quotes erd
5506 to get a list of available packages.
5507 To install one of them, right click on it or use the corresponding toolbar
5511 \begin_layout Standard
5512 If your LaTeX distribution does not provide such a `package manager', or
5513 if the package is not available from your distribution, then follow these
5514 steps to install it manually:
5517 \begin_layout Enumerate
5518 Get the package from
5519 \begin_inset CommandInset href
5522 target "http://www.ctan.org/"
5529 \begin_layout Enumerate
5530 If the package contains a file with the ending
5531 \begin_inset Quotes eld
5535 \begin_inset Flex Code
5538 \begin_layout Plain Layout
5545 \begin_inset Quotes erd
5548 (is the case for FoilTeX) then open a console, change to the folder of
5549 this file and execute the command
5550 \begin_inset Flex Code
5553 \begin_layout Plain Layout
5560 You have now unpacked the package and have all files to install it.
5561 Most LaTeX-packages are not packed and you can skip this step.
5564 \begin_layout Enumerate
5565 Now you need to decide if the package should be available for all users
5570 \begin_layout Enumerate
5571 On *nix systems (Linux, OSX, etc.), if you want the new package to be available
5572 for all users on your system, then install it in your `local' TeX tree,
5573 otherwise install it in your own `user' TeX tree.
5574 Where these trees should be created, if they do not already exist, depends
5576 To find this out, look in the file
5577 \begin_inset Flex Code
5580 \begin_layout Plain Layout
5590 \begin_layout Plain Layout
5591 This is usually in the directory
5592 \begin_inset Flex Code
5595 \begin_layout Plain Layout
5601 , though you can execute the command
5602 \begin_inset Flex Code
5605 \begin_layout Plain Layout
5616 The location of the `local' TeX tree is defined by the
5617 \begin_inset Flex Code
5620 \begin_layout Plain Layout
5626 variable; this is usually somewhere like
5627 \begin_inset Flex Code
5630 \begin_layout Plain Layout
5631 /usr/local/share/texmf
5637 The location of the `user' TeX tree is defined by
5638 \begin_inset Flex Code
5641 \begin_layout Plain Layout
5648 \begin_inset Flex Code
5651 \begin_layout Plain Layout
5658 (If these variables are not predefined, you have to define them.) You'll
5659 probably need root permissions to create or modify the `local' tree, but
5660 not for your `user' tree.
5661 \begin_inset Newline newline
5664 In general, it is recommended to install in the user tree because your user
5665 will not be modified or even overwritten when you upgrade your system.
5666 It will typically also be backed up together with everything else when
5667 you backup your home directory (which, of course, you do on a regular basis).
5670 \begin_layout Enumerate
5671 On Windows, if you want the new package to be available for all users on
5672 your system, change to the folder where LaTeX is installed and then change
5674 \begin_inset Flex Code
5677 \begin_layout Plain Layout
5688 (For MiKTeX, this would be by default the folder
5689 \begin_inset Flex Code
5692 \begin_layout Plain Layout
5710 \begin_layout Plain Layout
5711 Note that this will be the correct path only on English installations.
5712 On a German one, it would be
5713 \begin_inset Flex Code
5716 \begin_layout Plain Layout
5730 , and similarly for other languages.
5735 Create there a new folder
5736 \begin_inset Flex Code
5739 \begin_layout Plain Layout
5745 and copy all files of the package into it.
5747 \begin_inset Newline newline
5750 If the package should only available for you or you don't have admin permissions
5751 , do the same, but in the local LaTeX folder.
5753 \begin_inset space \thinspace{}
5757 \begin_inset space ~
5760 2.8 under Windows XP, this would be the folder:
5761 \begin_inset Newline newline
5767 \begin_inset Flex Code
5770 \begin_layout Plain Layout
5773 Documents and Settings
5785 \begin_inset Newline newline
5791 \begin_inset Phantom HPhantom
5794 \begin_layout Plain Layout
5805 \begin_inset Flex Code
5808 \begin_layout Plain Layout
5821 \begin_inset Newline newline
5824 On Vista, it would be:
5825 \begin_inset Newline newline
5829 \begin_inset Flex Code
5832 \begin_layout Plain Layout
5858 \begin_layout Enumerate
5859 Now one only need to tell LaTeX that there are new files.
5860 This depends on the used LaTeX-Distribution:
5864 \begin_layout Enumerate
5865 For TeXLive execute the command
5866 \begin_inset Flex Code
5869 \begin_layout Plain Layout
5876 If you installed the package for all users, then you will probably need
5877 to have root permissions for that.
5880 \begin_layout Enumerate
5881 For MiKTeX, if you have installed the package for all users, start the program
5883 \begin_inset Quotes eld
5887 \begin_inset space ~
5891 \begin_inset Quotes erd
5894 and press the button marked
5895 \begin_inset Quotes eld
5899 \begin_inset Quotes erd
5903 Otherwise start the program
5904 \begin_inset Quotes eld
5908 \begin_inset Quotes erd
5915 \begin_layout Enumerate
5916 Finally, you need to tell LyX that there are new packages available.
5917 So, in LyX, use the menu
5918 \begin_inset Flex MenuItem
5921 \begin_layout Plain Layout
5924 \SpecialChar \menuseparator
5930 and then restart LyX.
5933 \begin_layout Standard
5934 Now the package is installed.
5935 In our example, the document class
5936 \begin_inset Flex Code
5939 \begin_layout Plain Layout
5941 \begin_inset space ~
5948 \begin_layout Plain Layout
5960 will now be available under
5961 \begin_inset Flex MenuItem
5964 \begin_layout Plain Layout
5965 Document\SpecialChar \menuseparator
5966 Settings\SpecialChar \menuseparator
5976 \begin_layout Standard
5977 If you would like to use a LaTeX document class that is not even listed
5979 \begin_inset Flex MenuItem
5982 \begin_layout Plain Layout
5983 Document\SpecialChar \menuseparator
5984 Settings\SpecialChar \menuseparator
5990 , then you need to create a `layout' file for it.
5991 That is the topic of the next section.
5994 \begin_layout Section
5995 Types of layout files
5998 \begin_layout Standard
5999 This section describes the various sorts of LyX files that contain layout
6001 These files describe various paragraph and character styles, determining
6002 how LyX should display them and how they should be translated into LaTeX,
6003 DocBook, XHTML, or whatever output format is being used.
6007 \begin_layout Standard
6008 We shall try to provide a thorough description of the process of writing
6010 However, there are so many different types of documents supported even
6011 by just LaTeX that we can't hope to cover every different possibility or
6012 problem you might encounter.
6013 The LyX users' list is frequented by people with lots of experience with
6014 layout design who are willing to share what they've learned, so please
6015 feel free to ask questions there.
6018 \begin_layout Standard
6019 As you prepare to write a new layout, it is extremely helpful to look at
6020 the layouts distributed with LyX.
6021 If you write a LyX layout for a LaTeX document class that might also be
6022 used by others, or write a module that might be useful to others, then
6023 you should consider posting your layout to the
6024 \begin_inset CommandInset href
6026 name "layout section on the LyX wiki"
6027 target "http://wiki.lyx.org/Layouts/Layouts"
6031 or even to the LyX developers' list, so that it might be included in LyX
6036 \begin_layout Plain Layout
6037 Note that LyX is licensed under the General Public License, so any material
6038 that is contributed to LyX must be similarly licensed.
6046 \begin_layout Subsection
6048 \begin_inset CommandInset label
6050 name "sub:Layout-modules"
6057 \begin_layout Standard
6058 We have spoken to this point about `layout files'.
6059 But there are different sorts of files that contain layout information.
6060 Layout files, strictly so called, have the
6061 \begin_inset Flex Code
6064 \begin_layout Plain Layout
6070 extension and provide LyX with information about document classes.
6071 As of LyX 1.6, however, layout information can also be contained in layout
6077 \begin_inset Flex Code
6080 \begin_layout Plain Layout
6087 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6088 some modules—such as the
6089 \begin_inset Flex Code
6092 \begin_layout Plain Layout
6098 module—specifically provide support for one package.
6099 In a sense, layout modules are similar to included
6103 \begin_layout Plain Layout
6104 These can have any extension, but by convention have the
6105 \begin_inset Flex Code
6108 \begin_layout Plain Layout
6120 \begin_inset Flex Code
6123 \begin_layout Plain Layout
6129 —in that modules are not specific to a given document class but may be used
6130 with many different classes.
6131 The difference is that using an included file with
6132 \begin_inset Flex Code
6135 \begin_layout Plain Layout
6141 requires editing that file.
6142 Modules, by contrast, are selected in the
6143 \begin_inset Flex MenuItem
6146 \begin_layout Plain Layout
6147 Document\SpecialChar \menuseparator
6156 \begin_layout Standard
6157 Building modules is the easiest way to get started with layout editing,
6158 since it can be as simple as adding a single new paragraph style or flex
6160 But modules may, in principle, contain anything a layout file can contain.
6163 \begin_layout Standard
6164 After creating a new module and copying it to the
6165 \begin_inset Flex Code
6168 \begin_layout Plain Layout
6174 folder, you will need to reconfigure and then restart LyX for the module
6175 to appear in the menu.
6176 However, changes you make to the module will be seen immediately, if you
6178 \begin_inset Flex MenuItem
6181 \begin_layout Plain Layout
6182 Document\SpecialChar \menuseparator
6188 , highlight something, and then hit
6189 \begin_inset Quotes eld
6193 \begin_inset Quotes erd
6199 It is strongly recommended that you save your work before doing this
6204 it is strongly recommended that you not attempt to edit modules while simultaneo
6205 usly working on actual documents
6208 Though of course the developers strive to keep LyX stable in such situations,
6209 syntax errors and the like in your module file could cause strange behavior.
6210 \change_inserted 1414654397 1302962370
6214 \begin_layout Subsubsection
6216 \change_inserted 1414654397 1302962375
6220 \begin_layout Standard
6222 \change_inserted 1414654397 1302962524
6223 Modules are to LyX as packages are to LaTeX.
6224 Sometimes, however, you find yourself wanting a specific inset or character
6225 style just for one document and writing a module that will also be available
6226 to other documents makes little sense.
6227 What you need is LyX's
6228 \begin_inset Quotes eld
6232 \begin_inset Quotes erd
6238 \begin_layout Standard
6240 \change_inserted 1414654397 1302963263
6241 You will find it under
6243 Document\SpecialChar \menuseparator
6244 Settings\SpecialChar \menuseparator
6248 The large text box allows you to enter anything that you might enter in
6249 a layout file or module.
6250 You can think of a document's local layout, in fact, as a module that belongs
6252 So, in particular, you must enter a
6253 \begin_inset Flex Code
6256 \begin_layout Plain Layout
6258 \change_inserted 1414654397 1302962556
6267 Any format is acceptable, but one would normally use the format current
6269 (In LyX 2.0, the current layout format is 35.) You should be aware that local
6270 layout is not supported by versions of LyX prior to 1.6, so you should not
6271 use it if you want to be able to export your document to LyX 1.5 or earlier
6272 (without, that is, losing the local layout information).
6273 If you wish to be able to export to 1.6---local layout is supported in 1.6,
6274 though there is no UI for it---then you should use format 11 and, of course,
6275 use only layout constructs that were available in LyX 1.6.
6278 \begin_layout Standard
6280 \change_inserted 1414654397 1302963275
6281 When you have entered something in the
6282 \begin_inset Flex Code
6285 \begin_layout Plain Layout
6287 \change_inserted 1414654397 1302963275
6295 pane, LyX will enable the
6296 \begin_inset Quotes eld
6300 \begin_inset Quotes erd
6303 button at the bottom.
6304 Clicking this button will cause LyX to determine whether what you have
6305 entered is valid layout information for the chosen format.
6306 LyX will report the result but, unfortunately, will not tell you what errors
6307 there might have been.
6308 These will be written to the terminal, however, if LyX is started from
6310 You will not be permitted to save your local layout until you have entered
6314 \begin_layout Standard
6316 \change_inserted 1414654397 1302963364
6317 The warnings at the end of the previous section apply here, too.
6318 Do not play with local layout while you are actually working, especially
6319 if you have not saved your document.
6320 That said, using local layout with a test document can be a very convenient
6321 way to try out layout ideas, or even to start developing a module.
6326 \begin_layout Subsection
6328 \begin_inset Flex MenuItem
6331 \begin_layout Plain Layout
6340 \begin_layout Standard
6341 There are two situations you are likely to encounter when wanting to support
6342 a new LaTeX document class, involving style (
6343 \begin_inset Flex Code
6346 \begin_layout Plain Layout
6352 ) files and LaTeX2e class (
6353 \begin_inset Flex Code
6356 \begin_layout Plain Layout
6363 Supporting a style file is usually fairly easy.
6364 Supporting a new class file is a bit harder.
6365 We'll discuss the former in this section and the latter in the next.
6366 Similar remarks apply, of course, if you want to support a new DocBook
6370 \begin_layout Standard
6371 The easier case is the one in which your new document class is provided
6372 as a style file that is to be used in conjunction with an already supported
6374 For the sake of the example, we'll assume that the style file is called
6376 \begin_inset Flex MenuItem
6379 \begin_layout Plain Layout
6385 and that it is meant to be used with
6386 \begin_inset Flex MenuItem
6389 \begin_layout Plain Layout
6395 , which is a standard class.
6399 \begin_layout Standard
6400 Start by copying the existing class's layout file into your local directory:
6404 \begin_layout Plain Layout
6405 Of course, which directory is your local directory will vary by platform,
6406 and LyX allows you to specify your local directory on startup, too, using
6408 \begin_inset Flex Code
6411 \begin_layout Plain Layout
6425 \begin_layout LyX-Code
6426 cp report.layout ~/.lyx/layouts/myclass.layout
6429 \begin_layout Standard
6431 \begin_inset Flex Code
6434 \begin_layout Plain Layout
6440 and change the line:
6443 \begin_layout LyX-Code
6446 DeclareLaTeXClass{report}
6449 \begin_layout Standard
6453 \begin_layout LyX-Code
6456 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6459 \begin_layout Standard
6463 \begin_layout LyX-Code
6465 \begin_inset Newline newline
6471 \begin_inset Newline newline
6477 \begin_layout Standard
6478 near the top of the file.
6481 \begin_layout Standard
6482 Start LyX and select
6483 \begin_inset Flex MenuItem
6486 \begin_layout Plain Layout
6487 Tools\SpecialChar \menuseparator
6494 Then restart LyX and try creating a new document.
6496 \begin_inset Flex MenuItem
6499 \begin_layout Plain Layout
6505 " as a document class option in the
6506 \begin_inset Flex MenuItem
6509 \begin_layout Plain Layout
6510 Document\SpecialChar \menuseparator
6517 It is likely that some of the sectioning commands and such in your new
6518 class will work differently from how they worked in the base class—
6519 \begin_inset Flex Code
6522 \begin_layout Plain Layout
6528 in this example—so you can fiddle around with the settings for the different
6529 sections if you wish.
6530 The layout information for sections is contained in
6531 \begin_inset Flex Code
6534 \begin_layout Plain Layout
6540 , but you do not need to copy and change this file.
6541 Instead, you can simply add your changes to your layout file, after the
6543 \begin_inset Flex Code
6546 \begin_layout Plain Layout
6552 , which itself includes
6553 \begin_inset Flex Code
6556 \begin_layout Plain Layout
6563 For example, you might add these lines:
6566 \begin_layout LyX-Code
6570 \begin_layout LyX-Code
6574 \begin_layout LyX-Code
6578 \begin_layout LyX-Code
6582 \begin_layout LyX-Code
6586 \begin_layout Standard
6587 to change the font for chapter headings to sans-serif.
6588 This will override (or, in this case, add to) the existing declaration
6589 for the Chapter style.
6593 \begin_layout Standard
6594 Your new package may also provide commands or environments not present in
6596 In this case, you will want to add these to the layout file.
6598 \begin_inset CommandInset ref
6600 reference "sec:TextClass"
6604 for information on how to do so.
6607 \begin_layout Standard
6609 \begin_inset Flex MenuItem
6612 \begin_layout Plain Layout
6618 can be used with several different document classes, and even if it cannot,
6619 you might find it easiest just to write a module that you can load with
6621 The simplest possible such module would be:
6624 \begin_layout LyX-Code
6627 DeclareLyXModule{My Package}
6630 \begin_layout LyX-Code
6634 \begin_layout LyX-Code
6635 #Support for mypkg.sty.
6638 \begin_layout LyX-Code
6640 \begin_inset Newline newline
6646 \begin_layout LyX-Code
6648 \begin_inset Newline newline
6654 \begin_layout LyX-Code
6656 \begin_inset Newline newline
6662 \begin_inset Newline newline
6668 \begin_layout Standard
6669 A more complex module might modify the behavior of some existing constructs
6670 or define some new ones.
6672 \begin_inset CommandInset ref
6674 reference "sec:TextClass"
6681 \begin_layout Subsection
6683 \begin_inset Flex MenuItem
6686 \begin_layout Plain Layout
6695 \begin_layout Standard
6696 There are two possibilities here.
6697 One is that the class file is itself based upon an existing document class.
6698 For example, many thesis classes are based upon
6699 \begin_inset Flex MenuItem
6702 \begin_layout Plain Layout
6709 To see whether yours is, look for a line like
6712 \begin_layout LyX-Code
6718 \begin_layout Standard
6720 If so, then you may proceed largely as in the previous section, though
6722 \begin_inset Flex Code
6725 \begin_layout Plain Layout
6731 line will be different.
6732 If your new class is
6733 \begin_inset Flex Code
6736 \begin_layout Plain Layout
6742 and it is based upon
6743 \begin_inset Flex Code
6746 \begin_layout Plain Layout
6752 , then the line should read:
6756 \begin_layout Plain Layout
6757 And it will be easiest if you save the file to
6758 \begin_inset Flex Code
6761 \begin_layout Plain Layout
6767 : LyX assumes that the document class has the same name as the layout file.
6776 \begin_layout LyX-Code
6779 DeclareLaTeXClass[thesis,book]{thesis}
6782 \begin_layout Standard
6783 If, on the other hand, the new class is not based upon an existing class,
6784 you will probably have to
6785 \begin_inset Quotes eld
6789 \begin_inset Quotes erd
6793 We strongly suggest copying an existing layout file which uses a similar
6794 LaTeX class and then modifying it, if you can do so.
6795 At least use an existing file as a starting point so you can find out what
6796 items you need to worry about.
6797 Again, the specifics are covered below.
6800 \begin_layout Subsection
6802 \begin_inset CommandInset label
6804 name "sub:Creating-Templates"
6811 \begin_layout Standard
6812 Once you have written a layout file for a new document class, you might
6813 want to consider writing a
6818 A template acts as a kind of tutorial for your layout, showing how it might
6819 be used, though containing dummy content.
6820 You can of course look at the various templates included with LyX for ideas.
6823 \begin_layout Standard
6824 Templates are created just like usual documents: using LyX.
6825 The only difference is that usual documents contain all possible settings,
6826 including the font scheme and the paper size.
6827 Usually a user doesn't want a template to overwrite his preferred settings
6828 for such parameters.
6829 For that reason, the designer of a template should remove the corresponding
6831 \begin_inset Flex Code
6834 \begin_layout Plain Layout
6843 \begin_inset Flex Code
6846 \begin_layout Plain Layout
6854 from the template LyX file.
6855 This can be done with any simple text-editor, for example
6856 \begin_inset Flex Code
6859 \begin_layout Plain Layout
6866 \begin_inset Flex Code
6869 \begin_layout Plain Layout
6879 \begin_layout Standard
6880 Put the edited template files you create in
6881 \begin_inset Flex Code
6884 \begin_layout Plain Layout
6890 , copy the ones you use from the global template directory in
6891 \begin_inset Flex Code
6894 \begin_layout Plain Layout
6900 to the same place, and redefine the template path in the
6901 \begin_inset Flex MenuItem
6904 \begin_layout Plain Layout
6905 Tools\SpecialChar \menuseparator
6906 Preferences\SpecialChar \menuseparator
6915 \begin_layout Standard
6916 Note, by the way, that there is a template which has a particular meaning:
6918 \begin_inset Flex Code
6921 \begin_layout Plain Layout
6928 This template is loaded every time you create a new document with
6929 \begin_inset Flex MenuItem
6932 \begin_layout Plain Layout
6933 File\SpecialChar \menuseparator
6939 in order to provide useful defaults.
6940 To create this template from inside LyX, all you have to do is to open
6941 a document with the correct settings, and use the
6942 \begin_inset Flex MenuItem
6945 \begin_layout Plain Layout
6946 Save as Document Defaults
6954 \begin_layout Subsection
6955 Upgrading old layout files
6958 \begin_layout Standard
6959 The format of layout files changes with each LyX release, so old layout
6960 files need to be converted to the new format.
6961 This process has been automated since LyX 1.4: If LyX reads a layout file
6962 in an older format, it automatically calls the script
6963 \begin_inset Flex Code
6966 \begin_layout Plain Layout
6972 to convert it to a temporary file in current format.
6973 The original file is left untouched.
6974 If you use the layout file often, then, you may want to convert it permanently,
6975 so that LyX does not have to do so itself every time.
6976 To do this, you can call the converter manually:
6979 \begin_layout LyX-Code
6980 mv myclass.layout myclass.old
6983 \begin_layout LyX-Code
6984 python LyXDir/scripts/layout2layout.py myclass.old myclass.layout
6987 \begin_layout Standard
6989 \begin_inset Flex Code
6992 \begin_layout Plain Layout
6998 with the name of your LyX system directory, of course.
7001 \begin_layout Standard
7002 Note that manual conversion does not affect included files, so these will
7003 have to be converted separately.
7006 \begin_layout Section
7007 \begin_inset CommandInset label
7009 name "sec:TextClass"
7013 The layout file format
7016 \begin_layout Standard
7017 When it's finally time to get your hands dirty and create or edit your own
7018 layout file, the following sections describe what you're up against.
7019 Our advice is to go slowly, save and test often, listen to soothing music,
7020 and enjoy one or two of your favorite adult beverages; more if you are
7021 getting particularly stuck.
7022 It's really not that hard, except that the multitude of options can become
7023 overwhelming if you try to do too much in one sitting.
7024 Go have another adult beverage, just for good measure.
7027 \begin_layout Standard
7028 Note that all the tags used in layout files are case-insensitive.
7030 \begin_inset Flex Code
7033 \begin_layout Plain Layout
7040 \begin_inset Flex Code
7043 \begin_layout Plain Layout
7050 \begin_inset Flex Code
7053 \begin_layout Plain Layout
7059 are really the same tag.
7060 The possible values are printed in brackets after the feature's name.
7061 The default value if a feature isn't specified inside a text class-description
7063 \begin_inset Flex Code
7066 \begin_layout Plain Layout
7075 If the argument has a data type like
7076 \begin_inset Quotes eld
7080 \begin_inset Quotes erd
7084 \begin_inset Quotes eld
7088 \begin_inset Quotes erd
7091 , the default is shown like this:
7092 \begin_inset Flex Code
7095 \begin_layout Plain Layout
7106 \begin_layout Subsection
7107 The document class declaration
7110 \begin_layout Standard
7111 Lines in a layout file which begin with
7112 \begin_inset Flex Code
7115 \begin_layout Plain Layout
7122 There is one exception to this rule.
7124 \begin_inset Flex Code
7127 \begin_layout Plain Layout
7133 files should begin with a line like:
7136 \begin_layout LyX-Code
7139 #% Do not delete the line below; configure depends on this
7142 \begin_layout LyX-Code
7147 DeclareLaTeXClass{article}
7150 \begin_layout Standard
7151 The second line is used when you (re)configure LyX.
7152 The layout file is read by the LaTeX script
7153 \begin_inset Flex Code
7156 \begin_layout Plain Layout
7162 , in a special mode where
7163 \begin_inset Flex Code
7166 \begin_layout Plain Layout
7173 The first line is just a LaTeX comment, and the second one contains the
7174 declaration of the text class.
7175 If these lines appear in a file named
7176 \begin_inset Flex Code
7179 \begin_layout Plain Layout
7185 , then they define a text class of name
7186 \begin_inset Flex Code
7189 \begin_layout Plain Layout
7195 (the name of the layout file) which uses the LaTeX document class
7196 \begin_inset Flex Code
7199 \begin_layout Plain Layout
7205 (the default is to use the same name as the layout).
7207 \begin_inset Quotes eld
7211 \begin_inset Quotes erd
7214 that appears above is used as a description of the text class in the
7215 \begin_inset Flex MenuItem
7218 \begin_layout Plain Layout
7219 Document\SpecialChar \menuseparator
7228 \begin_layout Standard
7229 Let's assume that you wrote your own text class that uses the
7230 \begin_inset Flex Code
7233 \begin_layout Plain Layout
7239 document class, but where you changed the appearance of the section headings.
7240 If you put it in a file
7241 \begin_inset Flex Code
7244 \begin_layout Plain Layout
7250 , the header of this file should be:
7253 \begin_layout LyX-Code
7256 #% Do not delete the line below; configure depends on this
7259 \begin_layout LyX-Code
7264 DeclareLaTeXClass[article]{article (with my own headings)}
7267 \begin_layout Standard
7268 This declares a text class
7269 \begin_inset Flex Code
7272 \begin_layout Plain Layout
7278 , associated with the LaTeX document class
7279 \begin_inset Flex Code
7282 \begin_layout Plain Layout
7289 \begin_inset Quotes eld
7292 article (with my own headings)
7293 \begin_inset Quotes erd
7297 If your text class depends on several packages, you can declare it as:
7300 \begin_layout LyX-Code
7303 #% Do not delete the line below; configure depends on this
7306 \begin_layout LyX-Code
7311 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
7314 \begin_layout Standard
7315 This indicates that your text class uses the
7316 \begin_inset Flex Code
7319 \begin_layout Plain Layout
7326 Finally, it is also possible to declare classes for DocBook code.
7327 Typical declarations will look like:
7330 \begin_layout LyX-Code
7333 #% Do not delete the line below; configure depends on this
7336 \begin_layout LyX-Code
7341 DeclareDocBookClass[article]{SGML (DocBook article)}
7344 \begin_layout Standard
7345 Note that these declarations can also be given an optional parameter declaring
7346 the name of the document class (but not a list).
7349 \begin_layout Standard
7350 So, to be as explicit as possible, the form of the layout declaration is:
7353 \begin_layout LyX-Code
7358 DeclareLaTeXClass[class,package.sty]{layout description}
7361 \begin_layout Standard
7362 The class need only be specified if the name of the LaTeX class file and
7363 the name of the layout file are different or if there are packages to load.
7364 If the name of the class file is not specified, then LyX will simply assume
7365 that it is the same as the name of the layout file.
7368 \begin_layout Standard
7369 When the text class has been modified to your taste, all you have to do
7370 is to copy it either to
7371 \begin_inset Flex Code
7374 \begin_layout Plain Layout
7381 \begin_inset Flex Code
7384 \begin_layout Plain Layout
7391 \begin_inset Flex MenuItem
7394 \begin_layout Plain Layout
7395 Tools\SpecialChar \menuseparator
7401 , exit LyX and restart.
7402 Then your new text class should be available along with the others.
7405 \begin_layout Standard
7406 Once the layout file is installed, you can edit it and see your changes
7407 without having to reconfigure or to restart LyX.
7412 \begin_layout Plain Layout
7413 In versions of LyX prior to 1.6, this was not true.
7414 As a result, editing layout files was very time consuming, since you had
7415 constantly to restart LyX to see changes.
7420 You can force a reload of the current layout by using the LyX function
7422 \begin_inset Flex MenuItem
7425 \begin_layout Plain Layout
7432 There is no default binding for this function—though, of course, you can
7433 bind it to a key yourself.
7434 But you will normally use this function simply by entering it in the mini-buffe
7439 \begin_layout Standard
7445 \begin_inset Flex MenuItem
7448 \begin_layout Plain Layout
7454 is very much an `advanced feature'.
7459 recommended that you save your work before using this function.
7464 recommended that you not attempt to edit layout information while simultaneousl
7465 y working on a document that you care about.
7466 Use a test document.
7467 Syntax errors and the like in your layout file could cause peculiar behavior.
7468 In particular, such errors could cause LyX to regard the current layout
7469 as invalid and to attempt to switch to some other layout.
7473 \begin_layout Plain Layout
7474 Really bad syntax errors may even caused LyX to exit.
7475 This is because certain sorts of errors may make LyX unable to read
7485 The LyX team strives to keep LyX stable in such situations, but safe is
7490 \begin_layout Plain Layout
7491 While we're giving advice: make regular backups.
7492 And be nice to your mother.
7500 \begin_layout Subsection
7501 The Module declaration
7504 \begin_layout Standard
7505 A module must begin with a line like the following:
7508 \begin_layout LyX-Code
7511 DeclareLyXModule[endnotes.sty]{Endnotes}
7514 \begin_layout Standard
7515 The mandatory argument, in curly brackets, is the name of the module, as
7517 \begin_inset Flex MenuItem
7520 \begin_layout Plain Layout
7521 Document\SpecialChar \menuseparator
7522 Settings\SpecialChar \menuseparator
7529 The argument in square brackets is optional: It declares any LaTeX packages
7530 on which the module depends.
7531 Please note that only packages about which LyX knows should be listed in
7532 the square brackets.
7536 \begin_layout Plain Layout
7537 The list of such packages is documented only in the source code.
7542 LyX will not check for arbitrary packages.
7543 It is also possible to use the form
7544 \begin_inset Flex MenuItem
7547 \begin_layout Plain Layout
7553 as an optional argument, which declares that the module can only be used
7554 when there exists a conversion chain between the formats `
7555 \begin_inset Flex Code
7558 \begin_layout Plain Layout
7565 \begin_inset Flex Code
7568 \begin_layout Plain Layout
7577 \begin_layout Standard
7578 The module declaration should then be followed by lines like the following
7582 \begin_layout Plain Layout
7583 Preferably in English if the module should be published with LyX.
7584 This description will appear in the list of messages to be translated and
7585 will be thus translated with the next interface update.
7593 \begin_layout LyX-Code
7597 \begin_layout LyX-Code
7598 #Adds an endnote command, in addition to footnotes.
7602 \begin_layout LyX-Code
7603 #You will need to add
7605 theendnotes in TeX code where you
7608 \begin_layout LyX-Code
7609 #want the endnotes to appear.
7613 \begin_layout LyX-Code
7617 \begin_layout LyX-Code
7618 #Requires: somemodule | othermodule
7621 \begin_layout LyX-Code
7622 #Excludes: badmodule
7625 \begin_layout Standard
7626 The description is used in
7627 \begin_inset Flex MenuItem
7630 \begin_layout Plain Layout
7631 Document\SpecialChar \menuseparator
7632 Settings\SpecialChar \menuseparator
7638 to provide the user with information about what the module does.
7640 \begin_inset Flex Code
7643 \begin_layout Plain Layout
7649 line is used to identify other modules with which this one must be used;
7651 \begin_inset Flex Code
7654 \begin_layout Plain Layout
7660 line is used to identify modules with which this one may not be used.
7661 Both are optional, and, as shown, multiple modules should be separated
7662 with the pipe symbol: |.
7663 Note that the required modules are treated disjunctively:
7667 of the required modules must be used.
7672 excluded module may be used.
7673 Note that modules are identified here by their
7678 \begin_inset Flex Code
7681 \begin_layout Plain Layout
7689 \begin_inset Flex Code
7692 \begin_layout Plain Layout
7699 \begin_inset Flex Code
7702 \begin_layout Plain Layout
7711 \begin_layout Subsection
7715 \begin_layout Standard
7716 The first non-comment line of any layout file, included file, or module
7721 contain the file format number:
7724 \begin_layout Description
7725 \begin_inset Flex Code
7728 \begin_layout Plain Layout
7735 \begin_inset Flex Code
7738 \begin_layout Plain Layout
7744 ] The format of the layout file.
7747 \begin_layout Standard
7748 This tag was introduced with LyX 1.4.0.
7749 Layout files from LyX 1.3.x and earlier don't have an explicit file format
7750 and are considered to be of format 1.
7751 The format for the present version of LyX is format 21.
7752 But each version of LyX is capable of reading earlier versions' layout
7753 files, just as they are capable of reading files produced by earlier versions
7755 There is, however, no provision for converting to earlier formats.
7756 So LyX 1.6.x will not read layout files in format 21 but only files in format
7760 \begin_layout Subsection
7761 \begin_inset CommandInset label
7763 name "sub:General-text-class"
7767 General text class parameters
7770 \begin_layout Standard
7771 These are general parameters that govern the behavior of an entire document
7777 mean that they must appear in
7778 \begin_inset Flex Code
7781 \begin_layout Plain Layout
7787 files rather than in modules.
7788 A module can contain any layout tag.)
7791 \begin_layout Description
7792 \begin_inset Flex Code
7795 \begin_layout Plain Layout
7801 Adds information that will be output in the
7802 \begin_inset Flex Code
7805 \begin_layout Plain Layout
7811 block when this document class is output to XHTML.
7812 Typically, this would be used to output CSS style information, but it can
7813 be used for anything that can appear in
7814 \begin_inset Flex Code
7817 \begin_layout Plain Layout
7825 \begin_inset Quotes eld
7829 \begin_inset Flex Code
7832 \begin_layout Plain Layout
7839 \begin_inset Quotes erd
7845 \begin_layout Description
7846 \begin_inset Flex Code
7849 \begin_layout Plain Layout
7855 Adds information to the document preamble.
7857 \begin_inset Quotes eld
7861 \begin_inset Flex Code
7864 \begin_layout Plain Layout
7871 \begin_inset Quotes erd
7877 \begin_layout Description
7878 \begin_inset Flex Code
7881 \begin_layout Plain Layout
7887 Defines formats for use in the display of bibliographic information.
7889 \begin_inset CommandInset ref
7891 reference "sub:Citation-format-description"
7897 \begin_inset Quotes eld
7901 \begin_inset Flex Code
7904 \begin_layout Plain Layout
7911 \begin_inset Quotes erd
7917 \begin_layout Description
7918 \begin_inset Flex Code
7921 \begin_layout Plain Layout
7927 Describes various global options supported by the document class.
7929 \begin_inset space ~
7933 \begin_inset CommandInset ref
7935 reference "sub:ClassOptions"
7941 \begin_inset Quotes eld
7945 \begin_inset Flex Code
7948 \begin_layout Plain Layout
7955 \begin_inset Quotes erd
7961 \begin_layout Description
7962 \begin_inset Flex Code
7965 \begin_layout Plain Layout
7972 \begin_inset Flex Code
7975 \begin_layout Plain Layout
7984 \begin_inset Flex Code
7987 \begin_layout Plain Layout
7993 ] Whether the class should
7997 to having one or two columns.
7998 Can be changed in the
7999 \begin_inset Flex MenuItem
8002 \begin_layout Plain Layout
8003 Document\SpecialChar \menuseparator
8012 \begin_layout Description
8013 \begin_inset Flex Code
8016 \begin_layout Plain Layout
8023 \begin_inset Flex Code
8026 \begin_layout Plain Layout
8032 ] This sequence defines the properties for a counter.
8033 If the counter does not yet exist, it is created; if it does exist, it
8036 \begin_inset Quotes eld
8040 \begin_inset Flex Code
8043 \begin_layout Plain Layout
8050 \begin_inset Quotes erd
8054 \begin_inset Newline newline
8058 \begin_inset space ~
8062 \begin_inset CommandInset ref
8064 reference "sub:Counters"
8068 for details on counters.
8071 \begin_layout Description
8072 \begin_inset Flex Code
8075 \begin_layout Plain Layout
8081 Sets the default font used to display the document.
8083 \begin_inset space ~
8087 \begin_inset CommandInset ref
8089 reference "sub:Font-description"
8093 for how to declare fonts.
8095 \begin_inset Quotes eld
8099 \begin_inset Flex Code
8102 \begin_layout Plain Layout
8109 \begin_inset Quotes erd
8115 \begin_layout Description
8116 \begin_inset Flex Code
8119 \begin_layout Plain Layout
8126 \begin_inset Flex Code
8129 \begin_layout Plain Layout
8135 Specifies a module to be included by default with this document class.
8136 The module should be specified by filename without the
8137 \begin_inset Flex Code
8140 \begin_layout Plain Layout
8147 The user can still remove the module, but it will be active at the outset.
8148 (This applies only when new files are created, or when this class is chosen
8149 for an existing document.)
8152 \begin_layout Description
8153 \begin_inset Flex Code
8156 \begin_layout Plain Layout
8163 \begin_inset Flex Code
8166 \begin_layout Plain Layout
8172 ] This is the style that will be assigned to new paragraphs, usually
8173 \begin_inset Flex MenuItem
8176 \begin_layout Plain Layout
8183 This will default to the first defined style if not given, but you are
8184 encouraged to use this directive.
8187 \begin_layout Description
8188 \begin_inset Flex Code
8191 \begin_layout Plain Layout
8198 \begin_inset Flex Code
8201 \begin_layout Plain Layout
8207 ] This tag indicates that the module in question—which should be specified
8208 by filename without the
8209 \begin_inset Flex Code
8212 \begin_layout Plain Layout
8218 extension—cannot be used with this document class.
8219 This might be used in a journal-specific layout file to prevent, say, the
8221 \begin_inset Flex Code
8224 \begin_layout Plain Layout
8230 module that numbers theorems by section.
8235 be used in a module.
8236 Modules have their own way of excluding other modules (see
8237 \begin_inset CommandInset ref
8239 reference "sub:Layout-modules"
8246 \begin_layout Description
8247 \begin_inset Flex Code
8250 \begin_layout Plain Layout
8256 Defines a new float.
8258 \begin_inset space ~
8262 \begin_inset CommandInset ref
8264 reference "sub:Floats"
8270 \begin_inset Quotes eld
8274 \begin_inset Flex Code
8277 \begin_layout Plain Layout
8284 \begin_inset Quotes erd
8290 \begin_layout Description
8291 \begin_inset Flex Code
8294 \begin_layout Plain Layout
8300 Sets the information that will be output in the
8301 \begin_inset Flex Code
8304 \begin_layout Plain Layout
8310 block when this document class is output to XHTML.
8311 Note that this will completely override any prior
8312 \begin_inset Flex Code
8315 \begin_layout Plain Layout
8322 \begin_inset Flex Code
8325 \begin_layout Plain Layout
8333 \begin_inset Flex Code
8336 \begin_layout Plain Layout
8342 if you just want to add material to the preamble.) Must end with
8343 \begin_inset Quotes eld
8347 \begin_inset Flex Code
8350 \begin_layout Plain Layout
8357 \begin_inset Quotes erd
8363 \begin_layout Description
8364 \begin_inset Flex Code
8367 \begin_layout Plain Layout
8374 \begin_inset Flex Code
8377 \begin_layout Plain Layout
8383 ] The layout to use for the table of contents, bibliography, and so forth,
8384 when the document is output to HTML.
8385 For articles, this should normally be Section; for books, Chapter.
8386 If it is not given, then LyX will attempt to figure out which layout to
8390 \begin_layout Description
8391 \begin_inset Flex Code
8394 \begin_layout Plain Layout
8401 \begin_inset Flex Code
8404 \begin_layout Plain Layout
8410 ] Modifies the properties of the given counter.
8411 If the counter does not exist, the section is ignored.
8413 \begin_inset Quotes eld
8417 \begin_inset Flex Code
8420 \begin_layout Plain Layout
8427 \begin_inset Quotes erd
8431 \begin_inset Newline newline
8435 \begin_inset space ~
8439 \begin_inset CommandInset ref
8441 reference "sub:Counters"
8445 for details on counters.
8448 \begin_layout Description
8449 \begin_inset Flex Code
8452 \begin_layout Plain Layout
8459 \begin_inset Flex Code
8462 \begin_layout Plain Layout
8468 ] Modifies the properties of the given paragraph style.
8469 If the style does not exist, the section is ignored.
8471 \begin_inset Quotes eld
8475 \begin_inset Flex Code
8478 \begin_layout Plain Layout
8485 \begin_inset Quotes erd
8491 \begin_layout Description
8492 \begin_inset Flex Code
8495 \begin_layout Plain Layout
8501 As its name implies, this command allows you to include another layout
8502 definition file within yours to avoid duplicating commands.
8503 Common examples are the standard layout files, for example,
8504 \begin_inset Flex Code
8507 \begin_layout Plain Layout
8513 , which contains most of the basic layouts.
8516 \begin_layout Description
8517 \begin_inset Flex Code
8520 \begin_layout Plain Layout
8526 This section (re-)defines the layout of an inset.
8527 It can be applied to an existing inset or to a new, user-defined inset,
8528 e.g., a new character style.
8530 \begin_inset Quotes eld
8534 \begin_inset Flex Code
8537 \begin_layout Plain Layout
8544 \begin_inset Quotes erd
8548 \begin_inset Newline newline
8552 \begin_inset space ~
8556 \begin_inset CommandInset ref
8558 reference "sub:Flex-insets-and"
8562 for more information.
8566 \begin_layout Description
8567 \begin_inset Flex Code
8570 \begin_layout Plain Layout
8577 \begin_inset Flex Code
8580 \begin_layout Plain Layout
8586 ] A string that indicates the width of the left margin on the screen, for
8588 \begin_inset Quotes eld
8592 \begin_inset Quotes erd
8596 (Note that this is not a `length', like
8597 \begin_inset Quotes eld
8601 \begin_inset Quotes erd
8607 \begin_layout Description
8608 \begin_inset Flex Code
8611 \begin_layout Plain Layout
8618 \begin_inset Flex Code
8621 \begin_layout Plain Layout
8627 ] This command deletes an existing counter, usually one defined in an included
8631 \begin_layout Description
8632 \begin_inset Flex Code
8635 \begin_layout Plain Layout
8641 This command deletes an existing float.
8642 This is particularly useful when you want to suppress a float that has
8643 been defined in an input file.
8646 \begin_layout Description
8647 \begin_inset Flex Code
8650 \begin_layout Plain Layout
8656 This command deletes an existing style.
8657 This is particularly useful when you want to suppress a style that has
8658 be defined in an input file.
8661 \begin_layout Description
8662 \begin_inset Flex Code
8665 \begin_layout Plain Layout
8671 A string indicating the file format (as defined in the Preferences dialog)
8672 produced by this class.
8673 It is mainly useful when
8674 \begin_inset Flex Code
8677 \begin_layout Plain Layout
8683 is `literate' and one wants to define a new type of literate document.
8684 This string is reset to `docbook', `latex', or `literate' when the correspondin
8686 \begin_inset Flex Code
8689 \begin_layout Plain Layout
8695 parameter is encountered.
8698 \begin_layout Description
8699 \begin_inset Flex Code
8702 \begin_layout Plain Layout
8708 A string indicating what sort of output documents using this class will
8710 At present, the options are: `docbook', `latex', and `literate'.
8713 \begin_layout Description
8714 \begin_inset Flex Code
8717 \begin_layout Plain Layout
8724 \begin_inset Flex Code
8727 \begin_layout Plain Layout
8736 \begin_inset Flex Code
8739 \begin_layout Plain Layout
8746 \begin_inset Flex Code
8749 \begin_layout Plain Layout
8755 ] The default pagestyle.
8756 Can be changed in the
8757 \begin_inset Flex MenuItem
8760 \begin_layout Plain Layout
8761 Document\SpecialChar \menuseparator
8770 \begin_layout Description
8771 \begin_inset Flex Code
8774 \begin_layout Plain Layout
8780 Sets the preamble for the LaTeX document.
8781 Note that this will completely override any prior
8782 \begin_inset Flex Code
8785 \begin_layout Plain Layout
8792 \begin_inset Flex Code
8795 \begin_layout Plain Layout
8803 \begin_inset Flex Code
8806 \begin_layout Plain Layout
8812 if you just want to add material to the preamble.) Must end with
8813 \begin_inset Quotes eld
8817 \begin_inset Flex Code
8820 \begin_layout Plain Layout
8827 \begin_inset Quotes erd
8833 \begin_layout Description
8834 \begin_inset Flex Code
8837 \begin_layout Plain Layout
8844 \begin_inset Flex Code
8847 \begin_layout Plain Layout
8854 \begin_inset Flex Code
8857 \begin_layout Plain Layout
8866 \begin_inset Flex Code
8869 \begin_layout Plain Layout
8875 ] Whether the class already provides the feature
8876 \begin_inset Flex Code
8879 \begin_layout Plain Layout
8886 A feature is in general the name of a package (
8887 \begin_inset Flex Code
8890 \begin_layout Plain Layout
8897 \begin_inset Flex Code
8900 \begin_layout Plain Layout
8906 , \SpecialChar \ldots{}
8908 \begin_inset Flex Code
8911 \begin_layout Plain Layout
8918 \begin_inset Flex Code
8921 \begin_layout Plain Layout
8927 ,\SpecialChar \ldots{}
8928 ); the complete list of supported features is unfortunately not documented
8929 outside the LyX source code—but see
8930 \begin_inset Flex Code
8933 \begin_layout Plain Layout
8939 if you're interested.
8941 \begin_inset Flex MenuItem
8944 \begin_layout Plain Layout
8945 Help\SpecialChar \menuseparator
8951 also gives an overview of the supported packages.
8954 \begin_layout Description
8955 \begin_inset Flex Code
8958 \begin_layout Plain Layout
8965 \begin_inset Flex Code
8968 \begin_layout Plain Layout
8974 ] Indicates that this layout provides the functionality of the module mentioned,
8975 which should be specified by the filename without the
8976 \begin_inset Flex Code
8979 \begin_layout Plain Layout
8986 This will typically be used if the layout includes the module directly,
8987 rather than using the
8988 \begin_inset Flex Code
8991 \begin_layout Plain Layout
8997 tag to indicate that it ought to be used.
8998 It could also be used in a module that provided an alternate implementation
8999 of the same functionality.
9002 \begin_layout Description
9003 \begin_inset Flex Code
9006 \begin_layout Plain Layout
9013 \begin_inset Flex Code
9016 \begin_layout Plain Layout
9022 ] Whether the class requires the feature
9023 \begin_inset Flex Code
9026 \begin_layout Plain Layout
9033 Multiple features must be separated by commas.
9034 Note that you can only request supported features.
9036 \begin_inset Flex Code
9039 \begin_layout Plain Layout
9045 for a list of these.)
9048 \begin_layout Description
9049 \begin_inset Flex Code
9052 \begin_layout Plain Layout
9058 A string that indicates the width of the right margin on the screen, for
9060 \begin_inset Quotes eld
9064 \begin_inset Quotes erd
9070 \begin_layout Description
9071 \begin_inset Flex Code
9074 \begin_layout Plain Layout
9080 Sets which divisions get numbered.
9082 \begin_inset Flex Code
9085 \begin_layout Plain Layout
9094 \begin_layout Description
9095 \begin_inset Flex Code
9098 \begin_layout Plain Layout
9105 \begin_inset Flex Code
9108 \begin_layout Plain Layout
9117 \begin_inset Flex Code
9120 \begin_layout Plain Layout
9126 ] Whether the class-default should be printing on one or both sides of the
9128 Can be changed in the
9129 \begin_inset Flex MenuItem
9132 \begin_layout Plain Layout
9133 Document\SpecialChar \menuseparator
9142 \begin_layout Description
9143 \begin_inset Flex Code
9146 \begin_layout Plain Layout
9152 This sequence defines a paragraph style.
9153 If the style does not yet exist, it is created; if it does exist, its parameter
9156 \begin_inset Quotes eld
9160 \begin_inset Flex Code
9163 \begin_layout Plain Layout
9170 \begin_inset Quotes erd
9174 \begin_inset Newline newline
9178 \begin_inset space ~
9182 \begin_inset CommandInset ref
9184 reference "sub:Paragraph-Styles"
9188 for details on paragraph styles.
9191 \begin_layout Description
9192 \begin_inset Flex Code
9195 \begin_layout Plain Layout
9202 \begin_inset Flex Code
9205 \begin_layout Plain Layout
9211 ] The name of the command or environment to be used with
9212 \begin_inset Flex Code
9215 \begin_layout Plain Layout
9224 \begin_layout Description
9225 \begin_inset Flex Code
9228 \begin_layout Plain Layout
9235 \begin_inset Flex Code
9238 \begin_layout Plain Layout
9247 \begin_inset Flex Code
9250 \begin_layout Plain Layout
9256 ] Indicates what kind of markup is used to define the title of a document.
9258 \begin_inset Flex Code
9261 \begin_layout Plain Layout
9267 means that the macro with name
9268 \begin_inset Flex Code
9271 \begin_layout Plain Layout
9277 will be inserted after the last layout which has
9278 \begin_inset Quotes eld
9282 \begin_inset Flex Code
9285 \begin_layout Plain Layout
9292 \begin_inset Quotes erd
9297 \begin_inset Flex Code
9300 \begin_layout Plain Layout
9306 corresponds to the case where the block of paragraphs which have
9307 \begin_inset Quotes eld
9311 \begin_inset Flex Code
9314 \begin_layout Plain Layout
9321 \begin_inset Quotes erd
9324 should be enclosed into the
9325 \begin_inset Flex Code
9328 \begin_layout Plain Layout
9337 \begin_layout Description
9338 \begin_inset Flex Code
9341 \begin_layout Plain Layout
9347 Sets which divisions are included in the table of contents.
9349 \begin_inset Flex Code
9352 \begin_layout Plain Layout
9361 \begin_layout Subsection
9362 \begin_inset Flex Code
9365 \begin_layout Plain Layout
9372 \begin_inset CommandInset label
9374 name "sub:ClassOptions"
9381 \begin_layout Standard
9383 \begin_inset Flex Code
9386 \begin_layout Plain Layout
9392 section can contain the following entries:
9395 \begin_layout Description
9396 \begin_inset Flex Code
9399 \begin_layout Plain Layout
9406 \begin_inset Flex Code
9409 \begin_layout Plain Layout
9415 ] The list of available font sizes for the document's main font, separated
9417 \begin_inset Quotes eld
9421 \begin_inset Flex Code
9424 \begin_layout Plain Layout
9431 \begin_inset Quotes erd
9437 \begin_layout Description
9438 \begin_inset Flex Code
9441 \begin_layout Plain Layout
9447 Used to set the DTD line with XML-based output classes.
9449 \begin_inset space \thinspace{}
9453 \begin_inset Quotes eld
9456 -//OASIS//DTD DocBook V4.2//EN
9457 \begin_inset Quotes erd
9463 \begin_layout Description
9464 \begin_inset Flex Code
9467 \begin_layout Plain Layout
9474 \begin_inset Flex Code
9477 \begin_layout Plain Layout
9478 string="empty|plain|headings|fancy"
9483 ] The list of available page styles, separated by
9484 \begin_inset Quotes eld
9488 \begin_inset Flex Code
9491 \begin_layout Plain Layout
9498 \begin_inset Quotes erd
9504 \begin_layout Description
9505 \begin_inset Flex Code
9508 \begin_layout Plain Layout
9515 \begin_inset Flex Code
9518 \begin_layout Plain Layout
9524 ] Some document class options, separated by a comma, that will be added
9525 to the optional part of the
9526 \begin_inset Flex Code
9529 \begin_layout Plain Layout
9540 \begin_layout Standard
9542 \begin_inset Flex Code
9545 \begin_layout Plain Layout
9551 section must end with
9552 \begin_inset Quotes eld
9556 \begin_inset Flex Code
9559 \begin_layout Plain Layout
9566 \begin_inset Quotes erd
9572 \begin_layout Subsection
9574 \begin_inset CommandInset label
9576 name "sub:Paragraph-Styles"
9583 \begin_layout Standard
9584 A paragraph style description looks like this:
9588 \begin_layout Plain Layout
9589 Note that this will either define a new style or modify an existing one.
9597 \begin_layout LyX-Code
9604 \begin_layout LyX-Code
9608 \begin_layout LyX-Code
9612 \begin_layout Standard
9613 where the following commands are allowed:
9616 \begin_layout Description
9617 \begin_inset Flex Code
9620 \begin_layout Plain Layout
9627 \begin_inset Flex Code
9630 \begin_layout Plain Layout
9635 , left, right, center
9640 ] Paragraph alignment.
9643 \begin_layout Description
9644 \begin_inset Flex Code
9647 \begin_layout Plain Layout
9654 \begin_inset Flex Code
9657 \begin_layout Plain Layout
9662 , left, right, center
9667 ] A comma separated list of permitted alignments.
9668 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
9670 For example a right-aligned or centered enumeration isn't possible.)
9673 \begin_layout Description
9674 \begin_inset Flex Code
9677 \begin_layout Plain Layout
9683 Note that this will completely override any prior
9684 \begin_inset Flex Code
9687 \begin_layout Plain Layout
9693 declaration for this style.
9695 \begin_inset Quotes eld
9699 \begin_inset Flex Code
9702 \begin_layout Plain Layout
9709 \begin_inset Quotes erd
9714 \begin_inset CommandInset ref
9716 reference "sub:I18n"
9720 for details on its use.
9723 \begin_layout Description
9724 \begin_inset Flex Code
9727 \begin_layout Plain Layout
9734 \begin_inset Flex Code
9737 \begin_layout Plain Layout
9747 \begin_layout Plain Layout
9748 Note that a `float' here is a real number, such as: 1.5.
9753 The vertical space with which the last of a chain of paragraphs with this
9754 style is separated from the following paragraph.
9755 If the next paragraph has another style, the separations are not simply
9756 added, but the maximum is taken.
9759 \begin_layout Description
9760 \begin_inset Flex Code
9763 \begin_layout Plain Layout
9770 \begin_inset Flex Code
9773 \begin_layout Plain Layout
9779 The category for this style.
9780 This is used to group related styles in the style combobox on the toolbar.
9781 Any string can be used, but you may want to use existing categories with
9786 \begin_layout Description
9787 \begin_inset Flex Code
9790 \begin_layout Plain Layout
9796 Depth of XML command.
9797 Used only with XML-type formats.
9800 \begin_layout Description
9801 \begin_inset Flex Code
9804 \begin_layout Plain Layout
9811 \begin_inset CommandInset label
9813 name "des:CopyStyle"
9818 \begin_inset Flex Code
9821 \begin_layout Plain Layout
9827 Copies all the features of an existing style into the current one.
9831 \begin_layout Description
9832 \begin_inset Flex Code
9835 \begin_layout Plain Layout
9841 The name of a style whose preamble should be output
9846 This allows to ensure some ordering of the preamble snippets when macros
9847 definitions depend on one another.
9851 \begin_layout Plain Layout
9852 Note that, besides that functionality, there is no way to ensure any ordering
9854 The ordering that you see in a given version of LyX may change without
9855 warning in later versions.
9863 \begin_layout Description
9864 \begin_inset Flex Code
9867 \begin_layout Plain Layout
9874 \begin_inset Flex Code
9877 \begin_layout Plain Layout
9882 , Box, Filled_Box, Static
9887 ] The type of label that stands at the end of the paragraph (or sequence
9889 \begin_inset Flex Code
9892 \begin_layout Plain Layout
9899 \begin_inset Flex Code
9902 \begin_layout Plain Layout
9909 \begin_inset Flex Code
9912 \begin_layout Plain Layout
9919 \begin_inset Flex Code
9922 \begin_layout Plain Layout
9930 \begin_inset Flex Code
9933 \begin_layout Plain Layout
9940 \begin_inset Quotes eld
9944 \begin_inset Quotes erd
9948 \begin_inset Flex Code
9951 \begin_layout Plain Layout
9958 \begin_inset Flex Code
9961 \begin_layout Plain Layout
9962 \begin_inset space ~
9971 \begin_inset space ~
9974 black) square suitable for end of proof markers,
9975 \begin_inset Flex Code
9978 \begin_layout Plain Layout
9984 is an explicit text string.
9987 \begin_layout Description
9988 \begin_inset Flex Code
9991 \begin_layout Plain Layout
9998 \begin_inset Flex Code
10001 \begin_layout Plain Layout
10007 ] The string used for a label with a
10008 \begin_inset Flex Code
10011 \begin_layout Plain Layout
10018 \begin_inset Flex Code
10021 \begin_layout Plain Layout
10031 \begin_layout Description
10032 \begin_inset Flex Code
10035 \begin_layout Plain Layout
10041 The font used for both the text body
10047 \begin_inset space ~
10051 \begin_inset CommandInset ref
10053 reference "sub:Font-description"
10058 Note that defining this font automatically defines the
10059 \begin_inset Flex Code
10062 \begin_layout Plain Layout
10069 So you should define this one first if you also want to define
10070 \begin_inset Flex Code
10073 \begin_layout Plain Layout
10082 \begin_layout Description
10083 \begin_inset Flex Code
10086 \begin_layout Plain Layout
10093 \begin_inset CommandInset label
10095 name "des:FreeSpacing"
10100 \begin_inset Flex Code
10103 \begin_layout Plain Layout
10112 \begin_inset Flex Code
10115 \begin_layout Plain Layout
10121 ] Usually LyX doesn't allow you to insert more than one space between words,
10122 since a space is considered as the separation between two words, not a
10123 character or symbol of its own.
10124 This is a very fine thing but sometimes annoying, for example, when typing
10125 program code or plain LaTeX code.
10127 \begin_inset Flex Code
10130 \begin_layout Plain Layout
10137 Note that LyX will create protected blanks for the additional blanks when
10138 in another mode than LaTeX-mode.
10141 \begin_layout Description
10142 \begin_inset Flex Code
10145 \begin_layout Plain Layout
10151 These tags are used with XHTML output.
10153 \begin_inset CommandInset ref
10155 reference "sub:Paragraph-Style-XHTML"
10162 \begin_layout Description
10163 \begin_inset Flex Code
10166 \begin_layout Plain Layout
10172 [[FIXME]] (Used only with XML-type formats.)
10175 \begin_layout Description
10176 \begin_inset Flex Code
10179 \begin_layout Plain Layout
10186 \begin_inset Flex Code
10189 \begin_layout Plain Layout
10195 If 1, marks the style as to be included in the document preamble rather
10196 than in the document body.
10197 This is useful for document classes that want such information as the title
10198 and author to appear in the preamble.
10199 Note that this works only for styles for which the
10200 \begin_inset Flex Code
10203 \begin_layout Plain Layout
10210 \begin_inset Flex Code
10213 \begin_layout Plain Layout
10220 \begin_inset Flex Code
10223 \begin_layout Plain Layout
10232 \begin_layout Description
10233 \begin_inset Flex Code
10236 \begin_layout Plain Layout
10243 \begin_inset Flex Code
10246 \begin_layout Plain Layout
10252 If 1, marks the style as being part of a title block (see also the
10253 \begin_inset Flex Code
10256 \begin_layout Plain Layout
10263 \begin_inset Flex Code
10266 \begin_layout Plain Layout
10275 \begin_layout Description
10276 \begin_inset Flex Code
10279 \begin_layout Plain Layout
10286 \begin_inset Flex Code
10289 \begin_layout Plain Layout
10295 ] This provides extra space between paragraphs that have the same style.
10296 If you put other styles into an environment, each is separated with the
10298 \begin_inset Flex Code
10301 \begin_layout Plain Layout
10308 But the whole items of the environment are additionally separated with
10310 \begin_inset Flex Code
10313 \begin_layout Plain Layout
10320 Note that this is a
10325 \begin_layout Description
10326 \begin_inset Flex Code
10329 \begin_layout Plain Layout
10335 [[FIXME]] (Used only with XML-type formats.)
10338 \begin_layout Description
10339 \begin_inset Flex Code
10342 \begin_layout Plain Layout
10349 \begin_inset CommandInset label
10351 name "des:KeepEmpty"
10356 \begin_inset Flex Code
10359 \begin_layout Plain Layout
10368 \begin_inset Flex Code
10371 \begin_layout Plain Layout
10377 ] Usually LyX does not allow you to leave a paragraph empty, since it would
10378 lead to empty LaTeX output.
10379 There are some cases where this could be desirable however: in a letter
10380 template, the required fields can be provided as empty fields, so that
10381 people do not forget them; in some special classes, a style can be used
10382 as some kind of break, which does not contain actual text.
10385 \begin_layout Description
10386 \begin_inset Flex Code
10389 \begin_layout Plain Layout
10395 [float=0] The vertical space between the label and the text body.
10396 Only used for labels that are above the text body (
10397 \begin_inset Flex Code
10400 \begin_layout Plain Layout
10407 \begin_inset Flex Code
10410 \begin_layout Plain Layout
10411 Centered_Top_Environment
10419 \begin_layout Description
10420 \begin_inset Flex Code
10423 \begin_layout Plain Layout
10430 \begin_inset Flex Code
10433 \begin_layout Plain Layout
10440 \begin_inset Newline newline
10443 The name of the counter for automatic numbering.
10445 \begin_inset Newline newline
10453 \begin_inset Flex Code
10456 \begin_layout Plain Layout
10463 \begin_inset Flex Code
10466 \begin_layout Plain Layout
10473 In that case, the counter will be stepped each time the style appears.
10475 \begin_inset Newline newline
10483 \begin_inset Flex Code
10486 \begin_layout Plain Layout
10493 \begin_inset Flex Code
10496 \begin_layout Plain Layout
10502 , though this case is a bit complicated.
10503 Suppose you declare
10504 \begin_inset Quotes eld
10508 \begin_inset Flex Code
10511 \begin_layout Plain Layout
10512 LabelCounter myenum
10518 \begin_inset Quotes erd
10522 Then the actual counters used are
10523 \begin_inset Flex Code
10526 \begin_layout Plain Layout
10533 \begin_inset Flex Code
10536 \begin_layout Plain Layout
10543 \begin_inset Flex Code
10546 \begin_layout Plain Layout
10553 \begin_inset Flex Code
10556 \begin_layout Plain Layout
10562 , much as in LaTeX.
10563 These counters must all be declared separately.
10564 \begin_inset Newline newline
10568 \begin_inset CommandInset ref
10570 reference "sub:Counters"
10574 for details on counters.
10577 \begin_layout Description
10578 \begin_inset Flex Code
10581 \begin_layout Plain Layout
10587 The font used for the label.
10589 \begin_inset space ~
10593 \begin_inset CommandInset ref
10595 reference "sub:Font-description"
10602 \begin_layout Description
10603 \begin_inset Flex Code
10606 \begin_layout Plain Layout
10612 Text that indicates how far a label should be indented.
10615 \begin_layout Description
10616 \begin_inset Flex Code
10619 \begin_layout Plain Layout
10626 \begin_inset Flex Code
10629 \begin_layout Plain Layout
10635 ] The horizontal space between the label and the text body.
10636 Only used for labels that are not above the text body.
10639 \begin_layout Description
10640 \begin_inset Flex Code
10643 \begin_layout Plain Layout
10650 \begin_inset Flex Code
10653 \begin_layout Plain Layout
10659 ] The string used for a label with a
10660 \begin_inset Flex Code
10663 \begin_layout Plain Layout
10671 \begin_inset Flex Code
10674 \begin_layout Plain Layout
10680 is set, this string can be contain the special formatting commands described
10682 \begin_inset CommandInset ref
10684 reference "sub:Counters"
10692 \begin_layout Plain Layout
10693 For the sake of backwards compatibility, the string
10694 \begin_inset Flex Code
10697 \begin_layout Plain Layout
10707 will be replaced by the expanded
10708 \begin_inset Flex Code
10711 \begin_layout Plain Layout
10718 \begin_inset Flex Code
10721 \begin_layout Plain Layout
10730 This feature is now obsolete and should be replaced by the mechanisms of
10732 \begin_inset CommandInset ref
10734 reference "sub:Counters"
10746 \begin_layout Description
10747 \begin_inset Flex Code
10750 \begin_layout Plain Layout
10751 LabelStringAppendix
10757 \begin_inset Flex Code
10760 \begin_layout Plain Layout
10766 ] This is used inside the appendix instead of
10767 \begin_inset Flex Code
10770 \begin_layout Plain Layout
10778 \begin_inset Flex Code
10781 \begin_layout Plain Layout
10788 \begin_inset Flex Code
10791 \begin_layout Plain Layout
10792 LabelStringAppendix
10800 \begin_layout Description
10801 \begin_inset Flex Code
10804 \begin_layout Plain Layout
10810 [FIXME] (Used only with XML-type formats.)
10813 \begin_layout Description
10814 \begin_inset Flex Code
10817 \begin_layout Plain Layout
10824 \begin_inset Flex Code
10827 \begin_layout Plain Layout
10832 , Manual, Static, Top_Environment, Centered_Top_Environment, Counter, Sensitive,
10833 Enumerate, Itemize, Bibliography
10842 \begin_layout Itemize
10843 \begin_inset Flex Code
10846 \begin_layout Plain Layout
10852 means the label is the very first word (up to the first real blank).
10853 Use protected spaces (like
10854 \begin_inset space ~
10857 that one) if you want more than one word as the label.
10861 \begin_layout Itemize
10862 \begin_inset Flex Code
10865 \begin_layout Plain Layout
10871 means the label is simply whatever
10872 \begin_inset Flex Code
10875 \begin_layout Plain Layout
10882 Note that this really is `static'.
10885 \begin_layout Itemize
10886 \begin_inset Flex Code
10889 \begin_layout Plain Layout
10896 \begin_inset Flex Code
10899 \begin_layout Plain Layout
10900 Centered_Top_Environment
10905 are special cases of
10906 \begin_inset Flex Code
10909 \begin_layout Plain Layout
10916 The label will be printed above the paragraph, but only at the top of an
10917 environment or the top of a chain of paragraphs with this style.
10918 This might be used with the
10919 \begin_inset Flex MenuItem
10922 \begin_layout Plain Layout
10928 style, for example.
10931 \begin_layout Itemize
10932 \begin_inset Flex Code
10935 \begin_layout Plain Layout
10941 is a special case for the caption-labels
10942 \begin_inset Quotes eld
10946 \begin_inset Quotes erd
10950 \begin_inset Quotes eld
10954 \begin_inset Quotes erd
10959 \begin_inset Flex Code
10962 \begin_layout Plain Layout
10968 means the (hardcoded) label string depends on the kind of float: It is
10969 hardcoded to be `FloatType N', where N is the value of the counter associated
10973 \begin_layout Itemize
10975 \begin_inset Flex Code
10978 \begin_layout Plain Layout
10984 label type defines automatically numbered labels.
10986 \begin_inset Flex Code
10989 \begin_layout Plain Layout
10995 will be expanded to resolve any counter references it contains: For example,
10997 \begin_inset Quotes eld
11001 \begin_inset Flex Code
11004 \begin_layout Plain Layout
11015 \begin_inset Quotes erd
11020 \begin_inset CommandInset ref
11022 reference "sub:Counters"
11026 for more information on counters.
11029 \begin_layout Itemize
11030 \begin_inset Flex Code
11033 \begin_layout Plain Layout
11039 produces the usual sort of enumeration labels.
11040 At present, it is hardcoded to use Arabic numerals, lowercase letters,
11041 small Roman numerals, and uppercase letters for the four possible depths.
11044 \begin_layout Itemize
11045 \begin_inset Flex Code
11048 \begin_layout Plain Layout
11054 produces various bullets at the different levels.
11055 It is also hardcoded.
11058 \begin_layout Itemize
11059 \begin_inset Flex Code
11062 \begin_layout Plain Layout
11068 is used internally by LyX and should be used only with
11069 \begin_inset Flex Code
11072 \begin_layout Plain Layout
11073 LatexType BibEnvironment
11082 \begin_layout Description
11083 \begin_inset Flex Code
11086 \begin_layout Plain Layout
11092 Note that this will completely override any prior
11093 \begin_inset Flex Code
11096 \begin_layout Plain Layout
11102 declaration for this style.
11104 \begin_inset Quotes eld
11108 \begin_inset Flex Code
11111 \begin_layout Plain Layout
11118 \begin_inset Quotes erd
11123 \begin_inset CommandInset ref
11125 reference "sub:I18n"
11129 for details on its use.
11132 \begin_layout Description
11133 \begin_inset Flex Code
11136 \begin_layout Plain Layout
11142 The name of the corresponding LaTeX stuff.
11143 Either the environment or command name.
11146 \begin_layout Description
11147 \begin_inset Flex Code
11150 \begin_layout Plain Layout
11156 An optional parameter for the corresponding
11157 \begin_inset Flex Code
11160 \begin_layout Plain Layout
11167 This parameter cannot be changed from within LyX.
11170 \begin_layout Description
11171 \begin_inset Flex Code
11174 \begin_layout Plain Layout
11181 \begin_inset CommandInset label
11183 name "des:LatexType"
11188 \begin_inset Flex Code
11191 \begin_layout Plain Layout
11196 , Command, Environment, Item_Environment,
11202 \begin_inset Flex Code
11205 \begin_layout Plain Layout
11206 List_Environment, Bib_Environment
11211 ] How the style should be translated into LaTeX.
11215 \begin_layout Plain Layout
11216 \begin_inset Flex Code
11219 \begin_layout Plain Layout
11225 is perhaps a bit misleading, since these rules apply to SGML classes, too.
11226 Visit the SGML class files for specific examples.
11235 \begin_layout Itemize
11236 \begin_inset Flex Code
11239 \begin_layout Plain Layout
11245 means nothing special.
11249 \begin_layout Itemize
11250 \begin_inset Flex Code
11253 \begin_layout Plain Layout
11260 \begin_inset Flex Code
11263 \begin_layout Plain Layout
11270 {\SpecialChar \ldots{}
11279 \begin_layout Itemize
11280 \begin_inset Flex Code
11283 \begin_layout Plain Layout
11290 \begin_inset Flex Code
11293 \begin_layout Plain Layout
11300 }\SpecialChar \ldots{}
11316 \begin_layout Itemize
11317 \begin_inset Flex Code
11320 \begin_layout Plain Layout
11327 \begin_inset Flex Code
11330 \begin_layout Plain Layout
11337 \begin_inset Flex Code
11340 \begin_layout Plain Layout
11348 is generated for each paragraph of this environment.
11352 \begin_layout Itemize
11353 \begin_inset Flex Code
11356 \begin_layout Plain Layout
11363 \begin_inset Flex Code
11366 \begin_layout Plain Layout
11373 \begin_inset Flex Code
11376 \begin_layout Plain Layout
11382 is passed as an argument to the environment.
11384 \begin_inset Flex Code
11387 \begin_layout Plain Layout
11393 can be defined in the
11394 \begin_inset Flex MenuItem
11397 \begin_layout Plain Layout
11402 \SpecialChar \menuseparator
11408 \begin_inset space ~
11420 \begin_layout Standard
11421 Putting the last few things together, the LaTeX output will be either:
11424 \begin_layout LyX-Code
11427 latexname[latexparam]{\SpecialChar \ldots{}
11431 \begin_layout Standard
11435 \begin_layout LyX-Code
11438 begin{latexname}[latexparam] \SpecialChar \ldots{}
11444 \begin_layout Standard
11445 depending upon the LaTeX type.
11449 \begin_layout Description
11450 \begin_inset Flex Code
11453 \begin_layout Plain Layout
11460 \begin_inset Flex Code
11463 \begin_layout Plain Layout
11469 ] If you put styles into environments, the leftmargins are not simply added,
11470 but added with a factor
11471 \begin_inset Formula $\frac{4}{depth+4}$
11475 Note that this parameter is also used when the margin is defined as
11476 \begin_inset Flex Code
11479 \begin_layout Plain Layout
11486 \begin_inset Flex Code
11489 \begin_layout Plain Layout
11496 Then it is added to the manual or dynamic margin.
11498 \begin_inset Newline newline
11501 The argument is passed as a string.
11503 \begin_inset Quotes eld
11507 \begin_inset Flex Code
11510 \begin_layout Plain Layout
11517 \begin_inset Quotes erd
11520 means that the paragraph is indented with the width of
11521 \begin_inset Quotes eld
11525 \begin_inset Flex Code
11528 \begin_layout Plain Layout
11535 \begin_inset Quotes erd
11538 in the normal font.
11539 You can get a negative width by prefixing the string with
11540 \begin_inset Quotes eld
11544 \begin_inset Flex Code
11547 \begin_layout Plain Layout
11554 \begin_inset Quotes erd
11558 This way was chosen so that the look is the same with each used screen
11563 \begin_layout Description
11564 \begin_inset Flex Code
11567 \begin_layout Plain Layout
11574 \begin_inset Flex Code
11577 \begin_layout Plain Layout
11582 , Manual, Dynamic, First_Dynamic, Right_Address_Box
11588 \begin_inset Newline newline
11591 The kind of margin that the style has on the left side.
11593 \begin_inset Flex Code
11596 \begin_layout Plain Layout
11602 just means a fixed margin.
11604 \begin_inset Flex Code
11607 \begin_layout Plain Layout
11613 means that the left margin depends on the string entered in the
11614 \begin_inset Flex MenuItem
11617 \begin_layout Plain Layout
11618 Edit\SpecialChar \menuseparator
11620 \begin_inset space ~
11629 This is used to typeset nice lists without tabulators.
11631 \begin_inset Flex Code
11634 \begin_layout Plain Layout
11640 means that the margin depends on the size of the label.
11641 This is used for automatic enumerated headlines.
11642 It is obvious that the headline
11643 \begin_inset Quotes eld
11646 5.4.3.2.1 Very long headline
11647 \begin_inset Quotes erd
11650 must have a wider left margin (as wide as
11651 \begin_inset Quotes eld
11655 \begin_inset Quotes erd
11658 plus the space) than
11659 \begin_inset Quotes eld
11662 3.2 Very long headline
11663 \begin_inset Quotes erd
11667 \begin_inset Quotes eld
11671 \begin_inset Quotes erd
11674 are not able to do this.
11676 \begin_inset Flex Code
11679 \begin_layout Plain Layout
11685 is similar, but only the very first row of the paragraph is dynamic, while
11686 the others are static; this is used, for example, for descriptions.
11688 \begin_inset Flex Code
11691 \begin_layout Plain Layout
11697 means the margin is chosen in a way that the longest row of this paragraph
11698 fits to the right margin.
11699 This is used to typeset an address on the right edge of the page.
11702 \begin_layout Description
11703 \begin_inset Flex Code
11706 \begin_layout Plain Layout
11713 \begin_inset Flex Code
11716 \begin_layout Plain Layout
11725 \begin_inset Flex Code
11728 \begin_layout Plain Layout
11734 ] Whether fragile commands in this style should be
11735 \begin_inset Flex Code
11738 \begin_layout Plain Layout
11751 whether this command should itself be protected.)
11754 \begin_layout Description
11755 \begin_inset Flex Code
11758 \begin_layout Plain Layout
11765 \begin_inset Flex Code
11768 \begin_layout Plain Layout
11775 \begin_inset Flex Code
11778 \begin_layout Plain Layout
11786 ] Whether newlines are translated into LaTeX newlines (
11787 \begin_inset Flex Code
11790 \begin_layout Plain Layout
11801 The translation can be switched off to allow more comfortable LaTeX editing
11805 \begin_layout Description
11806 \begin_inset Flex Code
11809 \begin_layout Plain Layout
11816 \begin_inset Flex Code
11819 \begin_layout Plain Layout
11826 \begin_inset Flex Code
11829 \begin_layout Plain Layout
11838 \change_deleted 1414654397 1302985166
11839 Whether the following Paragraph is allowed to indent its very first row.
11841 \begin_inset Flex Code
11844 \begin_layout Plain Layout
11850 means that it is not allowed to do so;
11851 \begin_inset Flex Code
11854 \begin_layout Plain Layout
11860 means it could do so if it wants to.
11861 \change_inserted 1414654397 1302985275
11862 If set to true, and if
11863 \begin_inset Flex Code
11866 \begin_layout Plain Layout
11868 \change_inserted 1414654397 1302985206
11877 \begin_inset Flex Code
11880 \begin_layout Plain Layout
11882 \change_inserted 1414654397 1302985230
11890 ) paragraphs are being indented, then the indentation of such a paragraph
11891 following one of this type will be suppressed.
11892 (So this will not affect the display of non-default paragraphs.)
11897 \begin_layout Description
11898 \begin_inset Flex Code
11901 \begin_layout Plain Layout
11907 Name of a style that has replaced this style.
11908 This is used to rename a style, while keeping backward compatibility.
11911 \begin_layout Description
11912 \begin_inset Flex Code
11915 \begin_layout Plain Layout
11922 \begin_inset Flex Code
11925 \begin_layout Plain Layout
11931 ] The number of optional arguments that can be used with this style.
11932 This is useful for things like section headings, and only makes sense with
11934 Note that, on output, the optional arguments will all precede any required
11935 arguments (see below).
11936 So one can have constructs like:
11940 \begin_layout LyX-Code
11943 mycmd[opt1]{req1}{contents of paragraph}
11946 \begin_layout Standard
11947 but one cannot have things like:
11950 \begin_layout LyX-Code
11953 mycmd[opt1]{req1}[opt2]{contents of paragraph}
11956 \begin_layout Standard
11957 at least, not without ERT (with which you can have anything).
11962 \begin_layout Description
11963 \begin_inset Flex Code
11966 \begin_layout Plain Layout
11973 \begin_inset CommandInset label
11975 name "des:ParbreakIsNewline"
11980 \begin_inset Flex Code
11983 \begin_layout Plain Layout
11992 \begin_inset Flex Code
11995 \begin_layout Plain Layout
12001 ] Indicates that paragraphs will not be separated by an empty line in LaTeX
12002 output, but only by a line break; together with
12003 \begin_inset Flex Code
12006 \begin_layout Plain Layout
12012 , this allows to emulate a plain text editor (like the ERT inset).
12015 \begin_layout Description
12016 \begin_inset Flex Code
12019 \begin_layout Plain Layout
12026 \begin_inset Flex Code
12029 \begin_layout Plain Layout
12035 ] The indent of the very first line of a paragraph.
12037 \begin_inset Flex Code
12040 \begin_layout Plain Layout
12046 will be fixed for a certain style.
12047 The exception is the default style, since the indentation for these paragraphs
12048 can be prohibited with
12049 \begin_inset Flex Code
12052 \begin_layout Plain Layout
12060 \begin_inset Flex Code
12063 \begin_layout Plain Layout
12069 style paragraphs inside environments use the
12070 \begin_inset Flex Code
12073 \begin_layout Plain Layout
12079 of the environment, not their native one.
12081 \begin_inset Flex Code
12084 \begin_layout Plain Layout
12090 paragraphs inside an enumeration are not indented.
12093 \begin_layout Description
12094 \begin_inset Flex Code
12097 \begin_layout Plain Layout
12104 \begin_inset Flex Code
12107 \begin_layout Plain Layout
12113 ] The vertical space between two paragraphs of this style.
12116 \begin_layout Description
12117 \begin_inset Flex Code
12120 \begin_layout Plain Layout
12127 \begin_inset Flex Code
12130 \begin_layout Plain Layout
12136 ] LyX allows the user to choose either
12137 \begin_inset Quotes eld
12141 \begin_inset Quotes erd
12145 \begin_inset Quotes eld
12149 \begin_inset Quotes erd
12152 to typeset a document.
12154 \begin_inset Quotes eld
12158 \begin_inset Quotes erd
12161 is chosen, this value is completely ignored.
12163 \begin_inset Quotes eld
12167 \begin_inset Quotes erd
12170 is chosen, the parindent of a LaTeXtype
12171 \begin_inset Quotes eld
12175 \begin_inset Quotes erd
12178 style is ignored and all paragraphs are separated by this parskip argument.
12179 The vertical space is calculated with
12180 \begin_inset Flex Code
12183 \begin_layout Plain Layout
12185 \begin_inset space ~
12194 \begin_inset Flex Code
12197 \begin_layout Plain Layout
12203 is the height of a row with the normal font.
12204 This way, the look stays the same with different screen fonts.
12207 \begin_layout Description
12208 \begin_inset Flex Code
12211 \begin_layout Plain Layout
12218 \begin_inset CommandInset label
12220 name "des:PassThru"
12225 \begin_inset Flex Code
12228 \begin_layout Plain Layout
12237 \begin_inset Flex Code
12240 \begin_layout Plain Layout
12246 ] Whether the contents of this paragraph should be output in raw form, meaning
12247 without special translations that LaTeX would require.
12250 \begin_layout Description
12251 \begin_inset Flex Code
12254 \begin_layout Plain Layout
12261 \begin_inset CommandInset label
12263 name "des:Preamble"
12267 Information to be included in the LaTeX preamble when this style is used.
12268 Used to define macros, load packages, etc., required by this particular
12271 \begin_inset Quotes eld
12275 \begin_inset Flex Code
12278 \begin_layout Plain Layout
12285 \begin_inset Quotes erd
12291 \begin_layout Description
12292 \begin_inset Flex Code
12295 \begin_layout Plain Layout
12302 \begin_inset Flex Code
12305 \begin_layout Plain Layout
12311 ] The prefix to use when creating labels referring to paragraphs of this
12313 This allows the use of formatted references.
12316 \begin_layout Description
12317 \begin_inset Flex Code
12320 \begin_layout Plain Layout
12327 \begin_inset Flex Code
12330 \begin_layout Plain Layout
12336 ] The number of required arguments that the LaTeX command or environment
12337 corresponding to this style expects.
12338 In the case of a command, these are required arguments
12342 that associated with the content of the paragraph itself.
12343 These do not actually have to be provided: LyX will output empty arguments
12345 Note that optional arguments will be output before required arguments.
12346 See the discussion of the
12347 \begin_inset Flex Code
12350 \begin_layout Plain Layout
12356 tag above for more information.
12359 \begin_layout Description
12360 \begin_inset Flex Code
12363 \begin_layout Plain Layout
12370 \begin_inset Flex Code
12373 \begin_layout Plain Layout
12380 \begin_inset CommandInset label
12382 name "des:Requires"
12386 Whether the style requires the feature
12387 \begin_inset Flex Code
12390 \begin_layout Plain Layout
12397 See the description of
12398 \begin_inset Flex Code
12401 \begin_layout Plain Layout
12408 \begin_inset CommandInset ref
12409 LatexCommand pageref
12410 reference "des:FreeSpacing"
12414 ) for information on `features'.
12418 \begin_layout Description
12419 \begin_inset Flex Code
12422 \begin_layout Plain Layout
12429 \begin_inset Flex Code
12432 \begin_layout Plain Layout
12439 \begin_inset Flex Code
12442 \begin_layout Plain Layout
12451 \begin_layout Description
12452 \begin_inset Flex Code
12455 \begin_layout Plain Layout
12462 \begin_inset Flex Code
12465 \begin_layout Plain Layout
12470 , onehalf, double, other
12479 ] This defines what the default spacing should be in the style.
12481 \begin_inset Flex Code
12484 \begin_layout Plain Layout
12491 \begin_inset Flex Code
12494 \begin_layout Plain Layout
12501 \begin_inset Flex Code
12504 \begin_layout Plain Layout
12510 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
12511 If you specify the argument
12512 \begin_inset Flex Code
12515 \begin_layout Plain Layout
12521 , then you should also provide a numerical argument which will be the actual
12523 Note that, contrary to other parameters,
12524 \begin_inset Flex Code
12527 \begin_layout Plain Layout
12533 implies the generation of specific LaTeX code, using the package
12536 \begin_inset Flex Code
12539 \begin_layout Plain Layout
12548 \begin_layout Description
12549 \begin_inset Flex Code
12552 \begin_layout Plain Layout
12559 \begin_inset Flex Code
12562 \begin_layout Plain Layout
12569 \begin_inset Flex Code
12572 \begin_layout Plain Layout
12580 ] Spellcheck paragraphs of this style.
12584 \begin_layout Description
12585 \begin_inset Flex Code
12588 \begin_layout Plain Layout
12594 The font used for the text body .
12596 \begin_inset CommandInset ref
12598 reference "sub:Font-description"
12605 \begin_layout Description
12606 \begin_inset Flex Code
12609 \begin_layout Plain Layout
12618 \begin_inset Flex Code
12621 \begin_layout Plain Layout
12631 The level of the style in the table of contents.
12632 This is used for automatic numbering of section headings.
12635 \begin_layout Description
12636 \begin_inset Flex Code
12639 \begin_layout Plain Layout
12646 \begin_inset Flex Code
12649 \begin_layout Plain Layout
12655 ] The vertical space with which the very first of a chain of paragraphs
12656 with this style is separated from the previous paragraph.
12657 If the previous paragraph has another style, the separations are not simply
12658 added, but the maximum is taken.
12661 \begin_layout Subsection
12662 \begin_inset CommandInset label
12668 Internationalization of Paragraph Styles
12671 \begin_layout Standard
12672 LyX has long supported internationalization of layout information, but,
12673 until version 2.0, this applied only to the user interface and not to, say,
12675 Thus, French authors were forced to resort to ugly hacks if they wanted
12680 1' instead of `Theorem 1'.
12681 Thanks to Georg Baum, that is no longer the case.
12684 \begin_layout Standard
12686 \begin_inset Flex Code
12689 \begin_layout Plain Layout
12695 defines text that is to appear in the typeset document, it may use
12696 \begin_inset Flex Code
12699 \begin_layout Plain Layout
12706 \begin_inset Flex Code
12709 \begin_layout Plain Layout
12715 to support non-English and even multi-language documents correctly.
12716 The following excerpt (from the
12717 \begin_inset Flex Code
12720 \begin_layout Plain Layout
12726 file) shows how this works:
12729 \begin_layout LyX-Code
12734 \begin_layout LyX-Code
12737 theoremstyle{remark}
12740 \begin_layout LyX-Code
12743 newtheorem{claim}[thm]{
12750 \begin_layout LyX-Code
12754 \begin_layout LyX-Code
12758 \begin_layout LyX-Code
12763 claimname}{_(Claim)}
12766 \begin_layout LyX-Code
12770 \begin_layout LyX-Code
12774 \begin_layout LyX-Code
12783 claimname}{_(Claim)}}
12786 \begin_layout LyX-Code
12791 \begin_layout Standard
12792 In principle, any legal LaTeX may appear in the
12793 \begin_inset Flex Code
12796 \begin_layout Plain Layout
12803 \begin_inset Flex Code
12806 \begin_layout Plain Layout
12812 tags, but in practice they will typically look as they do here.
12813 The key to correct translation of the typeset text is the definition of
12815 \begin_inset Flex Code
12818 \begin_layout Plain Layout
12827 \begin_inset Flex Code
12830 \begin_layout Plain Layout
12842 \begin_layout Standard
12844 \begin_inset Flex Code
12847 \begin_layout Plain Layout
12853 tag provides for internationalization based upon the overall language of
12855 The contents of the tag will be included in the preamble, just as with
12857 \begin_inset Flex Code
12860 \begin_layout Plain Layout
12867 What makes it special is the use of the
12868 \begin_inset Quotes eld
12872 \begin_inset Quotes erd
12876 \begin_inset Flex Code
12879 \begin_layout Plain Layout
12885 , which will be replaced, when LyX produces LaTeX output, with the translation
12886 of its argument into the document language.
12889 \begin_layout Standard
12891 \begin_inset Flex Code
12894 \begin_layout Plain Layout
12900 tag is more complex, since it is meant to provide support for multi-language
12901 documents and so offers an interface to the
12902 \begin_inset Flex Code
12905 \begin_layout Plain Layout
12912 Its contents will be added to the preamble once for each language that
12913 appears in the document.
12914 In this case, the argument to
12915 \begin_inset Flex Code
12918 \begin_layout Plain Layout
12924 will be replaced with its translation into the language in question; the
12926 \begin_inset Flex Code
12929 \begin_layout Plain Layout
12935 is replaced by the language name (as used by the babel package).
12938 \begin_layout Standard
12939 A German document that also included a French section would thus have the
12940 following in the preamble:
12943 \begin_layout LyX-Code
12952 claimname}{Affirmation}}
12960 claimname}{Behauptung}}
12964 claimname}{Behauptung}
12967 \begin_layout Standard
12969 \begin_inset Flex Code
12972 \begin_layout Plain Layout
12978 will then conspire to produce the correct text in the output.
12981 \begin_layout Standard
12982 One important point to note here is that the translations are provided by
12983 LyX itself, through the same mechanism it uses for internationalization
12984 of the user interface.
12985 This means, in effect, that
12986 \begin_inset Flex Code
12989 \begin_layout Plain Layout
12996 \begin_inset Flex Code
12999 \begin_layout Plain Layout
13005 are really only of use in layout files that are provided with LyX, since
13006 text entered in user-created layout files will not be seen by LyX's internation
13007 alization routines.
13008 That said, however, any layout created with the intention that it will
13009 be included with LyX should use these tags where appropriate.
13012 \begin_layout Subsection
13014 \begin_inset CommandInset label
13023 \begin_layout Standard
13024 Since version 1.3.0 of LyX, it is has been both possible and necessary to
13025 define the floats (
13026 \begin_inset Flex MenuItem
13029 \begin_layout Plain Layout
13036 \begin_inset Flex MenuItem
13039 \begin_layout Plain Layout
13045 , \SpecialChar \ldots{}
13046 ) in the text class itself.
13047 Standard floats are included in the file
13048 \begin_inset Flex Code
13051 \begin_layout Plain Layout
13057 , so you may have to do no more than add
13060 \begin_layout LyX-Code
13061 Input stdfloats.inc
13064 \begin_layout Standard
13065 to your layout file.
13066 If you want to implement a text class that proposes some other float types
13067 (like the AGU class bundled with LyX), the information below will hopefully
13071 \begin_layout Description
13072 \begin_inset Flex Code
13075 \begin_layout Plain Layout
13082 \begin_inset Flex Code
13085 \begin_layout Plain Layout
13092 \begin_inset Quotes erd
13096 \begin_inset Quotes erd
13099 ] The file name extension of an auxiliary file for the list of figures (or
13101 LaTeX writes the captions to this file.
13104 \begin_layout Description
13105 \begin_inset Flex Code
13108 \begin_layout Plain Layout
13115 \begin_inset Flex Code
13118 \begin_layout Plain Layout
13125 \begin_inset Quotes erd
13129 \begin_inset Quotes erd
13132 ] The string that will be used in the menus and also for the caption.
13133 This is translated to the current language if babel is used.
13136 \begin_layout Description
13137 \begin_inset Flex Code
13140 \begin_layout Plain Layout
13146 These are used for XHTML output.
13148 \begin_inset CommandInset ref
13150 reference "sec:Tags-for-XHTML"
13157 \begin_layout Description
13158 \begin_inset Flex Code
13161 \begin_layout Plain Layout
13170 \begin_inset Flex Code
13173 \begin_layout Plain Layout
13182 \begin_inset Flex Code
13185 \begin_layout Plain Layout
13191 ] Indicates whether the float is already defined in the document class or
13192 if we instead need to load
13193 \begin_inset Flex Code
13196 \begin_layout Plain Layout
13202 and use what it provides to define it on-the-fly.
13204 \begin_inset Flex Code
13207 \begin_layout Plain Layout
13214 \begin_inset Flex Code
13217 \begin_layout Plain Layout
13224 It should be set to
13225 \begin_inset Flex Code
13228 \begin_layout Plain Layout
13234 if the float is already defined by the LaTeX document class.
13237 \begin_layout Description
13238 \begin_inset Flex Code
13241 \begin_layout Plain Layout
13248 \begin_inset Flex Code
13251 \begin_layout Plain Layout
13258 \begin_inset Quotes erd
13262 \begin_inset Quotes erd
13265 ] The command used to generate a list of floats of this type; the leading
13268 ' should be omitted.
13274 \begin_inset Flex Code
13277 \begin_layout Plain Layout
13283 is false, since there is no standard way to generate this command.
13285 \begin_inset Flex Code
13288 \begin_layout Plain Layout
13294 is true, since in that case there is a standard way to define the command.
13297 \begin_layout Description
13298 \begin_inset Flex Code
13301 \begin_layout Plain Layout
13308 \begin_inset Flex Code
13311 \begin_layout Plain Layout
13318 \begin_inset Quotes erd
13322 \begin_inset Quotes erd
13325 ] A title for a list of floats of this kind (list of figures, tables, or
13327 It is used for the screen label within LyX; it is passed to LaTeX for use
13328 as the title there; and it is used as the title in XHTML output.
13329 It will be translated to the document language.
13332 \begin_layout Description
13333 \begin_inset Flex Code
13336 \begin_layout Plain Layout
13343 \begin_inset Flex Code
13346 \begin_layout Plain Layout
13353 \begin_inset Quotes erd
13357 \begin_inset Quotes erd
13360 ] This (optional) argument determines whether floats of this class will
13361 be numbered within some sectional unit of the document.
13362 For example, if within is equal to
13363 \begin_inset Flex Code
13366 \begin_layout Plain Layout
13372 , the floats will be numbered within chapters.
13376 \begin_layout Description
13377 \begin_inset Flex Code
13380 \begin_layout Plain Layout
13387 \begin_inset Flex Code
13390 \begin_layout Plain Layout
13397 \begin_inset Quotes erd
13401 \begin_inset Quotes erd
13404 ] The default placement for the given class of floats.
13405 The string should be as in standard LaTeX:
13406 \begin_inset Flex Code
13409 \begin_layout Plain Layout
13416 \begin_inset Flex Code
13419 \begin_layout Plain Layout
13426 \begin_inset Flex Code
13429 \begin_layout Plain Layout
13436 \begin_inset Flex Code
13439 \begin_layout Plain Layout
13445 for top, bottom, page, and here, respectively.
13449 \begin_layout Plain Layout
13450 Note that the order of these letters in the string is irrelevant, like in
13456 On top of that there is a new type,
13457 \begin_inset Flex Code
13460 \begin_layout Plain Layout
13466 , which does not really correspond to a float, since it means: put it
13467 \begin_inset Quotes eld
13471 \begin_inset Quotes erd
13475 Note however that the
13476 \begin_inset Flex Code
13479 \begin_layout Plain Layout
13485 specifier is special and, because of implementation details, cannot be
13486 used in non-built in float types.
13487 If you do not understand what this means, just use
13488 \begin_inset Quotes eld
13492 \begin_inset Flex Code
13495 \begin_layout Plain Layout
13502 \begin_inset Quotes erd
13508 \begin_layout Description
13509 \begin_inset Flex Code
13512 \begin_layout Plain Layout
13519 \begin_inset Flex Code
13522 \begin_layout Plain Layout
13528 ] The prefix to use when creating labels referring to floats of this type.
13529 This allows the use of formatted references.
13530 Note that you can remove any
13531 \begin_inset Flex Code
13534 \begin_layout Plain Layout
13540 set by a copied style by using the special value
13541 \begin_inset Quotes eld
13545 \begin_inset Quotes erd
13548 , which must be all caps.
13551 \begin_layout Description
13552 \begin_inset Flex Code
13555 \begin_layout Plain Layout
13562 \begin_inset Flex Code
13565 \begin_layout Plain Layout
13572 \begin_inset Quotes erd
13576 \begin_inset Quotes erd
13579 ] The style used when defining the float using
13580 \begin_inset Flex Code
13583 \begin_layout Plain Layout
13594 \begin_layout Description
13595 \begin_inset Flex Code
13598 \begin_layout Plain Layout
13605 \begin_inset Flex Code
13608 \begin_layout Plain Layout
13615 \begin_inset Quotes erd
13619 \begin_inset Quotes erd
13623 \begin_inset Quotes eld
13627 \begin_inset Quotes erd
13630 of the new class of floats, like program or algorithm.
13631 After the appropriate
13632 \begin_inset Flex Code
13635 \begin_layout Plain Layout
13644 \begin_inset Flex Code
13647 \begin_layout Plain Layout
13656 \begin_inset Flex Code
13659 \begin_layout Plain Layout
13670 \begin_layout Description
13671 \begin_inset Flex Code
13674 \begin_layout Plain Layout
13681 \begin_inset Flex Code
13684 \begin_layout Plain Layout
13691 \begin_inset Flex Code
13694 \begin_layout Plain Layout
13702 ] Tells us whether this float is defined using the facilities provided by
13704 \begin_inset Flex Code
13707 \begin_layout Plain Layout
13713 , either by the class file or a package, or on-the-fly by LyX itself.
13716 \begin_layout Standard
13717 Note that defining a float with type
13718 \begin_inset Flex Code
13721 \begin_layout Plain Layout
13729 automatically defines the corresponding counter with name
13730 \begin_inset Flex Code
13733 \begin_layout Plain Layout
13744 \begin_layout Subsection
13745 Flex insets and InsetLayout
13746 \begin_inset CommandInset label
13748 name "sub:Flex-insets-and"
13755 \begin_layout Standard
13756 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
13757 these are called Flex insets.
13761 \begin_layout Standard
13762 Flex insets come in three different kinds:
13765 \begin_layout Itemize
13767 \begin_inset Flex Code
13770 \begin_layout Plain Layout
13776 ): These define semantic markup corresponding to such LaTeX commands as
13778 \begin_inset Flex Code
13781 \begin_layout Plain Layout
13790 \begin_inset Flex Code
13793 \begin_layout Plain Layout
13804 \begin_layout Itemize
13806 \begin_inset Flex Code
13809 \begin_layout Plain Layout
13815 ): These can be used to define custom collapsible insets, similar to TeX
13816 code, footnote, and the like.
13817 An obvious example is an endnote inset, which is defined in the
13818 \begin_inset Flex Code
13821 \begin_layout Plain Layout
13830 \begin_layout Itemize
13832 \begin_inset Flex Code
13835 \begin_layout Plain Layout
13841 ): For use with DocBook classes.
13844 \begin_layout Standard
13845 Flex insets are defined using the
13846 \begin_inset Flex Code
13849 \begin_layout Plain Layout
13855 tag, which shall be explained in a moment.
13858 \begin_layout Standard
13860 \begin_inset Flex Code
13863 \begin_layout Plain Layout
13869 tag also serves another function: It can be used to customize the general
13870 layout of many different types of insets.
13872 \begin_inset Flex Code
13875 \begin_layout Plain Layout
13881 can be used to customize the layout parameters for footnotes, marginal
13882 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
13883 boxes, tables, algorithms, URLs, and optional arguments, as well as to
13884 define Flex insets.
13887 \begin_layout Standard
13889 \begin_inset Flex Code
13892 \begin_layout Plain Layout
13898 definition must begin with a line of the form:
13901 \begin_layout LyX-Code
13905 \begin_layout Standard
13907 \begin_inset Flex Code
13910 \begin_layout Plain Layout
13916 indicates the inset whose layout is being defined, and here there are two
13920 \begin_layout Enumerate
13921 The layout for a pre-existing inset is being modified.
13922 In this case, can be
13923 \begin_inset Flex Code
13926 \begin_layout Plain Layout
13932 any one of the following:
13933 \begin_inset Flex Code
13936 \begin_layout Plain Layout
13943 \begin_inset Flex Code
13946 \begin_layout Plain Layout
13953 \begin_inset Flex Code
13956 \begin_layout Plain Layout
13963 \begin_inset Flex Code
13966 \begin_layout Plain Layout
13973 \begin_inset Flex Code
13976 \begin_layout Plain Layout
13983 \begin_inset Flex Code
13986 \begin_layout Plain Layout
13993 \begin_inset Flex Code
13996 \begin_layout Plain Layout
14003 \begin_inset Flex Code
14006 \begin_layout Plain Layout
14013 \begin_inset Flex Code
14016 \begin_layout Plain Layout
14023 \begin_inset Flex Code
14026 \begin_layout Plain Layout
14033 \begin_inset Flex Code
14036 \begin_layout Plain Layout
14043 \begin_inset Flex Code
14046 \begin_layout Plain Layout
14053 \begin_inset Flex Code
14056 \begin_layout Plain Layout
14063 \begin_inset Flex Code
14066 \begin_layout Plain Layout
14073 \begin_inset Flex Code
14076 \begin_layout Plain Layout
14083 \begin_inset Flex Code
14086 \begin_layout Plain Layout
14093 \begin_inset Flex Code
14096 \begin_layout Plain Layout
14103 \begin_inset Flex Code
14106 \begin_layout Plain Layout
14113 \begin_inset Flex Code
14116 \begin_layout Plain Layout
14123 \begin_inset Flex Code
14126 \begin_layout Plain Layout
14135 \begin_layout Enumerate
14136 The layout for a Flex inset is being defined.
14138 \begin_inset Flex Code
14141 \begin_layout Plain Layout
14147 must be of the form
14148 \begin_inset Quotes eld
14152 \begin_inset Flex Code
14155 \begin_layout Plain Layout
14162 \begin_inset Quotes erd
14166 \begin_inset Flex Code
14169 \begin_layout Plain Layout
14175 may be be any valid identifier not used by a pre-existing Flex inset.
14176 The identifier may include spaces, but in that case the whole thing must
14177 be wrapped in quotes.
14178 Note that the definition of a flex inset
14183 \begin_inset Flex Code
14186 \begin_layout Plain Layout
14192 entry, declaring which type of inset it defines.
14195 \begin_layout Standard
14197 \begin_inset Flex Code
14200 \begin_layout Plain Layout
14206 definition can contain the following entries:
14209 \begin_layout Description
14210 \begin_inset Flex Code
14213 \begin_layout Plain Layout
14219 The color for the inset's background.
14220 The valid colors are defined in
14221 \begin_inset Flex Code
14224 \begin_layout Plain Layout
14233 \begin_layout Description
14234 \begin_inset Flex Code
14237 \begin_layout Plain Layout
14244 \begin_inset Flex Code
14247 \begin_layout Plain Layout
14256 \begin_inset Flex Code
14259 \begin_layout Plain Layout
14265 ] Whether to use the content of the inset as the label, when the inset is
14270 \begin_layout Description
14271 \begin_inset Flex Code
14274 \begin_layout Plain Layout
14280 As with paragraph styles (see page
14281 \begin_inset CommandInset ref
14283 reference "des:CopyStyle"
14290 \begin_layout Description
14291 \begin_inset Flex Code
14294 \begin_layout Plain Layout
14301 \begin_inset Flex Code
14304 \begin_layout Plain Layout
14313 \begin_inset Flex Code
14316 \begin_layout Plain Layout
14322 ] Indicates whether the user may employ the Paragraph Settings dialog to
14323 customize the paragraph.
14326 \begin_layout Description
14327 \begin_inset Flex Code
14330 \begin_layout Plain Layout
14337 \begin_inset Flex Code
14340 \begin_layout Plain Layout
14347 \begin_inset Flex Code
14350 \begin_layout Plain Layout
14357 \begin_inset Flex Code
14360 \begin_layout Plain Layout
14366 , describing the rendering style used for the inset's frame and buttons.
14367 Footnotes generally use
14368 \begin_inset Flex Code
14371 \begin_layout Plain Layout
14377 , ERT insets generally
14378 \begin_inset Flex Code
14381 \begin_layout Plain Layout
14387 , and character styles
14388 \begin_inset Flex Code
14391 \begin_layout Plain Layout
14400 \begin_layout Description
14401 \begin_inset Flex Code
14404 \begin_layout Plain Layout
14411 \begin_inset Flex Code
14414 \begin_layout Plain Layout
14421 \begin_inset Flex Code
14424 \begin_layout Plain Layout
14433 \begin_inset Flex Code
14436 \begin_layout Plain Layout
14443 \begin_inset Flex Code
14446 \begin_layout Plain Layout
14453 Indicates whether the environment will stand on its own in LaTeX output
14454 or will appear inline with the surrounding text.
14455 If set to false, it is supposed that the LaTeX environment ignores white
14456 space (including one newline character) after the
14457 \begin_inset Flex Code
14460 \begin_layout Plain Layout
14473 \begin_inset Flex Code
14476 \begin_layout Plain Layout
14492 \begin_layout Description
14493 \begin_inset Flex Code
14496 \begin_layout Plain Layout
14502 Required at the end of the InsetLayout declarations.
14505 \begin_layout Description
14506 \begin_inset Flex Code
14509 \begin_layout Plain Layout
14515 The font used for both the text body
14521 \begin_inset space ~
14525 \begin_inset CommandInset ref
14527 reference "sub:Font-description"
14532 Note that defining this font automatically defines the
14533 \begin_inset Flex Code
14536 \begin_layout Plain Layout
14542 to the same value, so define this first and define
14543 \begin_inset Flex Code
14546 \begin_layout Plain Layout
14552 later if you want them to be different.
14555 \begin_layout Description
14556 \begin_inset Flex Code
14559 \begin_layout Plain Layout
14566 \begin_inset Quotes eld
14570 \begin_inset Quotes erd
14573 language, leading to Left-to-Right (latin) output, e.
14574 \begin_inset space \thinspace{}
14578 \begin_inset space \space{}
14581 in TeX code or URL.
14585 \begin_layout Description
14586 \begin_inset Flex Code
14589 \begin_layout Plain Layout
14596 \begin_inset Flex Code
14599 \begin_layout Plain Layout
14608 \begin_inset Flex Code
14611 \begin_layout Plain Layout
14617 ] Indicates whether the
14618 \begin_inset Flex Code
14621 \begin_layout Plain Layout
14627 should be used or, instead, the user can change the paragraph style used
14632 \begin_layout Description
14633 \begin_inset Flex Code
14636 \begin_layout Plain Layout
14642 As with paragraph styles (see page
14643 \begin_inset CommandInset ref
14644 LatexCommand pageref
14645 reference "des:FreeSpacing"
14653 \begin_layout Description
14654 \begin_inset Flex Code
14657 \begin_layout Plain Layout
14663 These tags control XHTML output.
14665 \begin_inset CommandInset ref
14667 reference "sec:Tags-for-XHTML"
14674 \begin_layout Description
14675 \begin_inset Flex Code
14678 \begin_layout Plain Layout
14685 \begin_inset Flex Code
14688 \begin_layout Plain Layout
14697 \begin_inset Flex Code
14700 \begin_layout Plain Layout
14706 ] Whether to include the contents of this inset in the strings generated
14707 for the `Outline' pane.
14708 One would not, for example, want the content of a footnote in a section
14709 header to be included in the TOC displayed in the outline, but one would
14710 normally want the content of a character style displayed.
14711 Default is false: not to include.
14714 \begin_layout Description
14715 \begin_inset Flex Code
14718 \begin_layout Plain Layout
14724 As with paragraph styles (see page
14725 \begin_inset CommandInset ref
14726 LatexCommand pageref
14727 reference "des:KeepEmpty"
14735 \begin_layout Description
14736 \begin_inset Flex Code
14739 \begin_layout Plain Layout
14745 The font used for the label.
14747 \begin_inset space ~
14751 \begin_inset CommandInset ref
14753 reference "sub:Font-description"
14758 Note that this definition can never appear before
14759 \begin_inset Flex Code
14762 \begin_layout Plain Layout
14768 , lest it be ineffective.
14771 \begin_layout Description
14772 \begin_inset Flex Code
14775 \begin_layout Plain Layout
14781 What will be displayed on the button or elsewhere as the inset label.
14783 \begin_inset Flex Code
14786 \begin_layout Plain Layout
14793 \begin_inset Flex Code
14796 \begin_layout Plain Layout
14802 ) modify this label on the fly.
14805 \begin_layout Description
14806 \begin_inset Flex Code
14809 \begin_layout Plain Layout
14815 The name of the corresponding LaTeX stuff.
14816 Either the environment or command name.
14819 \begin_layout Description
14820 \begin_inset Flex Code
14823 \begin_layout Plain Layout
14829 The optional parameter for the corresponding
14830 \begin_inset Flex Code
14833 \begin_layout Plain Layout
14839 stuff, including possible bracket pairs like
14840 \begin_inset Flex Code
14843 \begin_layout Plain Layout
14850 This parameter cannot be changed from within LyX.
14853 \begin_layout Description
14854 \begin_inset Flex Code
14857 \begin_layout Plain Layout
14863 As with paragraph styles (see page
14864 \begin_inset CommandInset ref
14865 LatexCommand pageref
14866 reference "des:LatexType"
14873 \begin_layout Description
14874 \begin_inset Flex Code
14877 \begin_layout Plain Layout
14884 \begin_inset Flex Code
14887 \begin_layout Plain Layout
14894 \begin_inset Flex Code
14897 \begin_layout Plain Layout
14904 \begin_inset Flex Code
14907 \begin_layout Plain Layout
14914 \begin_inset Flex Code
14917 \begin_layout Plain Layout
14923 (indicating a dummy definition ending definitions of charstyles, etc).
14924 This entry is required in and is only meaningful for Flex insets.
14925 Among other things, it determines on which menu this inset will appear.
14927 \begin_inset Flex Code
14930 \begin_layout Plain Layout
14937 \begin_inset Flex Code
14940 \begin_layout Plain Layout
14947 \begin_inset Flex Code
14950 \begin_layout Plain Layout
14958 \begin_inset Flex Code
14961 \begin_layout Plain Layout
14967 can be set to true for charstyle insets, if you wish, by setting it
14972 \begin_inset Flex Code
14975 \begin_layout Plain Layout
14984 \begin_layout Description
14985 \begin_inset Flex Code
14988 \begin_layout Plain Layout
14995 \begin_inset Flex Code
14998 \begin_layout Plain Layout
15007 \begin_inset Flex Code
15010 \begin_layout Plain Layout
15016 ] Whether multiple paragraphs are permitted in this inset.
15018 \begin_inset Flex Code
15021 \begin_layout Plain Layout
15027 to the same value and
15028 \begin_inset Flex Code
15031 \begin_layout Plain Layout
15037 to the opposite value.
15038 These can be reset to other values, if they are used
15043 \begin_inset Flex Code
15046 \begin_layout Plain Layout
15056 \begin_layout Description
15057 \begin_inset Flex Code
15060 \begin_layout Plain Layout
15067 \begin_inset Flex Code
15070 \begin_layout Plain Layout
15079 \begin_inset Flex Code
15082 \begin_layout Plain Layout
15088 ] Whether fragile commands in this inset should be
15089 \begin_inset Flex Code
15092 \begin_layout Plain Layout
15105 whether the command should itself be protected.) Default is false.
15108 \begin_layout Description
15109 \begin_inset Flex Code
15112 \begin_layout Plain Layout
15119 \begin_inset Flex Code
15122 \begin_layout Plain Layout
15131 \begin_inset Flex Code
15134 \begin_layout Plain Layout
15140 ] As with paragraph styles (see page
15141 \begin_inset CommandInset ref
15142 LatexCommand pageref
15143 reference "des:ParbreakIsNewline"
15151 \begin_layout Description
15152 \begin_inset Flex Code
15155 \begin_layout Plain Layout
15162 \begin_inset Flex Code
15165 \begin_layout Plain Layout
15174 \begin_inset Flex Code
15177 \begin_layout Plain Layout
15183 ] As with paragraph styles (see page
15184 \begin_inset CommandInset ref
15185 LatexCommand pageref
15186 reference "des:PassThru"
15194 \begin_layout Description
15195 \begin_inset Flex Code
15198 \begin_layout Plain Layout
15204 As with paragraph styles (see page
15205 \begin_inset CommandInset ref
15206 LatexCommand pageref
15207 reference "des:Preamble"
15214 \begin_layout Description
15215 \begin_inset Flex Code
15218 \begin_layout Plain Layout
15225 \begin_inset Flex Code
15228 \begin_layout Plain Layout
15234 ] The prefix to use when creating labels referring to insets of this type.
15235 This allows the use of formatted references.
15238 \begin_layout Description
15239 \begin_inset Flex Code
15242 \begin_layout Plain Layout
15249 \begin_inset Flex Code
15252 \begin_layout Plain Layout
15258 ] As with paragraph styles (see page
15259 \begin_inset CommandInset ref
15260 LatexCommand pageref
15261 reference "des:Requires"
15268 \begin_layout Description
15269 \begin_inset Flex Code
15272 \begin_layout Plain Layout
15279 \begin_inset Flex Code
15282 \begin_layout Plain Layout
15289 \begin_inset Flex Code
15292 \begin_layout Plain Layout
15300 ] Whether this inset should use the font of its surrounding environment
15302 Default is true: uses its own.
15305 \begin_layout Description
15306 \begin_inset Flex Code
15309 \begin_layout Plain Layout
15316 \begin_inset Flex Code
15319 \begin_layout Plain Layout
15326 \begin_inset Flex Code
15329 \begin_layout Plain Layout
15337 ] Spellcheck the contents of this inset.
15341 \begin_layout Subsection
15343 \begin_inset CommandInset label
15345 name "sub:Counters"
15352 \begin_layout Standard
15353 Since version 1.3.0 of LyX, it is both possible and necessary to define the
15355 \begin_inset Flex MenuItem
15358 \begin_layout Plain Layout
15365 \begin_inset Flex MenuItem
15368 \begin_layout Plain Layout
15374 , \SpecialChar \ldots{}
15375 ) in the text class itself.
15376 The standard counters are defined in the file
15377 \begin_inset Flex Code
15380 \begin_layout Plain Layout
15386 , so you may have to do no more than add
15389 \begin_layout LyX-Code
15390 Input stdcounters.inc
15393 \begin_layout Standard
15394 to your layout file to get them to work.
15395 But if you want to define custom counters, then you can do so.
15396 The counter declaration must begin with:
15399 \begin_layout LyX-Code
15400 Counter CounterName
15403 \begin_layout Standard
15405 \begin_inset Flex Code
15408 \begin_layout Plain Layout
15414 ' is replaced by the name of the counter.
15415 And it must end with
15416 \begin_inset Quotes eld
15420 \begin_inset Flex Code
15423 \begin_layout Plain Layout
15430 \begin_inset Quotes erd
15434 The following parameters can also be used:
15437 \begin_layout Description
15438 \begin_inset Flex Code
15441 \begin_layout Plain Layout
15448 \begin_inset Flex Code
15451 \begin_layout Plain Layout
15458 \begin_inset Quotes erd
15462 \begin_inset Quotes erd
15465 ] When defined, this string defines how the counter is displayed.
15466 Setting this value sets
15467 \begin_inset Flex Code
15470 \begin_layout Plain Layout
15471 LabelStringAppendix
15477 The following special constructs can be used in the string:
15481 \begin_layout Itemize
15482 \begin_inset Flex Code
15485 \begin_layout Plain Layout
15493 will be replaced by the expansion of the
15494 \begin_inset Flex Code
15497 \begin_layout Plain Layout
15504 \begin_inset Flex Code
15507 \begin_layout Plain Layout
15508 LabelStringAppendix
15514 \begin_inset Flex Code
15517 \begin_layout Plain Layout
15527 \begin_layout Itemize
15528 counter values can be expressed using LaTeX-like macros
15529 \begin_inset Flex Code
15532 \begin_layout Plain Layout
15549 \begin_inset Flex Code
15552 \begin_layout Plain Layout
15564 \begin_layout Plain Layout
15574 Actually, the situation is a bit more complicated: any
15593 other than those described below will produce arabic numerals.
15594 It would not be surprising to see this change in the future.
15600 \begin_inset Flex Code
15603 \begin_layout Plain Layout
15609 : 1, 2, 3,\SpecialChar \ldots{}
15611 \begin_inset Flex Code
15614 \begin_layout Plain Layout
15620 for lower-case letters: a, b, c, \SpecialChar \ldots{}
15622 \begin_inset Flex Code
15625 \begin_layout Plain Layout
15631 for upper-case letters: A, B, C, \SpecialChar \ldots{}
15633 \begin_inset Flex Code
15636 \begin_layout Plain Layout
15642 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
15644 \begin_inset Flex Code
15647 \begin_layout Plain Layout
15653 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
15655 \begin_inset Flex Code
15658 \begin_layout Plain Layout
15664 for hebrew numerals.
15668 \begin_layout Standard
15669 If LabelString is not defined, a default value is constructed as follows:
15670 if the counter has a master counter
15671 \begin_inset Flex Code
15674 \begin_layout Plain Layout
15681 \begin_inset Flex Code
15684 \begin_layout Plain Layout
15691 \begin_inset Flex Code
15694 \begin_layout Plain Layout
15704 is used; otherwise the string
15705 \begin_inset Flex Code
15708 \begin_layout Plain Layout
15719 \begin_layout Description
15720 \begin_inset Flex Code
15723 \begin_layout Plain Layout
15724 LabelStringAppendix
15730 \begin_inset Flex Code
15733 \begin_layout Plain Layout
15740 \begin_inset Quotes erd
15744 \begin_inset Quotes erd
15748 \begin_inset Flex Code
15751 \begin_layout Plain Layout
15757 , but for use in the Appendix.
15760 \begin_layout Description
15761 \begin_inset Flex Code
15764 \begin_layout Plain Layout
15771 \begin_inset Flex Code
15774 \begin_layout Plain Layout
15781 \begin_inset Quotes erd
15785 \begin_inset Quotes erd
15788 ] A format for use with formatted references to this counter.
15789 For example, one might want to have references to section numbers appear
15791 \begin_inset Quotes eld
15795 \begin_inset Quotes erd
15799 The string should contain
15800 \begin_inset Quotes eld
15804 \begin_inset Quotes erd
15808 This will be replaced by the counter number itself.
15809 So, for sections, it would be: Section ##.
15812 \begin_layout Description
15813 \begin_inset Flex Code
15816 \begin_layout Plain Layout
15823 \begin_inset Flex Code
15826 \begin_layout Plain Layout
15833 \begin_inset Quotes erd
15837 \begin_inset Quotes erd
15840 ] If this is set to the name of another counter, the present counter will
15841 be reset every time the other one is increased.
15843 \begin_inset Flex Code
15846 \begin_layout Plain Layout
15853 \begin_inset Flex Code
15856 \begin_layout Plain Layout
15865 \begin_layout Subsection
15867 \begin_inset CommandInset label
15869 name "sub:Font-description"
15876 \begin_layout Standard
15877 A font description looks like this:
15880 \begin_layout LyX-Code
15890 \begin_layout LyX-Code
15894 \begin_layout LyX-Code
15898 \begin_layout Standard
15899 The following commands are available:
15902 \begin_layout Description
15903 \begin_inset Flex Code
15906 \begin_layout Plain Layout
15913 \begin_inset Flex Code
15916 \begin_layout Plain Layout
15925 \begin_inset Flex Code
15928 \begin_layout Plain Layout
15935 \begin_inset Flex Code
15938 \begin_layout Plain Layout
15945 \begin_inset Flex Code
15948 \begin_layout Plain Layout
15955 \begin_inset Flex Code
15958 \begin_layout Plain Layout
15965 \begin_inset Flex Code
15968 \begin_layout Plain Layout
15975 \begin_inset Flex Code
15978 \begin_layout Plain Layout
15985 \begin_inset Flex Code
15988 \begin_layout Plain Layout
15995 \begin_inset Flex Code
15998 \begin_layout Plain Layout
16007 \begin_layout Description
16008 \begin_inset Flex Code
16011 \begin_layout Plain Layout
16018 \begin_inset Flex Code
16021 \begin_layout Plain Layout
16030 \begin_inset Flex Code
16033 \begin_layout Plain Layout
16040 \begin_inset Flex Code
16043 \begin_layout Plain Layout
16052 \begin_layout Description
16053 \begin_inset Flex Code
16056 \begin_layout Plain Layout
16063 \begin_inset Flex Code
16066 \begin_layout Plain Layout
16072 ] Valid arguments are:
16073 \begin_inset Flex Code
16076 \begin_layout Plain Layout
16083 \begin_inset Flex Code
16086 \begin_layout Plain Layout
16093 \begin_inset Flex Code
16096 \begin_layout Plain Layout
16103 \begin_inset Flex Code
16106 \begin_layout Plain Layout
16113 \begin_inset Flex Code
16116 \begin_layout Plain Layout
16123 \begin_inset Flex Code
16126 \begin_layout Plain Layout
16133 Each of these turns on or off the corresponding attribute.
16135 \begin_inset Flex Code
16138 \begin_layout Plain Layout
16144 turns on emphasis, and
16145 \begin_inset Flex Code
16148 \begin_layout Plain Layout
16156 \begin_inset Newline newline
16159 If the latter seems puzzling, remember that the font settings for the present
16160 context are generally inherited from the surrounding context.
16162 \begin_inset Flex Code
16165 \begin_layout Plain Layout
16171 would turn off the emphasis that was anyway in effect, say, in a theorem
16175 \begin_layout Description
16176 \begin_inset Flex Code
16179 \begin_layout Plain Layout
16186 \begin_inset Flex Code
16189 \begin_layout Plain Layout
16198 \begin_inset Flex Code
16201 \begin_layout Plain Layout
16210 \begin_layout Description
16211 \begin_inset Flex Code
16214 \begin_layout Plain Layout
16221 \begin_inset Flex Code
16224 \begin_layout Plain Layout
16233 \begin_inset Flex Code
16236 \begin_layout Plain Layout
16243 \begin_inset Flex Code
16246 \begin_layout Plain Layout
16253 \begin_inset Flex Code
16256 \begin_layout Plain Layout
16265 \begin_layout Description
16266 \begin_inset Flex Code
16269 \begin_layout Plain Layout
16276 \begin_inset Flex Code
16279 \begin_layout Plain Layout
16286 \begin_inset Flex Code
16289 \begin_layout Plain Layout
16296 \begin_inset Flex Code
16299 \begin_layout Plain Layout
16308 \begin_inset Flex Code
16311 \begin_layout Plain Layout
16318 \begin_inset Flex Code
16321 \begin_layout Plain Layout
16328 \begin_inset Flex Code
16331 \begin_layout Plain Layout
16338 \begin_inset Flex Code
16341 \begin_layout Plain Layout
16348 \begin_inset Flex Code
16351 \begin_layout Plain Layout
16360 \begin_layout Subsection
16361 \begin_inset CommandInset label
16363 name "sub:Citation-format-description"
16367 Citation format description
16370 \begin_layout Standard
16372 \begin_inset Flex Code
16375 \begin_layout Plain Layout
16381 blocks are used to describe how bibliographic information should be displayed,
16382 both within LyX itself (in the citation dialog and in tooltips, for example)
16383 and in XHTML output.
16384 Such a block might look like this:
16387 \begin_layout LyX-Code
16391 \begin_layout LyX-Code
16395 \begin_layout LyX-Code
16399 \begin_layout LyX-Code
16403 \begin_layout Standard
16404 The individual lines define how the bibliographic information associated
16405 with an article or book, respectively, is to be displayed, and such a definitio
16406 n can be given for any `entry type' that might be present in a BibTeX file.
16407 LyX defines a default format in the source code that will be used if no
16408 specific definition has been given.
16409 LyX predefines several formats in the file
16410 \begin_inset Flex Code
16413 \begin_layout Plain Layout
16419 , which is included in most of LyX's document classes.
16422 \begin_layout Standard
16423 The definitions use a simple language that allows BibTeX keys to be replaced
16425 Keys should be enclosed in
16426 \begin_inset Flex Code
16429 \begin_layout Plain Layout
16436 \begin_inset Flex Code
16439 \begin_layout Plain Layout
16446 So a simple definition might look like this:
16449 \begin_layout LyX-Code
16451 \begin_inset Quotes eld
16455 \begin_inset Quotes erd
16461 \begin_layout Standard
16462 This would print the author, followed by a comma, followed by the title,
16463 in quotes, followed by a period.
16466 \begin_layout Standard
16467 Of course, sometimes you may want to print a key only if it exists.
16468 This can be done by using a conditional construction, such as:
16469 \begin_inset Flex Code
16472 \begin_layout Plain Layout
16474 \begin_inset space ~
16484 \begin_inset Flex Code
16487 \begin_layout Plain Layout
16493 key exists, then print
16494 \begin_inset Quotes eld
16498 \begin_inset space ~
16502 \begin_inset Quotes erd
16505 followed by the volume key.
16506 It is also possible to have an else clause in the conditional, such as:
16508 \begin_inset Flex Code
16511 \begin_layout Plain Layout
16512 {%author%[[%author%]][[%editor%, ed.]]}
16519 \begin_inset Flex Code
16522 \begin_layout Plain Layout
16528 key is printed if it exists; otherwise, the editor key is printed, followed
16530 \begin_inset Quotes eld
16534 \begin_inset space ~
16538 \begin_inset Quotes erd
16541 Note that the key is again enclosed in
16542 \begin_inset Flex Code
16545 \begin_layout Plain Layout
16551 signs; the entire conditional is enclosed in braces; and the if and else
16552 clauses are enclosed in double brackets,
16553 \begin_inset Quotes eld
16557 \begin_inset Flex Code
16560 \begin_layout Plain Layout
16567 \begin_inset Quotes eld
16571 \begin_inset Quotes eld
16575 \begin_inset Flex Code
16578 \begin_layout Plain Layout
16585 \begin_inset Quotes erd
16589 There must be no space between any of these.
16592 \begin_layout Standard
16593 There is one other piece of syntax available in definitions, which looks
16595 \begin_inset Flex Code
16598 \begin_layout Plain Layout
16605 This defines a piece of formatting information that is to be used when
16607 \begin_inset Quotes eld
16611 \begin_inset Quotes erd
16615 Obviously, we do not want to output HTML tags when writing plain text,
16616 so they should be wrapped in
16617 \begin_inset Quotes eld
16621 \begin_inset Quotes erd
16625 \begin_inset Quotes eld
16629 \begin_inset Quotes erd
16635 \begin_layout Standard
16636 Two special sorts of definitions are also possible in a
16637 \begin_inset Flex Code
16640 \begin_layout Plain Layout
16647 An example of the first would be:
16650 \begin_layout LyX-Code
16652 \begin_inset Quotes eld
16656 \begin_inset Quotes erd
16662 \begin_layout Standard
16663 This is an abbreviation, or macro, and it can be used by treating it as
16665 \begin_inset Flex Code
16668 \begin_layout Plain Layout
16676 \begin_inset Flex Code
16679 \begin_layout Plain Layout
16685 exactly as it would treat its definition.
16686 So, let us issue the obvious
16694 \begin_layout LyX-Code
16698 \begin_layout Standard
16699 or anything like it.
16700 LyX shouldn't go into an infinite loop, but it may go into a long one before
16704 \begin_layout Standard
16705 The second sort of special definition might look like this:
16708 \begin_layout LyX-Code
16712 \begin_layout Standard
16713 This defines a translatable piece of text, which allows relevant parts of
16714 the bibliography to be translated.
16715 It can be included in a definition by treating it as a key:
16716 \begin_inset Flex Code
16719 \begin_layout Plain Layout
16726 Several of these are predefined in
16727 \begin_inset Flex Code
16730 \begin_layout Plain Layout
16737 Note that these are not macros, in the sense just defined.
16738 They will not be expanded.
16741 \begin_layout Standard
16742 So here then is an example that use all these features:
16745 \begin_layout LyX-Code
16746 !authoredit {%author%[[%author%, ]][[{%editor%[[%editor%, %_edtext%, ]]}]]}
16749 \begin_layout Standard
16750 This defines a macro that prints the author, followed by a comma, if the
16752 \begin_inset Flex Code
16755 \begin_layout Plain Layout
16761 key is defined, or else prints the name of the editor, followed by the
16763 \begin_inset Flex Code
16766 \begin_layout Plain Layout
16772 or its translation (it is by default
16773 \begin_inset Quotes eld
16777 \begin_inset Quotes erd
16781 \begin_inset Flex Code
16784 \begin_layout Plain Layout
16791 Note that this is in fact defined in
16792 \begin_inset Flex Code
16795 \begin_layout Plain Layout
16801 , so you can use it in your own definitions, or re-definitions, if you load
16805 \begin_layout Section
16806 \begin_inset CommandInset label
16808 name "sec:Tags-for-XHTML"
16812 Tags for XHTML output
16815 \begin_layout Standard
16816 As with LaTeX or DocBook, the format of LyX's XHTML output is also controlled
16817 by layout information.
16818 In general, LyX provides sensible defaults and, as mentioned earlier, it
16819 will even construct default CSS style rules from the other layout tags.
16820 For example, LyX will attempt to use the information provided in the
16821 \begin_inset Flex Code
16824 \begin_layout Plain Layout
16830 declaration for the Chapter style to write CSS that will appropriately
16831 format chapter headings.
16834 \begin_layout Standard
16835 In many cases, then, you may not have to do anything at all to get acceptable
16836 XHTML output for your own environments, custom insets, and so forth.
16837 But in some cases you will, and so LyX provides a number of layout tags
16838 that can be used to customize the XHTML and CSS that are generated.
16841 \begin_layout Standard
16842 Note that there are two tags,
16843 \begin_inset Flex Code
16846 \begin_layout Plain Layout
16853 \begin_inset Flex Code
16856 \begin_layout Plain Layout
16862 that may appear outside style and inset declarations.
16864 \begin_inset CommandInset ref
16866 reference "sub:General-text-class"
16870 for details on these.
16873 \begin_layout Subsection
16874 \begin_inset CommandInset label
16876 name "sub:Paragraph-Style-XHTML"
16883 \begin_layout Standard
16884 The sort of XHTML LyX outputs for a paragraph depends upon whether we are
16885 dealing with a normal paragraph, a command, or an environment, where this
16886 is itself determined by the contents of the corresponding
16887 \begin_inset Flex Code
16890 \begin_layout Plain Layout
16900 \begin_layout Standard
16901 For a command or normal paragraph, the output XHTML has the following form:
16904 \begin_layout LyX-Code
16906 \begin_inset Quotes erd
16910 \begin_inset Quotes erd
16916 \begin_layout LyX-Code
16918 \begin_inset Quotes erd
16922 \begin_inset Quotes erd
16928 \begin_layout LyX-Code
16929 Contents of the paragraph.
16932 \begin_layout LyX-Code
16936 \begin_layout Standard
16937 The label tags are of course omitted if the paragraph does not have a label.
16940 \begin_layout Standard
16941 For an environment that is not some sort of list, the XHTML takes this form:
16944 \begin_layout LyX-Code
16946 \begin_inset Quotes erd
16950 \begin_inset Quotes erd
16956 \begin_layout LyX-Code
16958 \begin_inset Quotes erd
16962 \begin_inset Quotes erd
16966 \begin_inset Quotes erd
16970 \begin_inset Quotes erd
16973 >Environment Label</labeltag>First paragraph.</itemtag>
16976 \begin_layout LyX-Code
16977 <itemtag>Second paragraph.</itemtag>
16980 \begin_layout LyX-Code
16984 \begin_layout Standard
16985 Note that the label is output only for the first paragraph, as it should
16986 be for a theorem, for example.
16990 \begin_layout Standard
16991 For a list, we have one of these forms:
16994 \begin_layout LyX-Code
16996 \begin_inset Quotes erd
17000 \begin_inset Quotes erd
17006 \begin_layout LyX-Code
17008 \begin_inset Quotes erd
17012 \begin_inset Quotes erd
17016 \begin_inset Quotes erd
17020 \begin_inset Quotes erd
17023 >List Label</labeltag>First item.</itemtag>
17026 \begin_layout LyX-Code
17028 \begin_inset Quotes erd
17032 \begin_inset Quotes erd
17036 \begin_inset Quotes erd
17040 \begin_inset Quotes erd
17043 >List Label</labeltag>Second item.</itemtag>
17046 \begin_layout LyX-Code
17050 \begin_layout LyX-Code
17054 \begin_layout LyX-Code
17056 \begin_inset Quotes erd
17060 \begin_inset Quotes erd
17066 \begin_layout LyX-Code
17068 \begin_inset Quotes erd
17072 \begin_inset Quotes erd
17075 >List Label</labeltag><itemtag attr=
17076 \begin_inset Quotes erd
17080 \begin_inset Quotes erd
17083 >First item.</itemtag>
17086 \begin_layout LyX-Code
17088 \begin_inset Quotes erd
17092 \begin_inset Quotes erd
17095 >List Label</labeltag><itemtag attr=
17096 \begin_inset Quotes erd
17100 \begin_inset Quotes erd
17103 >Second item.</itemtag>
17106 \begin_layout LyX-Code
17110 \begin_layout Standard
17111 Note the different orders of
17112 \begin_inset Flex Code
17115 \begin_layout Plain Layout
17122 \begin_inset Flex Code
17125 \begin_layout Plain Layout
17132 Which order we get depends upon the setting of
17133 \begin_inset Flex Code
17136 \begin_layout Plain Layout
17143 \begin_inset Flex Code
17146 \begin_layout Plain Layout
17152 is false (the default), you get the first of these, with the label within
17153 the item; if true, you get the second, with the label outside the item.
17156 \begin_layout Standard
17157 The specific tags and attributes output for each paragraph type can be controlle
17158 d by means of the layout tags we are about to describe.
17159 As mentioned earlier, however, LyX uses sensible defaults for many of these,
17160 so you often may not need to do very much to get good XHTML output.
17161 Think of the available tags as there so you can tweak things to your liking.
17164 \begin_layout Description
17165 \begin_inset Flex Code
17168 \begin_layout Plain Layout
17175 \begin_inset Flex Code
17178 \begin_layout Plain Layout
17184 ] Specifies attribute information to be output with the main tag.
17186 \begin_inset Quotes eld
17190 \begin_inset Flex Code
17193 \begin_layout Plain Layout
17200 \begin_inset Quotes erd
17204 By default, LyX will output
17205 \begin_inset Quotes eld
17209 \begin_inset Flex Code
17212 \begin_layout Plain Layout
17219 \begin_inset Quotes erd
17223 \begin_inset Flex Code
17226 \begin_layout Plain Layout
17232 is the LyX name of the layout, made lowercase, for example: chapter.
17237 contain any style information.
17239 \begin_inset Flex Code
17242 \begin_layout Plain Layout
17251 \begin_layout Description
17252 \begin_inset Flex Code
17255 \begin_layout Plain Layout
17262 \begin_inset Flex Code
17265 \begin_layout Plain Layout
17275 ] Whether to output the default CSS information LyX generates for this layout,
17276 even if additional information is explicitly provided via
17277 \begin_inset Flex Code
17280 \begin_layout Plain Layout
17288 \begin_inset Flex Code
17291 \begin_layout Plain Layout
17297 allows you to alter or augment the generated CSS, rather than to override
17300 \begin_inset Flex Code
17303 \begin_layout Plain Layout
17312 \begin_layout Description
17313 \begin_inset Flex Code
17316 \begin_layout Plain Layout
17323 \begin_inset Flex Code
17326 \begin_layout Plain Layout
17332 ] The tag to be used for individual paragraphs of environments, replacing
17334 \begin_inset Flex Code
17337 \begin_layout Plain Layout
17343 in the examples above.
17345 \begin_inset Flex Code
17348 \begin_layout Plain Layout
17357 \begin_layout Description
17358 \begin_inset Flex Code
17361 \begin_layout Plain Layout
17368 \begin_inset Flex Code
17371 \begin_layout Plain Layout
17377 ] Attributes for the item tag.
17379 \begin_inset Quotes eld
17383 \begin_inset Flex Code
17386 \begin_layout Plain Layout
17387 class=`layoutname_item'
17393 \begin_inset Quotes erd
17401 contain any style information.
17403 \begin_inset Flex Code
17406 \begin_layout Plain Layout
17415 \begin_layout Description
17416 \begin_inset Flex Code
17419 \begin_layout Plain Layout
17426 \begin_inset Flex Code
17429 \begin_layout Plain Layout
17435 ] The tag to be used for paragraph and item labels, replacing
17436 \begin_inset Flex Code
17439 \begin_layout Plain Layout
17445 in the examples above.
17447 \begin_inset Flex Code
17450 \begin_layout Plain Layout
17457 \begin_inset Flex Code
17460 \begin_layout Plain Layout
17467 \begin_inset Flex Code
17470 \begin_layout Plain Layout
17477 \begin_inset Flex Code
17480 \begin_layout Plain Layout
17481 Centered_Top_Environment
17486 , in which case it defaults to
17487 \begin_inset Flex Code
17490 \begin_layout Plain Layout
17499 \begin_layout Description
17500 \begin_inset Flex Code
17503 \begin_layout Plain Layout
17510 \begin_inset Flex Code
17513 \begin_layout Plain Layout
17519 ] Attributes for the label tag.
17521 \begin_inset Quotes eld
17525 \begin_inset Flex Code
17528 \begin_layout Plain Layout
17529 class=`layoutname_label'
17535 \begin_inset Quotes erd
17543 contain any style information.
17545 \begin_inset Flex Code
17548 \begin_layout Plain Layout
17557 \begin_layout Description
17558 \begin_inset Flex Code
17561 \begin_layout Plain Layout
17568 \begin_inset Flex Code
17571 \begin_layout Plain Layout
17581 ] Meaningful only for list-like environments, this tag controls whether
17582 the label tag is output before or inside the item tag.
17583 This is used, for example, in the description environment, where we want
17585 \begin_inset Flex Code
17588 \begin_layout Plain Layout
17589 <dt>\SpecialChar \ldots{}
17590 </dt><dd>\SpecialChar \ldots{}
17598 \begin_inset Flex Code
17601 \begin_layout Plain Layout
17607 : The label tag is output inside the item tag.
17610 \begin_layout Description
17611 \begin_inset Flex Code
17614 \begin_layout Plain Layout
17620 Information to be output in the
17621 \begin_inset Flex Code
17624 \begin_layout Plain Layout
17630 section when this style is used.
17631 This might, for example, be used to include a
17632 \begin_inset Flex Code
17635 \begin_layout Plain Layout
17642 \begin_inset Flex Code
17645 \begin_layout Plain Layout
17654 \begin_layout Description
17655 \begin_inset Flex Code
17658 \begin_layout Plain Layout
17664 CSS style information to be included when this style is used.
17665 Note that this will automatically be wrapped in a layout-generated
17666 \begin_inset Flex Code
17669 \begin_layout Plain Layout
17675 block, so only the CSS itself need be included.
17678 \begin_layout Description
17679 \begin_inset Flex Code
17682 \begin_layout Plain Layout
17689 \begin_inset Flex Code
17692 \begin_layout Plain Layout
17698 ] The tag to be used for the main label, replacing
17699 \begin_inset Flex Code
17702 \begin_layout Plain Layout
17708 in the examples above.
17710 \begin_inset Flex Code
17713 \begin_layout Plain Layout
17722 \begin_layout Description
17723 \begin_inset Flex Code
17726 \begin_layout Plain Layout
17733 \begin_inset Flex Code
17736 \begin_layout Plain Layout
17746 ] Marks this style as the one to be used to generate the
17747 \begin_inset Flex Code
17750 \begin_layout Plain Layout
17756 tag for the XHTML file.
17757 By default, it is false.
17759 \begin_inset Flex Code
17762 \begin_layout Plain Layout
17768 file sets it to true for the
17769 \begin_inset Flex Code
17772 \begin_layout Plain Layout
17782 \begin_layout Subsection
17786 \begin_layout Standard
17787 The XHTML output of insets can also be controlled by information in layout
17792 \begin_layout Plain Layout
17793 At present, this is true only for
17794 \begin_inset Quotes eld
17798 \begin_inset Quotes erd
17801 insets (insets you can type into) and is not true for
17802 \begin_inset Quotes eld
17806 \begin_inset Quotes erd
17809 insets (insets that are associated with dialog boxes).
17814 Here, too, LyX tries to provide sensible defaults, and it constructs default
17816 But everything can be customized.
17819 \begin_layout Standard
17820 The XHTML LyX outputs for an inset has the following form:
17823 \begin_layout LyX-Code
17825 \begin_inset Quotes erd
17829 \begin_inset Quotes erd
17835 \begin_layout LyX-Code
17836 <labeltag>Label</labeltag>
17839 \begin_layout LyX-Code
17841 \begin_inset Quotes erd
17845 \begin_inset Quotes erd
17848 >Contents of the inset.</innertag>
17851 \begin_layout LyX-Code
17855 \begin_layout Standard
17856 If the inset permits multiple paragraphs---that is, if
17857 \begin_inset Flex Code
17860 \begin_layout Plain Layout
17866 is true---then the contents of the inset will itself be output as paragraphs
17867 formatted according to the styles used for those paragraphs (standard,
17868 quote, and the like).
17869 The label tag is of course omitted if the paragraph does not have a label
17870 and, at present, is always
17871 \begin_inset Flex Code
17874 \begin_layout Plain Layout
17881 The inner tag is optional and, by default, does not appear.
17884 \begin_layout Standard
17885 The specific tags and attributes output for each inset can be controlled
17886 by means of the following layout tags.
17889 \begin_layout Description
17890 \begin_inset Flex Code
17893 \begin_layout Plain Layout
17900 \begin_inset Flex Code
17903 \begin_layout Plain Layout
17909 ] Specifies attribute information to be output with the main tag.
17911 \begin_inset Quotes eld
17915 \begin_inset Flex Code
17918 \begin_layout Plain Layout
17919 class=`myinset' onclick=`\SpecialChar \ldots{}
17926 \begin_inset Quotes erd
17930 By default, LyX will output
17931 \begin_inset Quotes eld
17935 \begin_inset Flex Code
17938 \begin_layout Plain Layout
17945 \begin_inset Quotes erd
17949 \begin_inset Flex Code
17952 \begin_layout Plain Layout
17958 is the LyX name of the inset, made lowercase and with non-alphanumeric
17959 characters converted to underscores, for example: footnote.
17962 \begin_layout Description
17963 \begin_inset Flex Code
17966 \begin_layout Plain Layout
17973 \begin_inset Flex Code
17976 \begin_layout Plain Layout
17986 ] Whether to output the default CSS information LyX generates for this layout,
17987 even if additional information is explicitly provided via
17988 \begin_inset Flex Code
17991 \begin_layout Plain Layout
17999 \begin_inset Flex Code
18002 \begin_layout Plain Layout
18008 allows you to alter or augment the generated CSS, rather than to override
18013 \begin_layout Description
18014 \begin_inset Flex Code
18017 \begin_layout Plain Layout
18024 \begin_inset Flex Code
18027 \begin_layout Plain Layout
18033 ] Attributes for the inner tag.
18035 \begin_inset Quotes eld
18039 \begin_inset Flex Code
18042 \begin_layout Plain Layout
18043 class=`insetname_inner'
18049 \begin_inset Quotes erd
18055 \begin_layout Description
18056 \begin_inset Flex Code
18059 \begin_layout Plain Layout
18066 \begin_inset Flex Code
18069 \begin_layout Plain Layout
18075 ] The inner tag, replacing
18076 \begin_inset Flex Code
18079 \begin_layout Plain Layout
18085 in the examples above.
18086 By default, there is none.
18089 \begin_layout Description
18090 \begin_inset Flex Code
18093 \begin_layout Plain Layout
18100 \begin_inset Flex Code
18103 \begin_layout Plain Layout
18111 ] Whether this inset represents a standalone block of text (such as a footnote)
18112 or instead represents material that is included in the surrounding text
18113 (such as a branch).
18117 \begin_layout Description
18118 \begin_inset Flex Code
18121 \begin_layout Plain Layout
18128 \begin_inset Flex Code
18131 \begin_layout Plain Layout
18137 ] A label for this inset, possibly including a reference to a counter.
18138 For example, for footnote, it might be:
18139 \begin_inset Flex Code
18142 \begin_layout Plain Layout
18151 This is optional, and there is no default.
18154 \begin_layout Description
18155 \begin_inset Flex Code
18158 \begin_layout Plain Layout
18164 Information to be output in the
18165 \begin_inset Flex Code
18168 \begin_layout Plain Layout
18174 section when this style is used.
18175 This might, for example, be used to include a
18176 \begin_inset Flex Code
18179 \begin_layout Plain Layout
18186 \begin_inset Flex Code
18189 \begin_layout Plain Layout
18198 \begin_layout Description
18199 \begin_inset Flex Code
18202 \begin_layout Plain Layout
18208 CSS style information to be included when this style is used.
18209 Note that this will automatically be wrapped in a layout-generated
18210 \begin_inset Flex Code
18213 \begin_layout Plain Layout
18219 block, so only the CSS itself need be included.
18222 \begin_layout Description
18223 \begin_inset Flex Code
18226 \begin_layout Plain Layout
18233 \begin_inset Flex Code
18236 \begin_layout Plain Layout
18242 ] The tag to be used for the main label, replacing
18243 \begin_inset Flex Code
18246 \begin_layout Plain Layout
18252 in the examples above.
18253 The default depends upon the setting of
18254 \begin_inset Flex Code
18257 \begin_layout Plain Layout
18264 \begin_inset Flex Code
18267 \begin_layout Plain Layout
18273 is true, the default is
18274 \begin_inset Flex Code
18277 \begin_layout Plain Layout
18283 ; if it is false, the default is
18284 \begin_inset Flex Code
18287 \begin_layout Plain Layout
18296 \begin_layout Subsection
18300 \begin_layout Standard
18301 The XHTML output for floats too can be controlled by layout information.
18302 The output has the following form:
18305 \begin_layout LyX-Code
18307 \begin_inset Quotes erd
18311 \begin_inset Quotes erd
18317 \begin_layout LyX-Code
18318 Contents of the float.
18321 \begin_layout LyX-Code
18325 \begin_layout Standard
18326 The caption, if there is one, is a separate inset and will be output as
18328 Its appearance can be controlled via the InsetLayout for caption insets.
18332 \begin_layout Description
18333 \begin_inset Flex Code
18336 \begin_layout Plain Layout
18343 \begin_inset Flex Code
18346 \begin_layout Plain Layout
18352 ] Specifies attribute information to be output with the main tag.
18354 \begin_inset Quotes eld
18358 \begin_inset Flex Code
18361 \begin_layout Plain Layout
18362 class=`myfloat' onclick=`\SpecialChar \ldots{}
18369 \begin_inset Quotes erd
18373 By default, LyX will output
18374 \begin_inset Quotes eld
18378 \begin_inset Flex Code
18381 \begin_layout Plain Layout
18382 class=`float float-floattype'
18388 \begin_inset Quotes erd
18392 \begin_inset Flex Code
18395 \begin_layout Plain Layout
18401 is LyX's name for this type of float, as determined by the float declaration
18403 \begin_inset CommandInset ref
18405 reference "sub:Floats"
18409 ), though made lowercase and with non-alphanumeric characters converted
18410 to underscores, for example: float-table.
18413 \begin_layout Description
18414 \begin_inset Flex Code
18417 \begin_layout Plain Layout
18423 CSS style information to be included when this float is used.
18424 Note that this will automatically be wrapped in a layout-generated
18425 \begin_inset Flex Code
18428 \begin_layout Plain Layout
18434 block, so only the CSS itself need be included.
18437 \begin_layout Description
18438 \begin_inset Flex Code
18441 \begin_layout Plain Layout
18448 \begin_inset Flex Code
18451 \begin_layout Plain Layout
18457 ] The tag to be used for this float, replacing
18458 \begin_inset Quotes eld
18462 \begin_inset Flex Code
18465 \begin_layout Plain Layout
18472 \begin_inset Quotes erd
18475 in the example above.
18477 \begin_inset Flex Code
18480 \begin_layout Plain Layout
18486 and will rarely need changing.
18489 \begin_layout Subsection
18490 Bibliography formatting
18493 \begin_layout Standard
18494 The bibliography can be formatted using
18495 \begin_inset Flex Code
18498 \begin_layout Plain Layout
18506 \begin_inset CommandInset ref
18508 reference "sub:Citation-format-description"
18515 \begin_layout Subsection
18519 \begin_layout Standard
18520 We have several times mentioned that LyX will generate default CSS style
18521 rules for both insets and paragraph styles, based upon the other layout
18522 information that is provided.
18523 In this section, we shall say a word about which layout information LyX
18527 \begin_layout Standard
18528 At present, LyX auto-generates CSS only for font information, making use
18530 \begin_inset Flex Code
18533 \begin_layout Plain Layout
18540 \begin_inset Flex Code
18543 \begin_layout Plain Layout
18550 \begin_inset Flex Code
18553 \begin_layout Plain Layout
18560 \begin_inset Flex Code
18563 \begin_layout Plain Layout
18570 \begin_inset Flex Code
18573 \begin_layout Plain Layout
18581 \begin_inset CommandInset ref
18583 reference "sub:Font-description"
18587 .) The translation is mostly straightforward and obvious.
18589 \begin_inset Quotes eld
18593 \begin_inset Flex Code
18596 \begin_layout Plain Layout
18603 \begin_inset Quotes erd
18607 \begin_inset Quotes eld
18611 \begin_inset Flex Code
18614 \begin_layout Plain Layout
18615 font-family: sans-serif;
18621 \begin_inset Quotes erd
18625 The correspondence of LyX sizes and CSS sizes is a little less obvious
18626 but nonetheless intuitive.
18628 \begin_inset Flex Code
18631 \begin_layout Plain Layout
18638 \begin_inset Flex URL
18641 \begin_layout Plain Layout
18652 \begin_layout Chapter
18653 Including External Material
18656 \begin_layout Standard
18657 \begin_inset Box Shadowbox
18667 height_special "totalheight"
18670 \begin_layout Plain Layout
18671 WARNING: This portion of the documentation has not been updated for some
18673 We certainly hope that it is still accurate, but there are no guarantees.
18681 \begin_layout Standard
18682 The use of material from sources external to LyX is covered in detail in
18688 This part of the manual covers what needs to happen behind the scenes for
18689 new sorts of material to be included.
18692 \begin_layout Section
18696 \begin_layout Standard
18697 The external material feature is based on the concept of a
18702 A template is a specification of how LyX should interface with a certain
18704 As bundled, LyX comes with predefined templates for Xfig figures, various
18705 raster format images, chess diagrams, and LilyPond music notation.
18706 You can check the actual list by using the menu
18707 \begin_inset Flex MenuItem
18710 \begin_layout Plain Layout
18711 Insert\SpecialChar \menuseparator
18712 File\SpecialChar \menuseparator
18719 Furthermore, it is possible to roll your own template to support a specific
18721 Later we'll describe in more detail what is involved, and hopefully you
18722 will submit all the templates you create so we can include them in a later
18726 \begin_layout Standard
18727 Another basic idea of the external material feature is to distinguish between
18728 the original file that serves as a base for final material and the produced
18729 file that is included in your exported or printed document.
18730 For example, consider the case of a figure produced with
18731 \begin_inset Flex Code
18734 \begin_layout Plain Layout
18741 The Xfig application itself works on an original file with the
18742 \begin_inset Flex Code
18745 \begin_layout Plain Layout
18752 Within Xfig, you create and change your figure, and when you are done,
18754 \begin_inset Flex Code
18757 \begin_layout Plain Layout
18764 When you want to include the figure in your document, you invoke
18765 \begin_inset Flex Code
18768 \begin_layout Plain Layout
18774 in order to create a PostScript file that can readily be included in your
18777 \begin_inset Flex Code
18780 \begin_layout Plain Layout
18786 file is the original file, and the PostScript file is the produced file.
18789 \begin_layout Standard
18790 This distinction is important in order to allow updating of the material
18791 while you are in the process of writing the document.
18792 Furthermore, it provides us with the flexibility that is needed to support
18793 multiple export formats.
18794 For instance, in the case of a plain text file, it is not exactly an award-winn
18795 ing idea to include the figure as raw PostScript.
18796 Instead, you'd either prefer to just include a reference to the figure
18797 or try to invoke some graphics to ASCII converter to make the final result
18798 look similar to the real graphics.
18799 The external material management allows you to do this, because it is parametri
18800 zed on the different export formats that LyX supports.
18803 \begin_layout Standard
18804 Besides supporting the production of different products according to the
18805 exported format, it supports tight integration with editing and viewing
18807 In the case of an Xfig figure, you are able to invoke Xfig on the original
18808 file with a single click from within the external material dialog in LyX,
18809 and also preview the produced PostScript file with Ghostview with another
18811 No more fiddling around with the command line and/or file browsers to locate
18812 and manipulate the original or produced files.
18813 In this way, you are finally able to take full advantage of the many different
18814 applications that are relevant to use when you write your documents, and
18815 ultimately be more productive.
18818 \begin_layout Section
18819 The external template configuration file
18822 \begin_layout Standard
18823 It is relatively easy to add custom external template definitions to LyX.
18824 However, be aware that doing this in an careless manner most probably
18828 introduce an easily exploitable security hole.
18829 So before you do this, please read the discussion about security in section
18831 \begin_inset CommandInset ref
18833 reference "sec:Security-discussion"
18840 \begin_layout Standard
18841 Having said that, we encourage you to submit any interesting templates that
18846 \begin_layout Standard
18847 The external templates are defined in the
18848 \begin_inset Flex Code
18851 \begin_layout Plain Layout
18852 LyXDir/lib/external_templates
18858 You can place your own version in
18859 \begin_inset Flex Code
18862 \begin_layout Plain Layout
18863 UserDir/external_templates
18871 \begin_layout Standard
18872 A typical template looks like this:
18875 \begin_layout LyX-Code
18879 \begin_layout LyX-Code
18880 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
18883 \begin_layout LyX-Code
18887 \begin_layout LyX-Code
18891 \begin_layout LyX-Code
18895 \begin_layout LyX-Code
18899 \begin_layout LyX-Code
18903 \begin_layout LyX-Code
18904 AutomaticProduction true
18907 \begin_layout LyX-Code
18911 \begin_layout LyX-Code
18915 \begin_layout LyX-Code
18919 \begin_layout LyX-Code
18920 TransformCommand Rotate RotationLatexCommand
18923 \begin_layout LyX-Code
18924 TransformCommand Resize ResizeLatexCommand
18927 \begin_layout LyX-Code
18928 Product "$$RotateFront$$ResizeFront
18931 \begin_layout LyX-Code
18936 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
18939 \begin_layout LyX-Code
18940 $$ResizeBack$$RotateBack"
18943 \begin_layout LyX-Code
18947 \begin_layout LyX-Code
18948 UpdateResult "$$AbsPath$$Basename.pstex_t"
18951 \begin_layout LyX-Code
18952 Requirement "graphicx"
18955 \begin_layout LyX-Code
18956 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
18959 \begin_layout LyX-Code
18960 ReferencedFile latex "$$AbsPath$$Basename.eps"
18963 \begin_layout LyX-Code
18964 ReferencedFile dvi "$$AbsPath$$Basename.eps"
18967 \begin_layout LyX-Code
18971 \begin_layout LyX-Code
18975 \begin_layout LyX-Code
18976 TransformCommand Rotate RotationLatexCommand
18979 \begin_layout LyX-Code
18980 TransformCommand Resize ResizeLatexCommand
18983 \begin_layout LyX-Code
18984 Product "$$RotateFront$$ResizeFront
18987 \begin_layout LyX-Code
18992 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
18995 \begin_layout LyX-Code
18996 $$ResizeBack$$RotateBack"
18999 \begin_layout LyX-Code
19000 UpdateFormat pdftex
19003 \begin_layout LyX-Code
19004 UpdateResult "$$AbsPath$$Basename.pdftex_t"
19007 \begin_layout LyX-Code
19008 Requirement "graphicx"
19011 \begin_layout LyX-Code
19012 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
19015 \begin_layout LyX-Code
19016 ReferencedFile latex "$$AbsPath$$Basename.pdf"
19019 \begin_layout LyX-Code
19023 \begin_layout LyX-Code
19027 \begin_layout LyX-Code
19028 Product "$$Contents(
19030 "$$AbsPath$$Basename.asc
19035 \begin_layout LyX-Code
19036 UpdateFormat asciixfig
19039 \begin_layout LyX-Code
19040 UpdateResult "$$AbsPath$$Basename.asc"
19043 \begin_layout LyX-Code
19047 \begin_layout LyX-Code
19051 \begin_layout LyX-Code
19052 Product "<graphic fileref=
19054 "$$AbsOrRelPathMaster$$Basename.eps
19059 \begin_layout LyX-Code
19063 \begin_layout LyX-Code
19067 \begin_layout LyX-Code
19068 UpdateResult "$$AbsPath$$Basename.eps"
19071 \begin_layout LyX-Code
19072 ReferencedFile docbook "$$AbsPath$$Basename.eps"
19075 \begin_layout LyX-Code
19076 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
19079 \begin_layout LyX-Code
19083 \begin_layout LyX-Code
19084 Product "[XFig: $$FName]"
19087 \begin_layout LyX-Code
19091 \begin_layout LyX-Code
19095 \begin_layout Standard
19096 As you can see, the template is enclosed in
19097 \begin_inset Flex Code
19100 \begin_layout Plain Layout
19106 \SpecialChar \ldots{}
19108 \begin_inset Flex Code
19111 \begin_layout Plain Layout
19118 It contains a header specifying some general settings and, for each supported
19119 primary document file format, a section
19120 \begin_inset Flex Code
19123 \begin_layout Plain Layout
19129 \SpecialChar \ldots{}
19131 \begin_inset Flex Code
19134 \begin_layout Plain Layout
19143 \begin_layout Subsection
19144 The template header
19147 \begin_layout Description
19148 \begin_inset Flex Code
19151 \begin_layout Plain Layout
19152 AutomaticProduction
19153 \begin_inset space ~
19161 Whether the file represented by the template must be generated by LyX.
19162 This command must occur exactly once.
19165 \begin_layout Description
19166 \begin_inset Flex Code
19169 \begin_layout Plain Layout
19171 \begin_inset space ~
19179 A glob pattern that is used in the file dialog to filter out the desired
19181 If there is more than one possible file extension (e.
19182 \begin_inset space \thinspace{}
19186 \begin_inset space \space{}
19190 \begin_inset Flex Code
19193 \begin_layout Plain Layout
19200 \begin_inset Flex Code
19203 \begin_layout Plain Layout
19209 ), use something like
19210 \begin_inset Flex Code
19213 \begin_layout Plain Layout
19220 This command must occur exactly once.
19223 \begin_layout Description
19224 \begin_inset Flex Code
19227 \begin_layout Plain Layout
19229 \begin_inset space ~
19237 The text that is displayed on the button.
19238 This command must occur exactly once.
19241 \begin_layout Description
19242 \begin_inset Flex Code
19245 \begin_layout Plain Layout
19247 \begin_inset space ~
19251 \begin_inset space ~
19259 The help text that is used in the External dialog.
19260 Provide enough information to explain to the user just what the template
19261 can provide him with.
19262 This command must occur exactly once.
19265 \begin_layout Description
19266 \begin_inset Flex Code
19269 \begin_layout Plain Layout
19271 \begin_inset space ~
19279 The file format of the original file.
19280 This must be the name of a format that is known to LyX (see section
19281 \begin_inset space ~
19285 \begin_inset CommandInset ref
19287 reference "sec:Formats"
19293 \begin_inset Quotes eld
19297 \begin_inset Flex Code
19300 \begin_layout Plain Layout
19307 \begin_inset Quotes erd
19310 if the template can handle original files of more than one format.
19311 LyX will attempt to interrogate the file itself in order to deduce its
19312 format in this case.
19313 This command must occur exactly once.
19316 \begin_layout Description
19317 \begin_inset Flex Code
19320 \begin_layout Plain Layout
19322 \begin_inset space ~
19330 A unique name for the template.
19331 It must not contain substitution macros (see below).
19334 \begin_layout Description
19335 \begin_inset Flex Code
19338 \begin_layout Plain Layout
19340 \begin_inset space ~
19343 Rotate|Resize|Clip|Extra
19348 This command specifies which transformations are supported by this template.
19349 It may occur zero or more times.
19350 This command enables the corresponding tabs in the external dialog.
19352 \begin_inset Flex Code
19355 \begin_layout Plain Layout
19361 command must have either a corresponding
19362 \begin_inset Flex Code
19365 \begin_layout Plain Layout
19372 \begin_inset Flex Code
19375 \begin_layout Plain Layout
19382 \begin_inset Flex Code
19385 \begin_layout Plain Layout
19392 Otherwise the transformation will not be supported by that format.
19395 \begin_layout Subsection
19399 \begin_layout Description
19400 \begin_inset Flex Code
19403 \begin_layout Plain Layout
19405 \begin_inset space ~
19408 LaTeX|PDFLaTeX|PlainText|DocBook
19413 The primary document file format that this format definition is for.
19414 Not every template has a sensible representation in all document file formats.
19415 Please define nevertheless a
19416 \begin_inset Flex Code
19419 \begin_layout Plain Layout
19425 section for all templates.
19426 Use a dummy text when no representation is available.
19427 Then you can at least see a reference to the external material in the exported
19431 \begin_layout Description
19432 \begin_inset Flex Code
19435 \begin_layout Plain Layout
19437 \begin_inset space ~
19441 \begin_inset space ~
19449 This command defines an additional macro
19450 \begin_inset Flex Code
19453 \begin_layout Plain Layout
19459 for substitution in
19460 \begin_inset Flex Code
19463 \begin_layout Plain Layout
19471 \begin_inset Flex Code
19474 \begin_layout Plain Layout
19480 itself may contain substitution macros.
19481 The advantage over using
19482 \begin_inset Flex Code
19485 \begin_layout Plain Layout
19492 \begin_inset Flex Code
19495 \begin_layout Plain Layout
19501 is that the substituted value of
19502 \begin_inset Flex Code
19505 \begin_layout Plain Layout
19511 is sanitized so that it is a valid optional argument in the document format.
19512 This command may occur zero or more times.
19515 \begin_layout Description
19516 \begin_inset Flex Code
19519 \begin_layout Plain Layout
19521 \begin_inset space ~
19529 The text that is inserted in the exported document.
19530 This is actually the most important command and can be quite complex.
19531 This command must occur exactly once.
19534 \begin_layout Description
19535 \begin_inset Flex Code
19538 \begin_layout Plain Layout
19540 \begin_inset space ~
19548 This command specifies a preamble snippet that will be included in the
19550 It has to be defined using
19551 \begin_inset Flex Code
19554 \begin_layout Plain Layout
19560 \SpecialChar \ldots{}
19562 \begin_inset Flex Code
19565 \begin_layout Plain Layout
19572 This command may occur zero or more times.
19575 \begin_layout Description
19576 \begin_inset Flex Code
19579 \begin_layout Plain Layout
19581 \begin_inset space ~
19585 \begin_inset space ~
19593 This command denotes files that are created by the conversion process and
19594 are needed for a particular export format.
19595 If the filename is relative, it is interpreted relative to the master document.
19596 This command may be given zero or more times.
19599 \begin_layout Description
19600 \begin_inset Flex Code
19603 \begin_layout Plain Layout
19605 \begin_inset space ~
19613 The name of a required LaTeX package.
19614 The package is included via
19615 \begin_inset Flex Code
19618 \begin_layout Plain Layout
19626 in the LaTeX preamble.
19627 This command may occur zero or more times.
19630 \begin_layout Description
19631 \begin_inset Flex Code
19634 \begin_layout Plain Layout
19636 \begin_inset space ~
19640 \begin_inset space ~
19643 RotationLatexCommand
19648 This command specifies that the built in LaTeX command should be used for
19650 This command may occur once or not at all.
19653 \begin_layout Description
19654 \begin_inset Flex Code
19657 \begin_layout Plain Layout
19659 \begin_inset space ~
19663 \begin_inset space ~
19671 This command specifies that the built in LaTeX command should be used for
19673 This command may occur once or not at all.
19676 \begin_layout Description
19677 \begin_inset Flex Code
19680 \begin_layout Plain Layout
19682 \begin_inset space ~
19686 \begin_inset space ~
19689 RotationLatexOption
19694 This command specifies that rotation is done via an optional argument.
19695 This command may occur once or not at all.
19698 \begin_layout Description
19699 \begin_inset Flex Code
19702 \begin_layout Plain Layout
19704 \begin_inset space ~
19708 \begin_inset space ~
19716 This command specifies that resizing is done via an optional argument.
19717 This command may occur once or not at all.
19720 \begin_layout Description
19721 \begin_inset Flex Code
19724 \begin_layout Plain Layout
19726 \begin_inset space ~
19730 \begin_inset space ~
19738 This command specifies that clipping is done via an optional argument.
19739 This command may occur once or not at all.
19742 \begin_layout Description
19743 \begin_inset Flex Code
19746 \begin_layout Plain Layout
19748 \begin_inset space ~
19752 \begin_inset space ~
19760 This command specifies that an extra optional argument is used.
19761 This command may occur once or not at all.
19764 \begin_layout Description
19765 \begin_inset Flex Code
19768 \begin_layout Plain Layout
19770 \begin_inset space ~
19778 The file format of the converted file.
19779 This must be the name of a format that is known to LyX (see the
19780 \begin_inset Flex MenuItem
19783 \begin_layout Plain Layout
19788 ools\SpecialChar \menuseparator
19793 references\SpecialChar \menuseparator
19794 File Handling\SpecialChar \menuseparator
19801 This command must occur exactly once.
19804 \begin_layout Description
19805 \begin_inset Flex Code
19808 \begin_layout Plain Layout
19810 \begin_inset space ~
19818 The file name of the converted file.
19819 The file name must be absolute.
19820 This command must occur exactly once.
19823 \begin_layout Subsection
19824 Preamble definitions
19827 \begin_layout Standard
19828 The external template configuration file may contain additional preamble
19829 definitions enclosed by
19830 \begin_inset Flex Code
19833 \begin_layout Plain Layout
19839 \SpecialChar \ldots{}
19841 \begin_inset Flex Code
19844 \begin_layout Plain Layout
19851 They can be used by the templates in the
19852 \begin_inset Flex Code
19855 \begin_layout Plain Layout
19864 \begin_layout Section
19865 The substitution mechanism
19868 \begin_layout Standard
19869 When the external material facility invokes an external program, it is done
19870 on the basis of a command defined in the template configuration file.
19871 These commands can contain various macros that are expanded before execution.
19872 Execution always take place in the directory of the containing document.
19875 \begin_layout Standard
19876 Also, whenever external material is to be displayed, the name will be produced
19877 by the substitution mechanism, and most other commands in the template
19878 definition support substitution as well.
19881 \begin_layout Standard
19882 The available macros are the following:
19885 \begin_layout Description
19886 \begin_inset Flex Code
19889 \begin_layout Plain Layout
19890 $$AbsOrRelPathMaster
19895 The file path, absolute or relative to the master LyX document.
19898 \begin_layout Description
19899 \begin_inset Flex Code
19902 \begin_layout Plain Layout
19903 $$AbsOrRelPathParent
19908 The file path, absolute or relative to the LyX document.
19911 \begin_layout Description
19912 \begin_inset Flex Code
19915 \begin_layout Plain Layout
19921 The absolute file path.
19924 \begin_layout Description
19925 \begin_inset Flex Code
19928 \begin_layout Plain Layout
19934 The filename without path and without the extension.
19937 \begin_layout Description
19938 \begin_inset Flex Code
19941 \begin_layout Plain Layout
19943 \begin_inset Quotes eld
19947 \begin_inset Quotes erd
19955 This macro will expand to the contents of the file with the name
19956 \begin_inset Flex Code
19959 \begin_layout Plain Layout
19968 \begin_layout Description
19969 \begin_inset Flex Code
19972 \begin_layout Plain Layout
19978 The file extension (including the dot).
19981 \begin_layout Description
19982 \begin_inset Flex Code
19985 \begin_layout Plain Layout
19991 The filename of the file specified in the external material dialog.
19992 This is either an absolute name, or it is relative to the LyX document.
19995 \begin_layout Description
19996 \begin_inset Flex Code
19999 \begin_layout Plain Layout
20006 \begin_inset Flex Code
20009 \begin_layout Plain Layout
20015 (absolute name or relative to the LyX document).
20018 \begin_layout Description
20019 \begin_inset Flex Code
20022 \begin_layout Plain Layout
20028 The file path, relative to the master LyX document.
20031 \begin_layout Description
20032 \begin_inset Flex Code
20035 \begin_layout Plain Layout
20041 The file path, relative to the LyX document.
20044 \begin_layout Description
20045 \begin_inset Flex Code
20048 \begin_layout Plain Layout
20054 This macro will expand to the absolute path of the system directory.
20055 This is typically used to point to the various helper scripts that are
20059 \begin_layout Description
20060 \begin_inset Flex Code
20063 \begin_layout Plain Layout
20069 A name and full path to a temporary file which will be automatically deleted
20070 whenever the containing document is closed, or the external material insertion
20074 \begin_layout Standard
20075 All path macros contain a trailing directory separator, so you can construct
20077 \begin_inset space \thinspace{}
20081 \begin_inset space \space{}
20084 the absolute filename with
20085 \begin_inset Flex Code
20088 \begin_layout Plain Layout
20089 $$AbsPath$$Basename$$Extension
20097 \begin_layout Standard
20098 The macros above are substituted in all commands unless otherwise noted.
20100 \begin_inset Flex Code
20103 \begin_layout Plain Layout
20109 supports additionally the following substitutions if they are enabled by
20111 \begin_inset Flex Code
20114 \begin_layout Plain Layout
20121 \begin_inset Flex Code
20124 \begin_layout Plain Layout
20133 \begin_layout Description
20134 \begin_inset Flex Code
20137 \begin_layout Plain Layout
20143 The front part of the resize command.
20146 \begin_layout Description
20147 \begin_inset Flex Code
20150 \begin_layout Plain Layout
20156 The back part of the resize command.
20159 \begin_layout Description
20160 \begin_inset Flex Code
20163 \begin_layout Plain Layout
20169 The front part of the rotation command.
20172 \begin_layout Description
20173 \begin_inset Flex Code
20176 \begin_layout Plain Layout
20182 The back part of the rotation command.
20185 \begin_layout Standard
20186 The value string of the
20187 \begin_inset Flex Code
20190 \begin_layout Plain Layout
20196 command supports additionally the following substitutions if they are enabled
20198 \begin_inset Flex Code
20201 \begin_layout Plain Layout
20208 \begin_inset Flex Code
20211 \begin_layout Plain Layout
20220 \begin_layout Description
20221 \begin_inset Flex Code
20224 \begin_layout Plain Layout
20233 \begin_layout Description
20234 \begin_inset Flex Code
20237 \begin_layout Plain Layout
20246 \begin_layout Description
20247 \begin_inset Flex Code
20250 \begin_layout Plain Layout
20259 \begin_layout Description
20260 \begin_inset Flex Code
20263 \begin_layout Plain Layout
20269 The rotation option.
20272 \begin_layout Standard
20273 You may ask why there are so many path macros.
20274 There are mainly two reasons:
20277 \begin_layout Enumerate
20278 Relative and absolute file names should remain relative or absolute, respectivel
20280 Users may have reasons to prefer either form.
20281 Relative names are useful for portable documents that should work on different
20282 machines, for example.
20283 Absolute names may be required by some programs.
20286 \begin_layout Enumerate
20287 LaTeX treats relative file names differently than LyX and other programs
20288 in nested included files.
20289 For LyX, a relative file name is always relative to the document that contains
20291 For LaTeX, it is always relative to the master document.
20292 These two definitions are identical if you have only one document, but
20293 differ if you have a master document that includes part documents.
20294 That means that relative filenames must be transformed when presented to
20296 Fortunately LyX does this automatically for you if you choose the right
20300 \begin_layout Standard
20301 So which path macro should be used in new template definitions? The rule
20305 \begin_layout Itemize
20307 \begin_inset Flex Code
20310 \begin_layout Plain Layout
20316 if an absolute path is required.
20319 \begin_layout Itemize
20321 \begin_inset Flex Code
20324 \begin_layout Plain Layout
20325 $$AbsOrRelPathMaster
20330 if the substituted string is some kind of LaTeX input.
20333 \begin_layout Itemize
20335 \begin_inset Flex Code
20338 \begin_layout Plain Layout
20339 $$AbsOrRelPathParent
20344 in order to preserve the user's choice.
20347 \begin_layout Standard
20348 There are special cases where this rule does not work and e.
20349 \begin_inset space \thinspace{}
20353 \begin_inset space \space{}
20356 relative names are needed, but normally it will work just fine.
20357 One example for such a case is the command
20358 \begin_inset Flex Code
20361 \begin_layout Plain Layout
20362 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
20367 in the XFig template above: We can't use the absolute name because the
20369 \begin_inset Flex Code
20372 \begin_layout Plain Layout
20378 files needs the relative name in order to rewrite the file content.
20381 \begin_layout Section
20382 Security discussion
20383 \begin_inset CommandInset label
20385 name "sec:Security-discussion"
20392 \begin_layout Standard
20393 The external material feature interfaces with a lot of external programs
20394 and does so automatically, so we have to consider the security implications
20396 In particular, since you have the option of including your own filenames
20397 and/or parameter strings and those are expanded into a command, it seems
20398 that it would be possible to create a malicious document which executes
20399 arbitrary commands when a user views or prints the document.
20400 This is something we definitely want to avoid.
20403 \begin_layout Standard
20404 However, since the external program commands are specified in the template
20405 configuration file only, there are no security issues if LyX is properly
20406 configured with safe templates only.
20407 This is so because the external programs are invoked with the
20408 \begin_inset Flex Code
20411 \begin_layout Plain Layout
20417 -system call rather than the
20418 \begin_inset Flex Code
20421 \begin_layout Plain Layout
20427 system-call, so it's not possible to execute arbitrary commands from the
20428 filename or parameter section via the shell.
20431 \begin_layout Standard
20432 This also implies that you are restricted in what command strings you can
20433 use in the external material templates.
20434 In particular, pipes and redirection are not readily available.
20435 This has to be so if LyX should remain safe.
20436 If you want to use some of the shell features, you should write a safe
20437 script to do this in a controlled manner, and then invoke the script from
20438 the command string.
20442 \begin_layout Standard
20443 It is possible to design a template that interacts directly with the shell,
20444 but since this would allow a malicious user to execute arbitrary commands
20445 by writing clever filenames and/or parameters, we generally recommend that
20446 you only use safe scripts that work with the
20447 \begin_inset Flex Code
20450 \begin_layout Plain Layout
20456 system call in a controlled manner.
20457 Of course, for use in a controlled environment, it can be tempting to just
20458 fall back to use ordinary shell scripts.
20459 If you do so, be aware that you
20463 provide an easily exploitable security hole in your system.
20464 Of course it stands to reason that such unsafe templates will never be
20465 included in the standard LyX distribution, although we do encourage people
20466 to submit new templates in the open source tradition.
20467 But LyX as shipped from the official distribution channels will never have
20471 \begin_layout Standard
20472 Including external material provides a lot of power, and you have to be
20473 careful not to introduce security hazards with this power.
20474 A subtle error in a single line in an innocent looking script can open
20475 the door to huge security problems.
20476 So if you do not fully understand the issues, we recommend that you consult
20477 a knowledgeable security professional or the LyX development team if you
20478 have any questions about whether a given template is safe or not.
20479 And do this before you use it in an uncontrolled environment.