lib/doc/Customization.lyx

   1 #LyX 2.0.0svn created this file. For more info see http://www.lyx.org/
   2 \lyxformat 348
   3 \begin_document
   4 \begin_header
   5 \textclass scrbook
   6 \begin_preamble
   7 % DO NOT ALTER THIS PREAMBLE!!!
   8 %
   9 % This preamble is designed to ensure that the User's Guide prints
  10 % out as advertised. If you mess with this preamble,
  11 % parts of the User's Guide 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
  15
  16 \usepackage{ifpdf} % part of the hyperref bundle
  17 \ifpdf % if pdflatex is used
  18
  19  % set fonts for nicer pdf view
  20  \IfFileExists{lmodern.sty}
  21   {\usepackage{lmodern}}{}
  22
  23 \fi % end if pdflatex is used
  24
  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{%
  29   \frontmatter
  30   \pdfbookmark[1]{\contentsname}{}
  31   \myTOC
  32   \mainmatter }
  33
  34 % redefine the \LyX macro for PDF bookmarks
  35 \def\LyX{\texorpdfstring{%
  36   L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
  37   {LyX}}
  38
  39 % used for multi-column text
  40 \usepackage{multicol}
  41 \usepackage{inputenc}
  42 \end_preamble
  43 \options fleqn,liststotoc,bibtotoc,idxtotoc,BCOR7.5mm,titlepage,tablecaptionabove
  44 \use_default_options false
  45 \begin_modules
  46 logicalmkup
  47 \end_modules
  48 \begin_local_layout
  49 Format 7
  50 InsetLayout CharStyle:MenuItem
  51 LyxType               charstyle
  52 LabelString           menu
  53 LatexType             command
  54 LatexName             menuitem
  55 Font
  56 Family              Sans
  57 EndFont
  58 Preamble
  59 \newcommand*{\menuitem}[1]{{\sffamily #1}}
  60 EndPreamble
  61 End
  62 \end_local_layout
  63 \language english
  64 \inputencoding auto
  65 \font_roman default
  66 \font_sans default
  67 \font_typewriter default
  68 \font_default_family default
  69 \font_sc false
  70 \font_osf false
  71 \font_sf_scale 100
  72 \font_tt_scale 100
  73
  74 \graphics default
  75 \paperfontsize 12
  76 \spacing single
  77 \use_hyperref true
  78 \pdf_title "LyX Configuration Manual"
  79 \pdf_author "LyX Team"
  80 \pdf_subject "LyX-documentation Customization"
  81 \pdf_keywords "LyX, documentation, customization"
  82 \pdf_bookmarks true
  83 \pdf_bookmarksnumbered true
  84 \pdf_bookmarksopen true
  85 \pdf_bookmarksopenlevel 1
  86 \pdf_breaklinks false
  87 \pdf_pdfborder false
  88 \pdf_colorlinks true
  89 \pdf_backref false
  90 \pdf_pdfusetitle false
  91 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true,pdfstartview=XYZ, plainpages=false, pdfpagelabels"
  92 \papersize default
  93 \use_geometry false
  94 \use_amsmath 0
  95 \use_esint 0
  96 \cite_engine basic
  97 \use_bibtopic false
  98 \paperorientation portrait
  99 \branch OutDated
 100 \selected 0
 101 \color #f5fae7
 102 \end_branch
 103 \secnumdepth 3
 104 \tocdepth 3
 105 \paragraph_separation indent
 106 \defskip medskip
 107 \quotes_language english
 108 \papercolumns 1
 109 \papersides 2
 110 \paperpagestyle headings
 111 \tracking_changes true
 112 \output_changes false
 113 \author "Georg Baum,,,"
 114 \author ""
 115 \end_header
 116
 117 \begin_body
 118
 119 \begin_layout Title
 120 Customizing LyX: Features for the Advanced User
 121 \end_layout
 122
 123 \begin_layout Author
 124 by the LyX Team
 125 \begin_inset Foot
 126 status collapsed
 127
 128 \begin_layout Plain Layout
 129 \noindent
 130 If you have comments or error corrections, please send them to the LyX Documenta
 131 tion mailing list,
 132 \begin_inset CommandInset href
 133 LatexCommand href
 134 target "lyx-docs@lists.lyx.org"
 135 type "mailto:"
 136
 137 \end_inset
 138
 139 .
 140  Include
 141 \begin_inset Quotes eld
 142 \end_inset
 143
 144 [Customization]
 145 \begin_inset Quotes erd
 146 \end_inset
 147
 148  in the subject header, and please cc the current maintainer of this file,
 149  Richard Heck <rgheck@comcast.net>.
 150 \end_layout
 151
 152 \end_inset
 153
 154
 155 \begin_inset Newline newline
 156 \end_inset
 157
 158
 159 \begin_inset Newline newline
 160 \end_inset
 161
 162 Version 2.0.x
 163 \end_layout
 164
 165 \begin_layout Standard
 166 \begin_inset CommandInset toc
 167 LatexCommand tableofcontents
 168
 169 \end_inset
 170
 171
 172 \end_layout
 173
 174 \begin_layout Standard
 175 \begin_inset Note Note
 176 status open
 177
 178 \begin_layout Plain Layout
 179 Please use change tracking when modifying this document.
 180  This makes it easier for our translators to recognize things that have
 181  been changed, and it helps the maintainer keep up-to-date with what's been
 182  done.
 183 \end_layout
 184
 185 \end_inset
 186
 187
 188 \end_layout
 189
 190 \begin_layout Chapter
 191 Introduction
 192 \end_layout
 193
 194 \begin_layout Standard
 195 This manual covers the customization features present in LyX.
 196  In it, we discuss issues like keyboard shortcuts, screen previewing options,
 197  printer options, sending commands to LyX via the LyX Server, internationalizati
 198 on, installing new LaTeX classes and LyX layouts, etc.
 199  We can't possibly hope to touch on everything you can change—our developers
 200  add new features faster than we can document them—but we will explain the
 201  most common customizations and hopefully point you in the right direction
 202  for some of the more obscure ones.
 203 \end_layout
 204
 205 \begin_layout Standard
 206 \begin_inset Branch OutDated
 207 status open
 208
 209 \begin_layout Standard
 210 Information from previous versions of this document that now seems to be
 211  outdated is contained in the OutDated branch of this document.
 212  By default, this information will not appear in the LaTeX output.
 213 \end_layout
 214
 215 \end_inset
 216
 217
 218 \end_layout
 219
 220 \begin_layout Chapter
 221 LyX configuration files
 222 \end_layout
 223
 224 \begin_layout Standard
 225 This chapter aims to help you to find your way through the LyX configuration
 226  files.
 227  Before continuing to read this chapter, you should find out where your
 228  LyX library and user directories are by using
 229 \begin_inset Flex CharStyle:MenuItem
 230 status collapsed
 231
 232 \begin_layout Plain Layout
 233 Help\SpecialChar \menuseparator
 234 About
 235 \begin_inset space ~
 236 \end_inset
 237
 238 LyX
 239 \end_layout
 240
 241 \end_inset
 242
 243 .
 244  The library directory is the place where LyX places its system-wide configurati
 245 on files; the user directory is where you can place your modified versions.
 246  We will call the former
 247 \begin_inset Flex CharStyle:Code
 248 status collapsed
 249
 250 \begin_layout Plain Layout
 251 LyXDir
 252 \end_layout
 253
 254 \end_inset
 255
 256  and the latter
 257 \begin_inset Flex CharStyle:MenuItem
 258 status collapsed
 259
 260 \begin_layout Plain Layout
 261 UserDir
 262 \end_layout
 263
 264 \end_inset
 265
 266  in the remainder of this document.
 267
 268 \end_layout
 269
 270 \begin_layout Section
 271 What's in
 272 \begin_inset Flex CharStyle:Code
 273 status collapsed
 274
 275 \begin_layout Plain Layout
 276 LyXDir
 277 \end_layout
 278
 279 \end_inset
 280
 281 ?
 282 \end_layout
 283
 284 \begin_layout Standard
 285 \begin_inset Flex CharStyle:Code
 286 status collapsed
 287
 288 \begin_layout Plain Layout
 289 LyXDir
 290 \end_layout
 291
 292 \end_inset
 293
 294  and its sub-directories contain a number of files and that can be used
 295  to customize LyX's behavior.
 296  You can change many of these files from within LyX itself through the
 297 \begin_inset Flex CharStyle:MenuItem
 298 status collapsed
 299
 300 \begin_layout Plain Layout
 301 Tools\SpecialChar \menuseparator
 302 Preferences
 303 \end_layout
 304
 305 \end_inset
 306
 307  dialog.
 308  Most customization that you will want to do in LyX is possible through
 309  this dialog.
 310  However, many other inner aspects of LyX can be customized by modifying
 311  the files in
 312 \begin_inset Flex CharStyle:Code
 313 status collapsed
 314
 315 \begin_layout Plain Layout
 316 LyXDir
 317 \end_layout
 318
 319 \end_inset
 320
 321 .
 322  These files fall in different categories, described in the following subsection
 323 s.
 324 \end_layout
 325
 326 \begin_layout Subsection
 327 Automatically generated files
 328 \end_layout
 329
 330 \begin_layout Standard
 331 The files, which are to be found in
 332 \begin_inset Flex CharStyle:MenuItem
 333 status collapsed
 334
 335 \begin_layout Plain Layout
 336 UserDir
 337 \end_layout
 338
 339 \end_inset
 340
 341 , are generated when you configure LyX.
 342  They contain various default values that are guessed by inspection.
 343  In general, it is not a good idea to modify them, since they might be overwritt
 344 en at any time.
 345 \end_layout
 346
 347 \begin_layout Labeling
 348 \labelwidthstring 00.00.0000
 349 \begin_inset Flex CharStyle:Code
 350 status collapsed
 351
 352 \begin_layout Plain Layout
 353 lyxrc.defaults
 354 \end_layout
 355
 356 \end_inset
 357
 358  contains defaults for various commands.
 359 \end_layout
 360
 361 \begin_layout Labeling
 362 \labelwidthstring 00.00.0000
 363 \begin_inset Flex CharStyle:Code
 364 status collapsed
 365
 366 \begin_layout Plain Layout
 367 packages.lst
 368 \end_layout
 369
 370 \end_inset
 371
 372  contains the list of packages that have been recognized by LyX.
 373  It is currently unused by the LyX program itself, but the information extracted
 374 , and more, is made available with
 375 \begin_inset Flex CharStyle:MenuItem
 376 status collapsed
 377
 378 \begin_layout Plain Layout
 379 Help\SpecialChar \menuseparator
 380 LaTeX
 381 \begin_inset space ~
 382 \end_inset
 383
 384 Configuration
 385 \end_layout
 386
 387 \end_inset
 388
 389 .
 390 \end_layout
 391
 392 \begin_layout Labeling
 393 \labelwidthstring 00.00.0000
 394 \begin_inset Flex CharStyle:Code
 395 status collapsed
 396
 397 \begin_layout Plain Layout
 398 textclass.lst
 399 \end_layout
 400
 401 \end_inset
 402
 403  the list of text classes that have been found in your
 404 \begin_inset Flex CharStyle:Code
 405 status collapsed
 406
 407 \begin_layout Plain Layout
 408 layout/
 409 \end_layout
 410
 411 \end_inset
 412
 413  directories, along with the associated LaTeX document class and their descripti
 414 on.
 415 \end_layout
 416
 417 \begin_layout Labeling
 418 \labelwidthstring 00.00.0000
 419 \begin_inset Flex CharStyle:Code
 420 status collapsed
 421
 422 \begin_layout Plain Layout
 423 lyxmodules.lst
 424 \end_layout
 425
 426 \end_inset
 427
 428  the list of layout modules found in your
 429 \begin_inset Flex CharStyle:Code
 430 status collapsed
 431
 432 \begin_layout Plain Layout
 433 layout/
 434 \end_layout
 435
 436 \end_inset
 437
 438  directories
 439 \end_layout
 440
 441 \begin_layout Labeling
 442 \labelwidthstring 00.00.0000
 443 \begin_inset Flex CharStyle:Code
 444 status collapsed
 445
 446 \begin_layout Plain Layout
 447 *files.lst
 448 \end_layout
 449
 450 \end_inset
 451
 452  lists of various sorts of LaTeX-related files found on your system
 453 \end_layout
 454
 455 \begin_layout Labeling
 456 \labelwidthstring 00.00.0000
 457 \begin_inset Flex CharStyle:Code
 458 status collapsed
 459
 460 \begin_layout Plain Layout
 461 doc/LaTeXConfig.lyx
 462 \end_layout
 463
 464 \end_inset
 465
 466  is automatically generated during configuration from the file
 467 \begin_inset Flex CharStyle:Code
 468 status collapsed
 469
 470 \begin_layout Plain Layout
 471 LaTeXConfig.lyx.in
 472 \end_layout
 473
 474 \end_inset
 475
 476 .
 477  It contains information on your LaTeX configuration.
 478 \end_layout
 479
 480 \begin_layout Subsection
 481 Directories
 482 \end_layout
 483
 484 \begin_layout Standard
 485 These directories are duplicated between
 486 \begin_inset Flex CharStyle:Code
 487 status collapsed
 488
 489 \begin_layout Plain Layout
 490 LyXDir
 491 \end_layout
 492
 493 \end_inset
 494
 495  and
 496 \begin_inset Flex CharStyle:Code
 497 status collapsed
 498
 499 \begin_layout Plain Layout
 500 UserDir
 501 \end_layout
 502
 503 \end_inset
 504
 505 .
 506  If a particular files exists in both places, the one in
 507 \begin_inset Flex CharStyle:Code
 508 status collapsed
 509
 510 \begin_layout Plain Layout
 511 UserDir
 512 \end_layout
 513
 514 \end_inset
 515
 516  will be used.
 517 \end_layout
 518
 519 \begin_layout Labeling
 520 \labelwidthstring 00.00.0000
 521 \begin_inset Flex CharStyle:Code
 522 status collapsed
 523
 524 \begin_layout Plain Layout
 525 bind/
 526 \end_layout
 527
 528 \end_inset
 529
 530  this directory contains files with the extension
 531 \begin_inset Flex CharStyle:Code
 532 status collapsed
 533
 534 \begin_layout Plain Layout
 535 .bind
 536 \end_layout
 537
 538 \end_inset
 539
 540  that define the keybindings used in LyX.
 541  If there exists an internationalized version of the bind file named
 542 \begin_inset Flex CharStyle:Code
 543 status collapsed
 544
 545 \begin_layout Plain Layout
 546 $LANG_xxx.bind
 547 \end_layout
 548
 549 \end_inset
 550
 551 , that will be used first.
 552 \end_layout
 553
 554 \begin_layout Labeling
 555 \labelwidthstring 00.00.0000
 556 \begin_inset Flex CharStyle:Code
 557 status collapsed
 558
 559 \begin_layout Plain Layout
 560 clipart/
 561 \end_layout
 562
 563 \end_inset
 564
 565  contains graphics files that can be included in documents.
 566
 567 \end_layout
 568
 569 \begin_layout Labeling
 570 \labelwidthstring 00.00.0000
 571 \begin_inset Flex CharStyle:Code
 572 status collapsed
 573
 574 \begin_layout Plain Layout
 575 doc/
 576 \end_layout
 577
 578 \end_inset
 579
 580  contains LyX documentation files (including the one you are currently reading).
 581  The file
 582 \begin_inset Flex CharStyle:Code
 583 status collapsed
 584
 585 \begin_layout Plain Layout
 586 LaTeXConfig.lyx
 587 \end_layout
 588
 589 \end_inset
 590
 591  deserves special attention, as noted above.
 592  The internationalized help docs are in subdirectories
 593 \begin_inset Flex CharStyle:Code
 594 status collapsed
 595
 596 \begin_layout Plain Layout
 597 doc/xx
 598 \end_layout
 599
 600 \end_inset
 601
 602  where
 603 \begin_inset Quotes eld
 604 \end_inset
 605
 606 xx
 607 \begin_inset Quotes erd
 608 \end_inset
 609
 610  is the ISO language code.
 611  See chapter
 612 \begin_inset space ~
 613 \end_inset
 614
 615
 616 \begin_inset CommandInset ref
 617 LatexCommand ref
 618 reference "chap:i18n"
 619
 620 \end_inset
 621
 622  for details.
 623 \end_layout
 624
 625 \begin_layout Labeling
 626 \labelwidthstring 00.00.0000
 627 \begin_inset Flex CharStyle:Code
 628 status collapsed
 629
 630 \begin_layout Plain Layout
 631 examples/
 632 \end_layout
 633
 634 \end_inset
 635
 636  contains example files that explain how to use some features.
 637  In the file browser, press the
 638 \begin_inset Flex CharStyle:MenuItem
 639 status collapsed
 640
 641 \begin_layout Plain Layout
 642 Examples
 643 \end_layout
 644
 645 \end_inset
 646
 647  button to get there.
 648 \end_layout
 649
 650 \begin_layout Labeling
 651 \labelwidthstring 00.00.0000
 652 \begin_inset Flex CharStyle:Code
 653 status collapsed
 654
 655 \begin_layout Plain Layout
 656 images/
 657 \end_layout
 658
 659 \end_inset
 660
 661  contains image files that are used by the
 662 \begin_inset Flex CharStyle:MenuItem
 663 status collapsed
 664
 665 \begin_layout Plain Layout
 666 Document
 667 \end_layout
 668
 669 \end_inset
 670
 671  dialog.
 672  In addition, it also contains the individual icons used in the toolbar
 673  and the banners that can be shown when LyX is launched.
 674 \end_layout
 675
 676 \begin_layout Labeling
 677 \labelwidthstring 00.00.0000
 678 \begin_inset Flex CharStyle:Code
 679 status collapsed
 680
 681 \begin_layout Plain Layout
 682 kbd/
 683 \end_layout
 684
 685 \end_inset
 686
 687  contains keyboard keymapping files.
 688  See Chapter
 689 \begin_inset space ~
 690 \end_inset
 691
 692
 693 \begin_inset CommandInset ref
 694 LatexCommand ref
 695 reference "sec:keymap"
 696
 697 \end_inset
 698
 699  for details.
 700 \end_layout
 701
 702 \begin_layout Labeling
 703 \labelwidthstring 00.00.0000
 704 \begin_inset Flex CharStyle:Code
 705 status collapsed
 706
 707 \begin_layout Plain Layout
 708 layouts/
 709 \end_layout
 710
 711 \end_inset
 712
 713  contains the text class and module files described in Chapter
 714 \begin_inset space ~
 715 \end_inset
 716
 717
 718 \begin_inset CommandInset ref
 719 LatexCommand ref
 720 reference "chap:textclass"
 721
 722 \end_inset
 723
 724 .
 725 \end_layout
 726
 727 \begin_layout Labeling
 728 \labelwidthstring 00.00.0000
 729 \begin_inset Flex CharStyle:Code
 730 status collapsed
 731
 732 \begin_layout Plain Layout
 733 lyx2lyx
 734 \end_layout
 735
 736 \end_inset
 737
 738  contains the
 739 \begin_inset Flex CharStyle:Code
 740 status collapsed
 741
 742 \begin_layout Plain Layout
 743 lyx2lyx
 744 \end_layout
 745
 746 \end_inset
 747
 748  Python scripts used to convert between LyX versions.
 749  These can be run from the command line if, say, you want to batch-convert
 750  files.
 751 \end_layout
 752
 753 \begin_layout Labeling
 754 \labelwidthstring 00.00.0000
 755 \begin_inset Flex CharStyle:Code
 756 status collapsed
 757
 758 \begin_layout Plain Layout
 759 scripts/
 760 \end_layout
 761
 762 \end_inset
 763
 764  contains some files that demonstrate the capabilities of the
 765 \begin_inset Flex CharStyle:MenuItem
 766 status collapsed
 767
 768 \begin_layout Plain Layout
 769 External
 770 \begin_inset space ~
 771 \end_inset
 772
 773 Template
 774 \end_layout
 775
 776 \end_inset
 777
 778  feature.
 779  Also contains some scripts used by LyX itself.
 780 \end_layout
 781
 782 \begin_layout Labeling
 783 \labelwidthstring 00.00.0000
 784 \begin_inset Flex CharStyle:Code
 785 status collapsed
 786
 787 \begin_layout Plain Layout
 788 templates/
 789 \end_layout
 790
 791 \end_inset
 792
 793  contains the standard LyX template files described in Chapter
 794 \begin_inset space ~
 795 \end_inset
 796
 797
 798 \begin_inset CommandInset ref
 799 LatexCommand ref
 800 reference "sec:templates"
 801
 802 \end_inset
 803
 804 .
 805 \end_layout
 806
 807 \begin_layout Labeling
 808 \labelwidthstring 00.00.0000
 809 \begin_inset Flex CharStyle:Code
 810 status collapsed
 811
 812 \begin_layout Plain Layout
 813 ui/
 814 \end_layout
 815
 816 \end_inset
 817
 818  contains files with the extension
 819 \begin_inset Flex CharStyle:Code
 820 status collapsed
 821
 822 \begin_layout Plain Layout
 823 .ui
 824 \end_layout
 825
 826 \end_inset
 827
 828  that define the user interface to LyX.
 829  That is, the files define which items appear in which menus and the items
 830  appearing on the toolbar.
 831 \end_layout
 832
 833 \begin_layout Subsection
 834 Files you don't want to modify
 835 \end_layout
 836
 837 \begin_layout Standard
 838 These files are used internally by LyX and you generally do not need to
 839  modify them unless you are a developer.
 840 \end_layout
 841
 842 \begin_layout Labeling
 843 \labelwidthstring 00.00.0000
 844 \begin_inset Flex CharStyle:Code
 845 status collapsed
 846
 847 \begin_layout Plain Layout
 848 CREDITS
 849 \end_layout
 850
 851 \end_inset
 852
 853  this file contains the list of LyX developers.
 854  The contents are displayed with the menu entry
 855 \begin_inset Flex CharStyle:MenuItem
 856 status collapsed
 857
 858 \begin_layout Plain Layout
 859 Help\SpecialChar \menuseparator
 860 About
 861 \begin_inset space ~
 862 \end_inset
 863
 864 LyX
 865 \end_layout
 866
 867 \end_inset
 868
 869 .
 870 \end_layout
 871
 872 \begin_layout Labeling
 873 \labelwidthstring 00.00.0000
 874 \begin_inset Flex CharStyle:Code
 875 status collapsed
 876
 877 \begin_layout Plain Layout
 878 chkconfig.ltx
 879 \end_layout
 880
 881 \end_inset
 882
 883  this is a LaTeX script used during the configuration process.
 884  Do not run directly.
 885 \end_layout
 886
 887 \begin_layout Labeling
 888 \labelwidthstring 00.00.0000
 889 \begin_inset Flex CharStyle:Code
 890 status collapsed
 891
 892 \begin_layout Plain Layout
 893 configure.py
 894 \end_layout
 895
 896 \end_inset
 897
 898  this is the script that is used to re-configure LyX.
 899  It creates configuration files in the directory it was run from.
 900 \end_layout
 901
 902 \begin_layout Subsection
 903 Other files needing a line or two...
 904 \end_layout
 905
 906 \begin_layout Labeling
 907 \labelwidthstring 00.00.0000
 908 \begin_inset Flex CharStyle:Code
 909 status collapsed
 910
 911 \begin_layout Plain Layout
 912 encodings
 913 \end_layout
 914
 915 \end_inset
 916
 917  this contains tables describing how different character encodings can be
 918  mapped to Unicode
 919 \end_layout
 920
 921 \begin_layout Labeling
 922 \labelwidthstring 00.00.0000
 923 \begin_inset Flex CharStyle:Code
 924 status collapsed
 925
 926 \begin_layout Plain Layout
 927 external_templates
 928 \end_layout
 929
 930 \end_inset
 931
 932  this file contains the templates available to the new
 933 \begin_inset Flex CharStyle:MenuItem
 934 status collapsed
 935
 936 \begin_layout Plain Layout
 937 External
 938 \begin_inset space ~
 939 \end_inset
 940
 941 Template
 942 \end_layout
 943
 944 \end_inset
 945
 946  feature.
 947 \end_layout
 948
 949 \begin_layout Labeling
 950 \labelwidthstring 00.00.0000
 951 \begin_inset Flex CharStyle:Code
 952 status collapsed
 953
 954 \begin_layout Plain Layout
 955 languages
 956 \end_layout
 957
 958 \end_inset
 959
 960  this file contains a list of all the languages currently supported by LyX.
 961 \end_layout
 962
 963 \begin_layout Section
 964 Your local configuration directory
 965 \end_layout
 966
 967 \begin_layout Standard
 968 Even if you are using LyX as an unprivileged user, you might want to change
 969  LyX configuration for your own use.
 970  The
 971 \begin_inset Flex CharStyle:Code
 972 status collapsed
 973
 974 \begin_layout Plain Layout
 975 UserDir
 976 \end_layout
 977
 978 \end_inset
 979
 980  directory contains all your personal configuration files.
 981  This is the directory described as
 982 \begin_inset Quotes eld
 983 \end_inset
 984
 985 user directory
 986 \begin_inset Quotes erd
 987 \end_inset
 988
 989  in
 990 \begin_inset Flex CharStyle:MenuItem
 991 status collapsed
 992
 993 \begin_layout Plain Layout
 994 Help\SpecialChar \menuseparator
 995 About
 996 \begin_inset space ~
 997 \end_inset
 998
 999 LyX
1000 \end_layout
1001
1002 \end_inset
1003
1004 .
1005  This directory is used as a mirror of
1006 \begin_inset Flex CharStyle:Code
1007 status collapsed
1008
1009 \begin_layout Plain Layout
1010 LyXDir
1011 \end_layout
1012
1013 \end_inset
1014
1015 , which means that every file in
1016 \begin_inset Flex CharStyle:Code
1017 status collapsed
1018
1019 \begin_layout Plain Layout
1020 UserDir
1021 \end_layout
1022
1023 \end_inset
1024
1025  is a replacement for the corresponding file in
1026 \begin_inset Flex CharStyle:Code
1027 status collapsed
1028
1029 \begin_layout Plain Layout
1030 LyXDir
1031 \end_layout
1032
1033 \end_inset
1034
1035 .
1036  Any configuration file described in the above sections can be placed either
1037  in the system-wide directory, in which case it will affect all users, or
1038  in your local directory for your own use.
1039 \end_layout
1040
1041 \begin_layout Standard
1042 To make things clearer, let's provide a few examples:
1043 \end_layout
1044
1045 \begin_layout Itemize
1046 The preferences set in the
1047 \begin_inset Flex CharStyle:MenuItem
1048 status collapsed
1049
1050 \begin_layout Plain Layout
1051 Tools\SpecialChar \menuseparator
1052 Preferences
1053 \end_layout
1054
1055 \end_inset
1056
1057  dialog are saved to a file
1058 \begin_inset Flex CharStyle:Code
1059 status collapsed
1060
1061 \begin_layout Plain Layout
1062 preferences
1063 \end_layout
1064
1065 \end_inset
1066
1067  in
1068 \begin_inset Flex CharStyle:Code
1069 status collapsed
1070
1071 \begin_layout Plain Layout
1072 UserDir
1073 \end_layout
1074
1075 \end_inset
1076
1077 .
1078 \end_layout
1079
1080 \begin_layout Itemize
1081 When you reconfigure using
1082 \begin_inset Flex CharStyle:MenuItem
1083 status collapsed
1084
1085 \begin_layout Plain Layout
1086 Tools\SpecialChar \menuseparator
1087 Reconfigure
1088 \end_layout
1089
1090 \end_inset
1091
1092 , LyX runs the
1093 \begin_inset Flex CharStyle:Code
1094 status collapsed
1095
1096 \begin_layout Plain Layout
1097 configure.py
1098 \end_layout
1099
1100 \end_inset
1101
1102  script, and the resulting files are written in your local configuration
1103  directory.
1104  This means that any additional text class file that you might have added
1105  in
1106 \begin_inset Flex CharStyle:Code
1107 status collapsed
1108
1109 \begin_layout Plain Layout
1110 UserDir/layouts
1111 \end_layout
1112
1113 \end_inset
1114
1115  will be added to the list of classes in the
1116 \begin_inset Flex CharStyle:MenuItem
1117 status collapsed
1118
1119 \begin_layout Plain Layout
1120 Document\SpecialChar \menuseparator
1121 Settings
1122 \end_layout
1123
1124 \end_inset
1125
1126  dialog.
1127 \end_layout
1128
1129 \begin_layout Itemize
1130 If you get some updated documentation from LyX ftp site and cannot install
1131  it because you do not have sysadmin rights on your system, you can just
1132  copy the files in
1133 \begin_inset Flex CharStyle:Code
1134 status collapsed
1135
1136 \begin_layout Plain Layout
1137 UserDir/doc/
1138 \end_layout
1139
1140 \end_inset
1141
1142  and the items in the
1143 \begin_inset Flex CharStyle:MenuItem
1144 status collapsed
1145
1146 \begin_layout Plain Layout
1147 Help
1148 \end_layout
1149
1150 \end_inset
1151
1152  menu will open them!
1153 \end_layout
1154
1155 \begin_layout Section
1156 Running LyX with multiple configurations
1157 \end_layout
1158
1159 \begin_layout Standard
1160 The configuration freedom of the local configuration directory may not suffice
1161  if you want to have more than one configuration at your disposal.
1162  For example, you may want to be use different key bindings or printer settings
1163  at different times.
1164  You can achieve this by having several such directories.
1165  You then specify which directory to use at run-time.
1166 \end_layout
1167
1168 \begin_layout Standard
1169 Invoking LyX with the command line switch
1170 \begin_inset Flex CharStyle:Code
1171 status collapsed
1172
1173 \begin_layout Plain Layout
1174 -userdir
1175 \end_layout
1176
1177 \end_inset
1178
1179
1180 \emph on
1181 <some directory>
1182 \emph default
1183  instructs the program to read the configuration from that directory, and
1184  not from the default directory.
1185  (You can determine the default directory by running LyX without the
1186 \begin_inset Flex CharStyle:Code
1187 status collapsed
1188
1189 \begin_layout Plain Layout
1190 -userdir
1191 \end_layout
1192
1193 \end_inset
1194
1195  switch.) If the specified directory does not exist, LyX offers to create
1196  it for you, just like it does for the default directory on the first time
1197  you run the program.
1198  You can modify the configuration options in this additional user directory
1199  exactly as you would for the default directory.
1200  These directories are completely independent (but read on).
1201  Note that setting the environment variable
1202 \begin_inset Flex CharStyle:Code
1203 status collapsed
1204
1205 \begin_layout Plain Layout
1206 LYX_USERDIR_VER
1207 \end_layout
1208
1209 \end_inset
1210
1211  to some value has exactly the same effect.
1212 \end_layout
1213
1214 \begin_layout Standard
1215 Having several configurations also requires more maintenance: if you want
1216  to add a new layout to
1217 \begin_inset Flex CharStyle:Code
1218 status collapsed
1219
1220 \begin_layout Plain Layout
1221 NewUserDir/layouts
1222 \end_layout
1223
1224 \end_inset
1225
1226  which you want available from all your configurations, you must add it
1227  to each directory separately.
1228  You can avoid this with the following trick: after LyX creates the additional
1229  directory, most of the subdirectories (see above) are empty.
1230  If you want the new configuration to mirror an existing one, replace the
1231  empty subdirectory with a symbolic link to the matching subdirectory in
1232  the existing configuration.
1233  Take care with the
1234 \begin_inset Flex CharStyle:Code
1235 status collapsed
1236
1237 \begin_layout Plain Layout
1238 doc/
1239 \end_layout
1240
1241 \end_inset
1242
1243  subdirectory, however, since it contains a file written by the configuration
1244  script (also accessible through
1245 \begin_inset Flex CharStyle:MenuItem
1246 status collapsed
1247
1248 \begin_layout Plain Layout
1249 Tools\SpecialChar \menuseparator
1250 Reconfigure
1251 \end_layout
1252
1253 \end_inset
1254
1255 ) which is configuration-specific.
1256 \end_layout
1257
1258 \begin_layout Chapter
1259 The Preferences dialog
1260 \end_layout
1261
1262 \begin_layout Standard
1263 All options of the preferences dialog are described in the Appendix
1264 \emph on
1265 The Preferences Dialog
1266 \emph default
1267  in the
1268 \emph on
1269 User's Guide
1270 \emph default
1271 .
1272  For some options you might find here more details.
1273 \end_layout
1274
1275 \begin_layout Section
1276 Using the dialog for the first time
1277 \end_layout
1278
1279 \begin_layout Standard
1280 The
1281 \begin_inset Flex CharStyle:Code
1282 status collapsed
1283
1284 \begin_layout Plain Layout
1285 UserDir/preferences
1286 \end_layout
1287
1288 \end_inset
1289
1290  file will contain only changes that you have made to the default behavior,
1291  some of which is hard-coded into LyX and some of which is contained in
1292  the system file
1293 \begin_inset Flex CharStyle:Code
1294 status collapsed
1295
1296 \begin_layout Plain Layout
1297 LyXDir/lyxrc.defaults
1298 \end_layout
1299
1300 \end_inset
1301
1302 .
1303  Note that in both files lines beginning with a
1304 \begin_inset Quotes eld
1305 \end_inset
1306
1307 #
1308 \begin_inset Quotes erd
1309 \end_inset
1310
1311  are just comments and are not interpreted.
1312  However, only system administrators should edit
1313 \begin_inset Flex CharStyle:Code
1314 status collapsed
1315
1316 \begin_layout Plain Layout
1317 LyXDir/lyxrc.defaults
1318 \end_layout
1319
1320 \end_inset
1321
1322 .
1323  Users should use the
1324 \begin_inset Flex CharStyle:MenuItem
1325 status collapsed
1326
1327 \begin_layout Plain Layout
1328 Tools\SpecialChar \menuseparator
1329 Preferences
1330 \end_layout
1331
1332 \end_inset
1333
1334  dialog to create and modify their own
1335 \begin_inset Flex CharStyle:Code
1336 status collapsed
1337
1338 \begin_layout Plain Layout
1339 UserDir/preferences
1340 \end_layout
1341
1342 \end_inset
1343
1344  file.
1345 \end_layout
1346
1347 \begin_layout Standard
1348 We hope that the
1349 \begin_inset Flex CharStyle:MenuItem
1350 status collapsed
1351
1352 \begin_layout Plain Layout
1353 Tools\SpecialChar \menuseparator
1354 Preferences
1355 \end_layout
1356
1357 \end_inset
1358
1359  dialog will be largely self-explanatory.
1360  Most things in the dialog have associated `tool tips': hover your mouse
1361  pointer over something for more information.
1362  Before we highlight a few of the more important commands below, however,
1363  a word of warning: Applying some of your changes (e.
1364 \begin_inset space \thinspace{}
1365 \end_inset
1366
1367 g.
1368 \begin_inset space \space{}
1369 \end_inset
1370
1371 screen fonts) will have an instant effect.
1372  Others (e.
1373 \begin_inset space \thinspace{}
1374 \end_inset
1375
1376 g.
1377 \begin_inset space \space{}
1378 \end_inset
1379
1380 changing the bind file) will not.
1381  If nothing appears to have changed, just
1382 \begin_inset Flex CharStyle:MenuItem
1383 status collapsed
1384
1385 \begin_layout Plain Layout
1386 Save
1387 \end_layout
1388
1389 \end_inset
1390
1391  the changes and restart LyX.
1392 \end_layout
1393
1394 \begin_layout Section
1395 File Handling
1396 \end_layout
1397
1398 \begin_layout Standard
1399 LyX has a powerful mechanism to convert to and from any file format using
1400  external programs.
1401
1402 \end_layout
1403
1404 \begin_layout Subsection
1405 \begin_inset CommandInset label
1406 LatexCommand label
1407 name "sub:Formats"
1408
1409 \end_inset
1410
1411 Formats
1412 \end_layout
1413
1414 \begin_layout Standard
1415 The first step is to define your file formats if they are not already defined.
1416  To do so, open the
1417 \begin_inset Flex CharStyle:MenuItem
1418 status collapsed
1419
1420 \begin_layout Plain Layout
1421 Tools\SpecialChar \menuseparator
1422 Preferences
1423 \end_layout
1424
1425 \end_inset
1426
1427  dialog.
1428  Under
1429 \begin_inset Flex CharStyle:MenuItem
1430 status collapsed
1431
1432 \begin_layout Plain Layout
1433 File Handling\SpecialChar \menuseparator
1434 File formats
1435 \end_layout
1436
1437 \end_inset
1438
1439  press the
1440 \begin_inset Flex CharStyle:MenuItem
1441 status collapsed
1442
1443 \begin_layout Plain Layout
1444 New\SpecialChar \ldots{}
1445
1446 \end_layout
1447
1448 \end_inset
1449
1450  button to define your new format.
1451  The
1452 \begin_inset Flex CharStyle:MenuItem
1453 status collapsed
1454
1455 \begin_layout Plain Layout
1456 Format
1457 \end_layout
1458
1459 \end_inset
1460
1461  field contains the named used to identify the format in the GUI.
1462  The
1463 \begin_inset Flex CharStyle:MenuItem
1464 status collapsed
1465
1466 \begin_layout Plain Layout
1467 Short Name
1468 \end_layout
1469
1470 \end_inset
1471
1472  is used to identify the format internally.
1473  You will also need to enter a file extension.
1474  These are all required.
1475  The optional
1476 \begin_inset Flex CharStyle:MenuItem
1477 status collapsed
1478
1479 \begin_layout Plain Layout
1480 Shortcut
1481 \end_layout
1482
1483 \end_inset
1484
1485  field is used to provide a keyboard shortcut on the menus.
1486  (For example, pressing
1487 \begin_inset Flex CharStyle:MenuItem
1488 status collapsed
1489
1490 \begin_layout Plain Layout
1491 Alt-V D
1492 \end_layout
1493
1494 \end_inset
1495
1496  will
1497 \begin_inset Flex CharStyle:MenuItem
1498 status collapsed
1499
1500 \begin_layout Plain Layout
1501 View\SpecialChar \menuseparator
1502 DVI
1503 \end_layout
1504
1505 \end_inset
1506
1507 .)
1508 \end_layout
1509
1510 \begin_layout Standard
1511 A Format can have a
1512 \begin_inset Flex CharStyle:MenuItem
1513 status collapsed
1514
1515 \begin_layout Plain Layout
1516 Viewer
1517 \end_layout
1518
1519 \end_inset
1520
1521  and
1522 \begin_inset Flex CharStyle:MenuItem
1523 status collapsed
1524
1525 \begin_layout Plain Layout
1526 Editor
1527 \end_layout
1528
1529 \end_inset
1530
1531  associated with it.
1532  For example, you might want to use
1533 \begin_inset Flex CharStyle:MenuItem
1534 status collapsed
1535
1536 \begin_layout Plain Layout
1537 Ghostview
1538 \end_layout
1539
1540 \end_inset
1541
1542  to view PostScript files.
1543  You can enter the command needed to start the program in the corresponding
1544  fields.
1545  In defining this command, you can use the four variables listed in the
1546  next section.
1547  The viewer is launched when you view an image in LyX or use the
1548 \begin_inset Flex CharStyle:MenuItem
1549 status collapsed
1550
1551 \begin_layout Plain Layout
1552 View
1553 \end_layout
1554
1555 \end_inset
1556
1557  menu.
1558  The editor is for example launched when you press the
1559 \begin_inset Flex CharStyle:MenuItem
1560 status collapsed
1561
1562 \begin_layout Plain Layout
1563 Edit
1564 \end_layout
1565
1566 \end_inset
1567
1568  button in the
1569 \begin_inset Flex CharStyle:MenuItem
1570 status collapsed
1571
1572 \begin_layout Plain Layout
1573 Graphics
1574 \end_layout
1575
1576 \end_inset
1577
1578  or the
1579 \begin_inset Flex CharStyle:MenuItem
1580 status collapsed
1581
1582 \begin_layout Plain Layout
1583 External material
1584 \end_layout
1585
1586 \end_inset
1587
1588  dialog.
1589 \end_layout
1590
1591 \begin_layout Standard
1592 The
1593 \begin_inset Flex CharStyle:MenuItem
1594 status collapsed
1595
1596 \begin_layout Plain Layout
1597 Document format
1598 \end_layout
1599
1600 \end_inset
1601
1602  option tells LyX that a format is suitable for document export.
1603  If this is is set and if a suitable conversion route exists (see
1604 \begin_inset CommandInset ref
1605 LatexCommand ref
1606 reference "sub:Converters"
1607
1608 \end_inset
1609
1610 ), the format will appear in the
1611 \begin_inset Flex CharStyle:MenuItem
1612 status collapsed
1613
1614 \begin_layout Plain Layout
1615 File\SpecialChar \menuseparator
1616 Export
1617 \end_layout
1618
1619 \end_inset
1620
1621  menu.
1622  The format will also appear in the
1623 \begin_inset Flex CharStyle:MenuItem
1624 status collapsed
1625
1626 \begin_layout Plain Layout
1627 View
1628 \end_layout
1629
1630 \end_inset
1631
1632  menu if a viewer is specified for the format.
1633  Pure image formats, such as
1634 \begin_inset Flex CharStyle:Code
1635 status collapsed
1636
1637 \begin_layout Plain Layout
1638 png
1639 \end_layout
1640
1641 \end_inset
1642
1643 , should not use this option.
1644  Formats that can both represent vector graphics and documents like
1645 \begin_inset Flex CharStyle:Code
1646 status collapsed
1647
1648 \begin_layout Plain Layout
1649 pdf
1650 \end_layout
1651
1652 \end_inset
1653
1654  should use it.
1655 \end_layout
1656
1657 \begin_layout Standard
1658 The option
1659 \begin_inset Flex CharStyle:MenuItem
1660 status collapsed
1661
1662 \begin_layout Plain Layout
1663 Vector graphics format
1664 \end_layout
1665
1666 \end_inset
1667
1668  tells LyX that a format can contain vector graphics.
1669  This information is used to determine the target format of included graphics
1670  for
1671 \begin_inset Flex CharStyle:MenuItem
1672 status collapsed
1673
1674 \begin_layout Plain Layout
1675 pdflatex
1676 \end_layout
1677
1678 \end_inset
1679
1680  export.
1681  Included graphics may need to be converted to either
1682 \begin_inset Flex CharStyle:MenuItem
1683 status collapsed
1684
1685 \begin_layout Plain Layout
1686 pdf
1687 \end_layout
1688
1689 \end_inset
1690
1691 ,
1692 \begin_inset Flex CharStyle:MenuItem
1693 status collapsed
1694
1695 \begin_layout Plain Layout
1696 png
1697 \end_layout
1698
1699 \end_inset
1700
1701 , or
1702 \begin_inset Flex CharStyle:MenuItem
1703 status collapsed
1704
1705 \begin_layout Plain Layout
1706 jpg
1707 \end_layout
1708
1709 \end_inset
1710
1711 , since
1712 \begin_inset Flex CharStyle:MenuItem
1713 status collapsed
1714
1715 \begin_layout Plain Layout
1716 pdflatex
1717 \end_layout
1718
1719 \end_inset
1720
1721  cannot handle other image formats.
1722  If an included graphic is not already in
1723 \begin_inset Flex CharStyle:MenuItem
1724 status collapsed
1725
1726 \begin_layout Plain Layout
1727 pdf
1728 \end_layout
1729
1730 \end_inset
1731
1732 ,
1733 \begin_inset Flex CharStyle:MenuItem
1734 status collapsed
1735
1736 \begin_layout Plain Layout
1737 png
1738 \end_layout
1739
1740 \end_inset
1741
1742 , or
1743 \begin_inset Flex CharStyle:MenuItem
1744 status collapsed
1745
1746 \begin_layout Plain Layout
1747 jpg
1748 \end_layout
1749
1750 \end_inset
1751
1752  format, it is converted to
1753 \begin_inset Flex CharStyle:MenuItem
1754 status collapsed
1755
1756 \begin_layout Plain Layout
1757 pdf
1758 \end_layout
1759
1760 \end_inset
1761
1762  if the vector format option is set, and otherwise to
1763 \begin_inset Flex CharStyle:MenuItem
1764 status collapsed
1765
1766 \begin_layout Plain Layout
1767 png
1768 \end_layout
1769
1770 \end_inset
1771
1772 .
1773 \end_layout
1774
1775 \begin_layout Subsection
1776 Copiers
1777 \end_layout
1778
1779 \begin_layout Standard
1780 Since all conversions from one format to another take place in LyX's temporary
1781  directory, it is sometimes necessary to modify a file before copying it
1782  to the temporary directory in order that the conversion may be performed.
1783 \begin_inset Foot
1784 status collapsed
1785
1786 \begin_layout Plain Layout
1787 For example, the file may refer to other files—images, for example—using
1788  relative file names, and these may become invalid when the file is copied
1789  to the temporary directory.
1790 \end_layout
1791
1792 \end_inset
1793
1794  This is done by a Copier: It copies a file to (or from) the temporary directory
1795  and may modify it in the process.
1796 \end_layout
1797
1798 \begin_layout Standard
1799 The definitions of the copiers may use four variables:
1800 \end_layout
1801
1802 \begin_layout Labeling
1803 \labelwidthstring 00.00.0000
1804 \begin_inset Flex CharStyle:Code
1805 status collapsed
1806
1807 \begin_layout Plain Layout
1808 $$s
1809 \end_layout
1810
1811 \end_inset
1812
1813  The LyX system directory (e.
1814 \begin_inset space \thinspace{}
1815 \end_inset
1816
1817 g.
1818 \begin_inset space \space{}
1819 \end_inset
1820
1821
1822 \begin_inset Flex CharStyle:MenuItem
1823 status collapsed
1824
1825 \begin_layout Plain Layout
1826 /usr/share/lyx
1827 \end_layout
1828
1829 \end_inset
1830
1831 ).
1832 \end_layout
1833
1834 \begin_layout Labeling
1835 \labelwidthstring 00.00.0000
1836 \begin_inset Flex CharStyle:Code
1837 status collapsed
1838
1839 \begin_layout Plain Layout
1840 $$i
1841 \end_layout
1842
1843 \end_inset
1844
1845  The input file
1846 \end_layout
1847
1848 \begin_layout Labeling
1849 \labelwidthstring 00.00.0000
1850 \begin_inset Flex CharStyle:Code
1851 status collapsed
1852
1853 \begin_layout Plain Layout
1854 $$o
1855 \end_layout
1856
1857 \end_inset
1858
1859  The output file
1860 \end_layout
1861
1862 \begin_layout Labeling
1863 \labelwidthstring 00.00.0000
1864 \begin_inset Flex CharStyle:Code
1865 status collapsed
1866
1867 \begin_layout Plain Layout
1868 $$l
1869 \end_layout
1870
1871 \end_inset
1872
1873  The `LaTeX name'
1874 \end_layout
1875
1876 \begin_layout Standard
1877 The latter should be the filename as it would be used in a LaTeX's
1878 \series bold
1879
1880 \backslash
1881 include
1882 \series default
1883  command.
1884  It is relevant only when exporting files suitable for such inclusion.
1885 \end_layout
1886
1887 \begin_layout Standard
1888 Copiers can be used to do almost anything with output files.
1889  For example, suppose you want generated pdf files to be copied to a special
1890  directory,
1891 \begin_inset Flex CharStyle:Code
1892 status collapsed
1893
1894 \begin_layout Plain Layout
1895 /home/you/pdf/
1896 \end_layout
1897
1898 \end_inset
1899
1900 .
1901  Then you could write a shell script such as this one:
1902 \end_layout
1903
1904 \begin_layout Standard
1905 \begin_inset listings
1906 inline false
1907 status open
1908
1909 \begin_layout Plain Layout
1910
1911 #!/bin/bash
1912 \end_layout
1913
1914 \begin_layout Plain Layout
1915
1916 FROMFILE=$1
1917 \end_layout
1918
1919 \begin_layout Plain Layout
1920
1921 TOFILE=`basename $2`
1922 \end_layout
1923
1924 \begin_layout Plain Layout
1925
1926 cp $FROMFILE /home/you/pdf/$TOFILE
1927 \end_layout
1928
1929 \end_inset
1930
1931 Save that in your local LyX directory—say,
1932 \begin_inset Flex CharStyle:Code
1933 status collapsed
1934
1935 \begin_layout Plain Layout
1936 /home/you/.lyx/scripts/pdfcopier.sh
1937 \end_layout
1938
1939 \end_inset
1940
1941 —and make it executable, if you need to do so on your platform.
1942  Then, in the
1943 \begin_inset Flex CharStyle:MenuItem
1944 status collapsed
1945
1946 \begin_layout Plain Layout
1947 Tools\SpecialChar \menuseparator
1948 Preferences
1949 \end_layout
1950
1951 \end_inset
1952
1953  dialog, select under
1954 \begin_inset Flex CharStyle:MenuItem
1955 status collapsed
1956
1957 \begin_layout Plain Layout
1958 File Handling\SpecialChar \menuseparator
1959 File formats
1960 \end_layout
1961
1962 \end_inset
1963
1964  the
1965 \begin_inset Flex CharStyle:MenuItem
1966 status collapsed
1967
1968 \begin_layout Plain Layout
1969 PDF(pdflatex)
1970 \end_layout
1971
1972 \end_inset
1973
1974  format—or one of the other pdf formats—and enter
1975 \begin_inset Flex CharStyle:Code
1976 status collapsed
1977
1978 \begin_layout Plain Layout
1979 pdfcopier.sh $$i $$o
1980 \end_layout
1981
1982 \end_inset
1983
1984  into the
1985 \begin_inset Flex CharStyle:MenuItem
1986 status collapsed
1987
1988 \begin_layout Plain Layout
1989 Copier
1990 \end_layout
1991
1992 \end_inset
1993
1994  field.
1995
1996 \end_layout
1997
1998 \begin_layout Standard
1999 Copiers are used by LyX in various of its own conversions.
2000  For example, if appropriate programs are found, LyX will automatically
2001  install copiers for the
2002 \begin_inset Flex CharStyle:MenuItem
2003 status collapsed
2004
2005 \begin_layout Plain Layout
2006 HTML
2007 \end_layout
2008
2009 \end_inset
2010
2011  and
2012 \begin_inset Flex CharStyle:MenuItem
2013 status collapsed
2014
2015 \begin_layout Plain Layout
2016 HTML
2017 \begin_inset space ~
2018 \end_inset
2019
2020 (MS Word)
2021 \end_layout
2022
2023 \end_inset
2024
2025  formats.
2026  When these formats are exported, the copier sees that not just the main
2027  HTML file but various associated files (style files, images, etc.) are also
2028  copied.
2029  All these files are written to a subdirectory of the directory in which
2030  the original LyX file was found.
2031 \begin_inset Foot
2032 status collapsed
2033
2034 \begin_layout Plain Layout
2035 This copier can be customized.
2036  The optional
2037 \begin_inset Quotes eld
2038 \end_inset
2039
2040 -e
2041 \begin_inset Quotes erd
2042 \end_inset
2043
2044  argument takes a comma-separated list of extensions to be copied; if it
2045  is omitted, all files will be copied.
2046  The
2047 \begin_inset Quotes eld
2048 \end_inset
2049
2050 -t
2051 \begin_inset Quotes erd
2052 \end_inset
2053
2054  argument determines the extension added to the generated directory.
2055  By default, it is
2056 \begin_inset Quotes eld
2057 \end_inset
2058
2059
2060 \begin_inset Flex CharStyle:MenuItem
2061 status collapsed
2062
2063 \begin_layout Plain Layout
2064 LyXconv
2065 \end_layout
2066
2067 \end_inset
2068
2069
2070 \begin_inset Quotes erd
2071 \end_inset
2072
2073 , so HTML generated from
2074 \begin_inset Flex CharStyle:MenuItem
2075 status collapsed
2076
2077 \begin_layout Plain Layout
2078 /path/to/filename.lyx
2079 \end_layout
2080
2081 \end_inset
2082
2083  will end up in
2084 \begin_inset Flex CharStyle:MenuItem
2085 status collapsed
2086
2087 \begin_layout Plain Layout
2088 /path/to/filename.html.LyXconv
2089 \end_layout
2090
2091 \end_inset
2092
2093 .
2094
2095 \end_layout
2096
2097 \end_inset
2098
2099
2100 \end_layout
2101
2102 \begin_layout Subsection
2103 \begin_inset CommandInset label
2104 LatexCommand label
2105 name "sub:Converters"
2106
2107 \end_inset
2108
2109 Converters
2110 \end_layout
2111
2112 \begin_layout Standard
2113 You can define your own Converters to convert files between different formats.
2114  This is done in the
2115 \begin_inset Flex CharStyle:MenuItem
2116 status collapsed
2117
2118 \begin_layout Plain Layout
2119 Tools\SpecialChar \menuseparator
2120 Preferences\SpecialChar \menuseparator
2121 File Handling\SpecialChar \menuseparator
2122 Converters
2123 \end_layout
2124
2125 \end_inset
2126
2127  dialog.
2128 \end_layout
2129
2130 \begin_layout Standard
2131 To define a new converter, select the
2132 \begin_inset Flex CharStyle:MenuItem
2133 status collapsed
2134
2135 \begin_layout Plain Layout
2136 From
2137 \begin_inset space ~
2138 \end_inset
2139
2140 format
2141 \end_layout
2142
2143 \end_inset
2144
2145  and
2146 \begin_inset Flex CharStyle:MenuItem
2147 status collapsed
2148
2149 \begin_layout Plain Layout
2150 To
2151 \begin_inset space ~
2152 \end_inset
2153
2154 format
2155 \end_layout
2156
2157 \end_inset
2158
2159  from the drop-down lists, enter the command needed for the conversion,
2160  and then press the
2161 \begin_inset Flex CharStyle:MenuItem
2162 status collapsed
2163
2164 \begin_layout Plain Layout
2165 Add
2166 \end_layout
2167
2168 \end_inset
2169
2170  button.
2171  Several variables can be used in the definition of converters:
2172 \end_layout
2173
2174 \begin_layout Labeling
2175 \labelwidthstring 00.00.0000
2176 \begin_inset Flex CharStyle:Code
2177 status collapsed
2178
2179 \begin_layout Plain Layout
2180 $$s
2181 \end_layout
2182
2183 \end_inset
2184
2185  The LyX system directory
2186 \end_layout
2187
2188 \begin_layout Labeling
2189 \labelwidthstring 00.00.0000
2190 \begin_inset Flex CharStyle:Code
2191 status collapsed
2192
2193 \begin_layout Plain Layout
2194 $$i
2195 \end_layout
2196
2197 \end_inset
2198
2199  The input file
2200 \end_layout
2201
2202 \begin_layout Labeling
2203 \labelwidthstring 00.00.0000
2204 \begin_inset Flex CharStyle:Code
2205 status collapsed
2206
2207 \begin_layout Plain Layout
2208 $$o
2209 \end_layout
2210
2211 \end_inset
2212
2213  The output file
2214 \end_layout
2215
2216 \begin_layout Labeling
2217 \labelwidthstring 00.00.0000
2218 \begin_inset Flex CharStyle:Code
2219 status collapsed
2220
2221 \begin_layout Plain Layout
2222 $$b
2223 \end_layout
2224
2225 \end_inset
2226
2227  The base filename of the input file (i.
2228 \begin_inset space \thinspace{}
2229 \end_inset
2230
2231 g., without the extension)
2232 \end_layout
2233
2234 \begin_layout Labeling
2235 \labelwidthstring 00.00.0000
2236 \begin_inset Flex CharStyle:Code
2237 status collapsed
2238
2239 \begin_layout Plain Layout
2240 $$p
2241 \end_layout
2242
2243 \end_inset
2244
2245  The path to the input file
2246 \end_layout
2247
2248 \begin_layout Labeling
2249 \labelwidthstring 00.00.0000
2250 \begin_inset Flex CharStyle:Code
2251 status collapsed
2252
2253 \begin_layout Plain Layout
2254 $$r
2255 \end_layout
2256
2257 \end_inset
2258
2259  The path to the original input file (this is different from $$p when chain
2260  of converters is called).
2261 \end_layout
2262
2263 \begin_layout Standard
2264 In the
2265 \begin_inset Flex CharStyle:MenuItem
2266 status collapsed
2267
2268 \begin_layout Plain Layout
2269 Extra
2270 \begin_inset space ~
2271 \end_inset
2272
2273 Flag
2274 \end_layout
2275
2276 \end_inset
2277
2278  field you can enter the following flags, separated by commas:
2279 \end_layout
2280
2281 \begin_layout Labeling
2282 \labelwidthstring 00.00.0000
2283 \begin_inset Flex CharStyle:Code
2284 status collapsed
2285
2286 \begin_layout Plain Layout
2287 latex
2288 \end_layout
2289
2290 \end_inset
2291
2292  This converter runs some form of LaTeX.
2293  This will make LyX's LaTeX error logs available.
2294 \end_layout
2295
2296 \begin_layout Labeling
2297 \labelwidthstring 00.00.0000
2298 \begin_inset Flex CharStyle:Code
2299 status collapsed
2300
2301 \begin_layout Plain Layout
2302 needaux
2303 \end_layout
2304
2305 \end_inset
2306
2307  Needs the LaTeX
2308 \begin_inset Flex CharStyle:MenuItem
2309 status collapsed
2310
2311 \begin_layout Plain Layout
2312 .aux
2313 \end_layout
2314
2315 \end_inset
2316
2317  file for the conversion.
2318 \end_layout
2319
2320 \begin_layout Labeling
2321 \labelwidthstring 00.00.0000
2322 \begin_inset Flex CharStyle:Code
2323 status collapsed
2324
2325 \begin_layout Plain Layout
2326 xml
2327 \end_layout
2328
2329 \end_inset
2330
2331  Output is XML.
2332 \end_layout
2333
2334 \begin_layout Standard
2335 The following three flags are not really flags at all because they take
2336  an argument in the
2337 \begin_inset Flex CharStyle:MenuItem
2338 status collapsed
2339
2340 \begin_layout Plain Layout
2341 key
2342 \begin_inset space ~
2343 \end_inset
2344
2345 =
2346 \begin_inset space ~
2347 \end_inset
2348
2349 value
2350 \end_layout
2351
2352 \end_inset
2353
2354  format:
2355 \end_layout
2356
2357 \begin_layout Labeling
2358 \labelwidthstring 00.00.0000
2359 \begin_inset Flex CharStyle:Code
2360 status collapsed
2361
2362 \begin_layout Plain Layout
2363 parselog
2364 \end_layout
2365
2366 \end_inset
2367
2368  If set, the converter's standard error will be redirected to a file
2369 \begin_inset Flex CharStyle:Code
2370 status collapsed
2371
2372 \begin_layout Plain Layout
2373 infile.out
2374 \end_layout
2375
2376 \end_inset
2377
2378 , and the script given as argument will be run as:
2379 \begin_inset Flex CharStyle:Code
2380 status collapsed
2381
2382 \begin_layout Plain Layout
2383 script <infile.out >infile.log
2384 \end_layout
2385
2386 \end_inset
2387
2388 .
2389  The argument may contain
2390 \begin_inset Flex CharStyle:Code
2391 status collapsed
2392
2393 \begin_layout Plain Layout
2394 $$s
2395 \end_layout
2396
2397 \end_inset
2398
2399 .
2400 \end_layout
2401
2402 \begin_layout Labeling
2403 \labelwidthstring 00.00.0000
2404 \begin_inset Flex CharStyle:Code
2405 status collapsed
2406
2407 \begin_layout Plain Layout
2408 resultdir
2409 \end_layout
2410
2411 \end_inset
2412
2413  The name of the directory in which the converter will dump the generated
2414  files.
2415  LyX will not create this directory, and it does not copy anything into
2416  it, though it will copy this directory to the destination.
2417  The argument may contain
2418 \begin_inset Flex CharStyle:Code
2419 status collapsed
2420
2421 \begin_layout Plain Layout
2422 $$b
2423 \end_layout
2424
2425 \end_inset
2426
2427 , which will be replaced by the base name of the input and output files,
2428  respectively, when the directory is copied.
2429 \begin_inset Newline newline
2430 \end_inset
2431
2432 Note that resultdir and usetempdir make no sense together.
2433  The latter will be ignored if the former is given.
2434 \end_layout
2435
2436 \begin_layout Labeling
2437 \labelwidthstring 00.00.0000
2438 \begin_inset Flex CharStyle:Code
2439 status collapsed
2440
2441 \begin_layout Plain Layout
2442 resultfile
2443 \end_layout
2444
2445 \end_inset
2446
2447  Determines the output file name and may, contain
2448 \begin_inset Flex CharStyle:Code
2449 status collapsed
2450
2451 \begin_layout Plain Layout
2452 $$b
2453 \end_layout
2454
2455 \end_inset
2456
2457 .
2458  Sensible only with resultdir and optional even then; if not given, it defaults
2459  to `index'.
2460 \end_layout
2461
2462 \begin_layout Standard
2463 None of these last three are presently used in any of the converters that
2464  are installed with LyX.
2465
2466 \end_layout
2467
2468 \begin_layout Standard
2469 You do not have to define converters between all the formats between which
2470  you want to convert.
2471  For example, you will note that there is no `LyX to PostScript' converter,
2472  but LyX will export PostScript.
2473  It does so by first creating a LaTeX file (no converter needs to be defined
2474  for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2475  and finally converting the resulting DVI file to PostScript.
2476  LyX finds such `chains' of converters automatically, and it will always
2477  choose the shortest possible chain.
2478  You can, though, still define multiple conversion methods between file
2479  formats.
2480  For example, the standard LyX configuration provides three ways to convert
2481  LaTeX to PDF: Directly, using
2482 \begin_inset Flex CharStyle:MenuItem
2483 status collapsed
2484
2485 \begin_layout Plain Layout
2486 pdflatex
2487 \end_layout
2488
2489 \end_inset
2490
2491 ; via (DVI and) PostScript, using
2492 \begin_inset Flex CharStyle:MenuItem
2493 status collapsed
2494
2495 \begin_layout Plain Layout
2496 ps2pdf
2497 \end_layout
2498
2499 \end_inset
2500
2501 ; or via DVI, using
2502 \begin_inset Flex CharStyle:MenuItem
2503 status collapsed
2504
2505 \begin_layout Plain Layout
2506 dvipdfm
2507 \end_layout
2508
2509 \end_inset
2510
2511 .
2512  To define such alternate chains, you must define multiple target `file
2513  formats', as described in section
2514 \begin_inset CommandInset ref
2515 LatexCommand ref
2516 reference "sub:Formats"
2517
2518 \end_inset
2519
2520 .
2521  For example, in the standard configuration, the formats named
2522 \begin_inset Flex CharStyle:MenuItem
2523 status collapsed
2524
2525 \begin_layout Plain Layout
2526 pdf
2527 \end_layout
2528
2529 \end_inset
2530
2531 ,
2532 \begin_inset Flex CharStyle:MenuItem
2533 status collapsed
2534
2535 \begin_layout Plain Layout
2536 pdf2
2537 \end_layout
2538
2539 \end_inset
2540
2541 , and
2542 \begin_inset Flex CharStyle:MenuItem
2543 status collapsed
2544
2545 \begin_layout Plain Layout
2546 pdf3
2547 \end_layout
2548
2549 \end_inset
2550
2551  are defined, all of which share the extension
2552 \begin_inset Flex CharStyle:MenuItem
2553 status collapsed
2554
2555 \begin_layout Plain Layout
2556 .pdf
2557 \end_layout
2558
2559 \end_inset
2560
2561 , and which correspond to the conversion methods just mentioned.
2562 \end_layout
2563
2564 \begin_layout Chapter
2565 Internationalizing LyX
2566 \begin_inset CommandInset label
2567 LatexCommand label
2568 name "chap:i18n"
2569
2570 \end_inset
2571
2572
2573 \end_layout
2574
2575 \begin_layout Standard
2576 LyX supports using a translated interface.
2577  Last time we checked, LyX provided text in thirty languages.
2578  The language of choice is called your
2579 \emph on
2580 locale
2581 \emph default
2582 .
2583  (For further reading on locale settings, see also the documentation for
2584  locale that comes with your operating system.
2585  For Linux, the manual page for
2586 \begin_inset Flex CharStyle:Code
2587 status collapsed
2588
2589 \begin_layout Plain Layout
2590 locale(5)
2591 \end_layout
2592
2593 \end_inset
2594
2595  could be a good place to start).
2596 \end_layout
2597
2598 \begin_layout Standard
2599 Notice that these translations will work, but do contain a few flaws.
2600  In particular, all dialogs have been designed with the English text in
2601  mind, which means that some of the translated text will be too large to
2602  fit within the space allocated.
2603  This is only a display problem and will not cause any harm.
2604  Also, you will find that some of the translations do not define shortcut
2605  keys for everything.
2606  Sometimes, there are simply not enough free letters to do it.
2607  Other times, the translator just hasn't got around to doing it yet.
2608  Our localization team, which you may wish to join,
2609 \begin_inset Foot
2610 status collapsed
2611
2612 \begin_layout Plain Layout
2613 If you are a fluent speaker of a language other than English, joining these
2614  teams is a great way to give back to the LyX community!
2615 \end_layout
2616
2617 \end_inset
2618
2619  will of course try to fix these shortcomings in future versions of LyX.
2620 \end_layout
2621
2622 \begin_layout Section
2623 Translating LyX
2624 \end_layout
2625
2626 \begin_layout Subsection
2627 Translating the graphical user interface (text messages).
2628 \end_layout
2629
2630 \begin_layout Standard
2631 LyX uses the GNU
2632 \begin_inset Flex CharStyle:Code
2633 status collapsed
2634
2635 \begin_layout Plain Layout
2636 gettext
2637 \end_layout
2638
2639 \end_inset
2640
2641  library to handle the internationalization of the interface.
2642  To have LyX speak your favorite language in all menus and dialogs, you
2643  need a
2644 \begin_inset Flex CharStyle:Code
2645 status collapsed
2646
2647 \begin_layout Plain Layout
2648 po
2649 \end_layout
2650
2651 \end_inset
2652
2653 -file for that language.
2654  When this is available, you'll have to generate a
2655 \begin_inset Flex CharStyle:Code
2656 status collapsed
2657
2658 \begin_layout Plain Layout
2659 mo
2660 \end_layout
2661
2662 \end_inset
2663
2664 -file from it and install the
2665 \begin_inset Flex CharStyle:Code
2666 status collapsed
2667
2668 \begin_layout Plain Layout
2669 mo
2670 \end_layout
2671
2672 \end_inset
2673
2674 -file.
2675  The process of doing all of this is explained in the documentation for
2676  GNU
2677 \begin_inset Flex CharStyle:Code
2678 status collapsed
2679
2680 \begin_layout Plain Layout
2681 gettext
2682 \end_layout
2683
2684 \end_inset
2685
2686 .
2687  It is possible to do this just for yourself, but if you're going to do
2688  it, you might as well share the results of your labors with the rest of
2689  the LyX community.
2690  Send a message to the LyX developers' list for more information about how
2691  to proceed.
2692 \end_layout
2693
2694 \begin_layout Standard
2695 In short, this is what you should do (xx denotes the language code):
2696 \end_layout
2697
2698 \begin_layout Itemize
2699 Check out the LyX source code.
2700  (See the
2701 \begin_inset CommandInset href
2702 LatexCommand href
2703 name "information on the web"
2704 target "http://www.lyx.org/devel/cvs.php"
2705
2706 \end_inset
2707
2708 .)
2709 \end_layout
2710
2711 \begin_layout Itemize
2712 Copy the file
2713 \begin_inset Flex CharStyle:Code
2714 status collapsed
2715
2716 \begin_layout Plain Layout
2717 lyx.pot
2718 \end_layout
2719
2720 \end_inset
2721
2722  to the folder of the
2723 \begin_inset Flex CharStyle:Code
2724 status collapsed
2725
2726 \begin_layout Plain Layout
2727 **.po
2728 \end_layout
2729
2730 \end_inset
2731
2732  files.
2733  Then rename it to
2734 \begin_inset Flex CharStyle:Code
2735 status collapsed
2736
2737 \begin_layout Plain Layout
2738 xx.po
2739 \end_layout
2740
2741 \end_inset
2742
2743 .
2744  (If
2745 \begin_inset Flex CharStyle:Code
2746 status collapsed
2747
2748 \begin_layout Plain Layout
2749 lyx.pot
2750 \end_layout
2751
2752 \end_inset
2753
2754  doesn't exist anywhere, it can be remade with the console command
2755 \begin_inset Flex CharStyle:Code
2756 status collapsed
2757
2758 \begin_layout Plain Layout
2759 make lyx.pot
2760 \end_layout
2761
2762 \end_inset
2763
2764  in that directory, or you can use an existing po-file for some other language
2765  as a template).
2766 \end_layout
2767
2768 \begin_layout Itemize
2769 Edit
2770 \begin_inset Flex CharStyle:Code
2771 status collapsed
2772
2773 \begin_layout Plain Layout
2774 xx.po
2775 \end_layout
2776
2777 \end_inset
2778
2779 .
2780 \begin_inset Foot
2781 status collapsed
2782
2783 \begin_layout Plain Layout
2784 This is just a text file, so it can be edited in any text editor.
2785  But there are also specialized programs that support such editing, such
2786  as
2787 \family typewriter
2788 Poedit
2789 \family default
2790  (for all platforms) or
2791 \family typewriter
2792 KBabel
2793 \family default
2794  (for KDE).
2795
2796 \family typewriter
2797 Emacs
2798 \family default
2799  contains a `mode' for editing
2800 \begin_inset Flex CharStyle:Code
2801 status collapsed
2802
2803 \begin_layout Plain Layout
2804 po
2805 \end_layout
2806
2807 \end_inset
2808
2809  files, as well.
2810 \end_layout
2811
2812 \end_inset
2813
2814  For some menu- and widget-labels, there are also shortcut keys that should
2815  be translated.
2816  Those keys are marked after a `|', and should be translated according to
2817  the words and phrases of the language.
2818  You should also fill also out the information at the beginning of the new
2819
2820 \begin_inset Flex CharStyle:Code
2821 status collapsed
2822
2823 \begin_layout Plain Layout
2824 po
2825 \end_layout
2826
2827 \end_inset
2828
2829 -file with your email-address, etc., so people know where to reach you with
2830  suggestions and entertaining flames.
2831 \end_layout
2832
2833 \begin_layout Standard
2834 If you are just doing this on your own, then:
2835 \end_layout
2836
2837 \begin_layout Itemize
2838 Generate
2839 \begin_inset Flex CharStyle:Code
2840 status collapsed
2841
2842 \begin_layout Plain Layout
2843 xx.mo
2844 \end_layout
2845
2846 \end_inset
2847
2848 .
2849  This can be done with
2850 \begin_inset Flex CharStyle:Code
2851 status collapsed
2852
2853 \begin_layout Plain Layout
2854 msgfmt -o xx.mo < xx.po
2855 \end_layout
2856
2857 \end_inset
2858
2859 .
2860 \end_layout
2861
2862 \begin_layout Itemize
2863 Copy the
2864 \begin_inset Flex CharStyle:Code
2865 status collapsed
2866
2867 \begin_layout Plain Layout
2868 mo
2869 \end_layout
2870
2871 \end_inset
2872
2873 -file to your locale-tree, at the correct directory for application messages
2874  for the language
2875 \series bold
2876
2877 \series default
2878 xx, and under the name
2879 \begin_inset Flex CharStyle:Code
2880 status collapsed
2881
2882 \begin_layout Plain Layout
2883 lyx.mo
2884 \end_layout
2885
2886 \end_inset
2887
2888  (e.
2889 \begin_inset space \thinspace{}
2890 \end_inset
2891
2892 g.
2893 \begin_inset space \space{}
2894 \end_inset
2895
2896
2897 \begin_inset Flex CharStyle:Code
2898 status collapsed
2899
2900 \begin_layout Plain Layout
2901 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2902 \end_layout
2903
2904 \end_inset
2905
2906
2907 \series bold
2908 .
2909 \end_layout
2910
2911 \begin_layout Standard
2912 As said, however, it would be best if the new
2913 \begin_inset Flex CharStyle:Code
2914 status collapsed
2915
2916 \begin_layout Plain Layout
2917 po
2918 \end_layout
2919
2920 \end_inset
2921
2922 -file could be added to the LyX distribution, so others can use it.
2923  Adding it involves making additional changes to LyX.
2924  So send an email to the developers' mailing list if you're interested in
2925  doing that.
2926 \end_layout
2927
2928 \begin_layout Subsubsection
2929 Ambiguous messages
2930 \end_layout
2931
2932 \begin_layout Standard
2933 Sometimes it turns out that one English message needs to be translated into
2934  different messages in the target language.
2935  One example is the message
2936 \begin_inset Flex CharStyle:Code
2937 status collapsed
2938
2939 \begin_layout Plain Layout
2940 To
2941 \end_layout
2942
2943 \end_inset
2944
2945  which has the German translation
2946 \lang german
2947 Nach
2948 \lang english
2949  or
2950 \lang german
2951 Bis
2952 \lang english
2953 , depending upon exactly what the English
2954 \begin_inset Quotes eld
2955 \end_inset
2956
2957 to
2958 \begin_inset Quotes erd
2959 \end_inset
2960
2961  means.
2962  GNU
2963 \begin_inset Flex CharStyle:Code
2964 status collapsed
2965
2966 \begin_layout Plain Layout
2967 gettext
2968 \end_layout
2969
2970 \end_inset
2971
2972  does not handle such ambiguous translations.
2973  Therefore you have to add some context information to the message: Instead
2974  of
2975 \begin_inset Flex CharStyle:Code
2976 status collapsed
2977
2978 \begin_layout Plain Layout
2979 To
2980 \end_layout
2981
2982 \end_inset
2983
2984  it becomes
2985 \begin_inset Flex CharStyle:Code
2986 status collapsed
2987
2988 \begin_layout Plain Layout
2989 To[[as in 'From format x to format y']]
2990 \end_layout
2991
2992 \end_inset
2993
2994  and
2995 \begin_inset Flex CharStyle:Code
2996 status collapsed
2997
2998 \begin_layout Plain Layout
2999 To[[as in 'From page x to page y']].
3000 \end_layout
3001
3002 \end_inset
3003
3004  Now the two occurrences of
3005 \begin_inset Flex CharStyle:Code
3006 status collapsed
3007
3008 \begin_layout Plain Layout
3009 To
3010 \end_layout
3011
3012 \end_inset
3013
3014  are different for
3015 \begin_inset Flex CharStyle:Code
3016 status collapsed
3017
3018 \begin_layout Plain Layout
3019 gettext
3020 \end_layout
3021
3022 \end_inset
3023
3024  and can be translated correctly to
3025 \lang german
3026 Nach
3027 \lang english
3028  and
3029 \lang german
3030 Bis
3031 \lang english
3032 , respectively.
3033 \end_layout
3034
3035 \begin_layout Standard
3036 Of course the context information needs to be stripped off the original
3037  message when no translation is used.
3038  Therefore you have to put it in double square brackets at the end of the
3039  message (see the example above).
3040  The translation mechanism of LyX ensures that everything in double square
3041  brackets at the end of messages is removed before displaying the message.
3042 \end_layout
3043
3044 \begin_layout Subsection
3045 Translating the documentation.
3046 \end_layout
3047
3048 \begin_layout Standard
3049 The online documentation (in the
3050 \begin_inset Flex CharStyle:MenuItem
3051 status collapsed
3052
3053 \begin_layout Plain Layout
3054 Help
3055 \end_layout
3056
3057 \end_inset
3058
3059 -menu) can (and should!) be translated.
3060  If there are translated versions of the documentation available
3061 \begin_inset Foot
3062 status collapsed
3063
3064 \begin_layout Plain Layout
3065 As of March 2008, at least some of the documents have been translated into
3066  fourteen languages, with the Tutorial available in a few more.
3067 \end_layout
3068
3069 \end_inset
3070
3071  and the locale is set accordingly, these will be used automagically by
3072  LyX.
3073  LyX looks for translated versions as
3074 \begin_inset Flex CharStyle:Code
3075 status collapsed
3076
3077 \begin_layout Plain Layout
3078 LyXDir/doc/xx/DocName.lyx
3079 \end_layout
3080
3081 \end_inset
3082
3083 , where
3084 \begin_inset Flex CharStyle:Code
3085 status collapsed
3086
3087 \begin_layout Plain Layout
3088 xx
3089 \end_layout
3090
3091 \end_inset
3092
3093  is the code for the language currently in use.
3094  If there are no translated documents, the default English versions will
3095  be displayed.
3096  Note that the translated versions must have the same filenames (
3097 \begin_inset Flex CharStyle:Code
3098 status collapsed
3099
3100 \begin_layout Plain Layout
3101 DocName
3102 \end_layout
3103
3104 \end_inset
3105
3106  above) as the original.
3107  If you feel up to translating the documentation (an excellent way to proof-read
3108  the original documentation by the way!), there are a few things you should
3109  do right away:
3110 \end_layout
3111
3112 \begin_layout Itemize
3113 Read
3114 \begin_inset Flex CharStyle:Code
3115 status collapsed
3116
3117 \begin_layout Plain Layout
3118 DocStyle.lyx
3119 \end_layout
3120
3121 \end_inset
3122
3123 , the guide to writing LyX documentation.
3124  Pay special attention to the translator's section.
3125 \end_layout
3126
3127 \begin_layout Itemize
3128 Check out the documentation translation web page at
3129 \begin_inset CommandInset href
3130 LatexCommand href
3131 name "http://www.lyx.org/Translation"
3132 target "http://www.lyx.org/Translation"
3133
3134 \end_inset
3135
3136 .
3137  That way, you can find out which (if any) documents have already been translate
3138 d into your language.
3139  You can also find out who (if anyone) is organizing the effort to translate
3140  the documentation into your language.
3141  If no one is organizing the effort, please let us know that you're interested.
3142 \end_layout
3143
3144 \begin_layout Standard
3145 Once you get to actually translating, here's a few hints for you that may
3146  save you trouble:
3147 \end_layout
3148
3149 \begin_layout Itemize
3150 Join the documentation team! There is information on how to do that in
3151 \begin_inset Flex CharStyle:Code
3152 status collapsed
3153
3154 \begin_layout Plain Layout
3155 Intro.lyx
3156 \end_layout
3157
3158 \end_inset
3159
3160  (
3161 \begin_inset Flex CharStyle:MenuItem
3162 status collapsed
3163
3164 \begin_layout Plain Layout
3165 Help\SpecialChar \menuseparator
3166
3167 \bar under
3168 I
3169 \bar default
3170 ntroduction
3171 \end_layout
3172
3173 \end_inset
3174
3175 ), which by the way is the first document you should translate.
3176 \end_layout
3177
3178 \begin_layout Itemize
3179 Learn the typographic conventions for the language you are translating to.
3180  Typography is an ancient art and over the centuries, a great variety of
3181  conventions have developed throughout different parts of the world.
3182  Also study the professional terminology amongst typographers in your country.
3183  Inventing your own terminology will only confuse the users.
3184
3185 \emph on
3186 (Warning! Typography is addictive!)
3187 \end_layout
3188
3189 \begin_layout Itemize
3190 Make a copy of the document.
3191  This will be your working copy.
3192  You can use this as your personal translated help-file by placing it in
3193  your
3194 \begin_inset Flex CharStyle:Code
3195 status collapsed
3196
3197 \begin_layout Plain Layout
3198 UserDir/doc/xx/
3199 \end_layout
3200
3201 \end_inset
3202
3203  directory.
3204 \end_layout
3205
3206 \begin_layout Itemize
3207 Sometimes the original document (from the LyX-team) will be updated.
3208  Use the source viewer at
3209 \begin_inset CommandInset href
3210 LatexCommand href
3211 name "http://www.lyx.org/trac/timeline"
3212 target "http://www.lyx.org/trac/timeline"
3213
3214 \end_inset
3215
3216  to see what has been changed.
3217  That way you can easily see which parts of the translated document need
3218  to be updated.
3219 \end_layout
3220
3221 \begin_layout Standard
3222 If you ever find an error in the original document, fix it and notify the
3223  rest of the documentation team of the changes! (You didn't forget to join
3224  the documentation team, did you?)
3225 \end_layout
3226
3227 \begin_layout Standard
3228 \begin_inset Branch OutDated
3229 status collapsed
3230
3231 \begin_layout Section
3232 International Keyboard Support
3233 \end_layout
3234
3235 \begin_layout Standard
3236
3237 \emph on
3238 [Editor's Note: The following section is by
3239 \emph default
3240
3241 \shape smallcaps
3242 \emph on
3243 Ivan Schreter
3244 \shape default
3245 .
3246  It needs to be fixed to conform to the new Documentation Style sheet and
3247  to make use of the new v1.0 features.
3248  The whole thing also needs to be merged with the section following it.-jw
3249  It may also be badly out of date.-rh (2008)]
3250 \end_layout
3251
3252 \begin_layout Subsection
3253 Defining Own Keymaps: Keymap File Format
3254 \end_layout
3255
3256 \begin_layout Standard
3257 Let's look at a keyboard definition file a little closer.
3258  It is a plain text file defining
3259 \end_layout
3260
3261 \begin_layout Itemize
3262 key-to-key or key-to-string translations
3263 \end_layout
3264
3265 \begin_layout Itemize
3266 dead keys
3267 \end_layout
3268
3269 \begin_layout Itemize
3270 dead keys exceptions
3271 \end_layout
3272
3273 \begin_layout Standard
3274 To define key-to-key or key-to-string translation, use this command:
3275 \end_layout
3276
3277 \begin_layout Quotation
3278 \begin_inset Flex CharStyle:Code
3279 status collapsed
3280
3281 \begin_layout Plain Layout
3282
3283 \backslash
3284 kmap
3285 \end_layout
3286
3287 \end_inset
3288
3289
3290 \begin_inset Flex CharStyle:Code
3291 status collapsed
3292
3293 \begin_layout Plain Layout
3294 key
3295 \end_layout
3296
3297 \end_inset
3298
3299  outstring
3300 \end_layout
3301
3302 \begin_layout Standard
3303 where
3304 \begin_inset Flex CharStyle:Code
3305 status collapsed
3306
3307 \begin_layout Plain Layout
3308 key
3309 \end_layout
3310
3311 \end_inset
3312
3313  is the key to be translated and
3314 \begin_inset Flex CharStyle:Code
3315 status collapsed
3316
3317 \begin_layout Plain Layout
3318 outstring
3319 \end_layout
3320
3321 \end_inset
3322
3323  is the string to be inserted into the document.
3324  To define dead keys, use:
3325 \end_layout
3326
3327 \begin_layout Quotation
3328 \begin_inset Flex CharStyle:Code
3329 status collapsed
3330
3331 \begin_layout Plain Layout
3332
3333 \backslash
3334 kmod
3335 \end_layout
3336
3337 \end_inset
3338
3339
3340 \begin_inset Flex CharStyle:Code
3341 status collapsed
3342
3343 \begin_layout Plain Layout
3344 key
3345 \end_layout
3346
3347 \end_inset
3348
3349  deadkey
3350 \end_layout
3351
3352 \begin_layout Standard
3353 where
3354 \begin_inset Flex CharStyle:Code
3355 status collapsed
3356
3357 \begin_layout Plain Layout
3358 key
3359 \end_layout
3360
3361 \end_inset
3362
3363  is a keyboard key and
3364 \begin_inset Flex CharStyle:Code
3365 status collapsed
3366
3367 \begin_layout Plain Layout
3368 deadkey
3369 \end_layout
3370
3371 \end_inset
3372
3373  is dead key name.
3374  The following dead keys are supported (shortcut name is in parentheses):
3375 \end_layout
3376
3377 \begin_layout Quotation
3378
3379 \emph on
3380 Name
3381 \begin_inset space \hfill{}
3382 \end_inset
3383
3384 Example
3385 \end_layout
3386
3387 \begin_layout Quotation
3388 acute (acu)
3389 \begin_inset space \hfill{}
3390 \end_inset
3391
3392 áéíóú
3393 \end_layout
3394
3395 \begin_layout Quotation
3396 grave (gra)
3397 \begin_inset space \hfill{}
3398 \end_inset
3399
3400 àèìòù
3401 \end_layout
3402
3403 \begin_layout Quotation
3404 macron (mac)
3405 \begin_inset space \hfill{}
3406 \end_inset
3407
3408  ō
3409 \end_layout
3410
3411 \begin_layout Quotation
3412 tilde (til)
3413 \begin_inset space \hfill{}
3414 \end_inset
3415
3416 ñÑ
3417 \end_layout
3418
3419 \begin_layout Quotation
3420 underbar (underb)
3421 \begin_inset space \hfill{}
3422 \end_inset
3423
3424
3425 \begin_inset ERT
3426 status open
3427
3428 \begin_layout Plain Layout
3429
3430
3431 \backslash
3432 b o
3433 \end_layout
3434
3435 \end_inset
3436
3437
3438 \end_layout
3439
3440 \begin_layout Quotation
3441 cedilla (ced)
3442 \begin_inset space \hfill{}
3443 \end_inset
3444
3445 çÇ
3446 \end_layout
3447
3448 \begin_layout Quotation
3449 underdot (underd)
3450 \begin_inset space \hfill{}
3451 \end_inset
3452
3453
3454 \begin_inset ERT
3455 status open
3456
3457 \begin_layout Plain Layout
3458
3459
3460 \backslash
3461 d o
3462 \end_layout
3463
3464 \end_inset
3465
3466
3467 \end_layout
3468
3469 \begin_layout Quotation
3470 circumflex (circu)
3471 \begin_inset space \hfill{}
3472 \end_inset
3473
3474 âêîôû
3475 \end_layout
3476
3477 \begin_layout Quotation
3478 circle (circl)
3479 \begin_inset space \hfill{}
3480 \end_inset
3481
3482 ÅůŮ
3483 \end_layout
3484
3485 \begin_layout Quotation
3486 tie (tie)
3487 \begin_inset space \hfill{}
3488 \end_inset
3489
3490
3491 \begin_inset ERT
3492 status open
3493
3494 \begin_layout Plain Layout
3495
3496
3497 \backslash
3498 t o
3499 \end_layout
3500
3501 \end_inset
3502
3503
3504 \end_layout
3505
3506 \begin_layout Quotation
3507 breve (bre)
3508 \begin_inset space \hfill{}
3509 \end_inset
3510
3511 ă
3512 \begin_inset ERT
3513 status open
3514
3515 \begin_layout Plain Layout
3516
3517
3518 \backslash
3519 u o
3520 \end_layout
3521
3522 \end_inset
3523
3524
3525 \end_layout
3526
3527 \begin_layout Quotation
3528 caron (car)
3529 \begin_inset space \hfill{}
3530 \end_inset
3531
3532 čšž
3533 \end_layout
3534
3535 \begin_layout Quotation
3536 hungarian umlaut (hug)
3537 \begin_inset space \hfill{}
3538 \end_inset
3539
3540 őű
3541 \end_layout
3542
3543 \begin_layout Quotation
3544 umlaut (uml)
3545 \begin_inset space \hfill{}
3546 \end_inset
3547
3548 äöü
3549 \end_layout
3550
3551 \begin_layout Quotation
3552 dot (dot)
3553 \begin_inset space \hfill{}
3554 \end_inset
3555
3556 ż
3557 \begin_inset ERT
3558 status open
3559
3560 \begin_layout Plain Layout
3561
3562
3563 \backslash
3564 .s
3565 \end_layout
3566
3567 \end_inset
3568
3569
3570 \end_layout
3571
3572 \begin_layout Standard
3573 Since in many international keyboards there are exceptions to what some
3574  dead keys should do, you can define them using
3575 \end_layout
3576
3577 \begin_layout Quotation
3578 \begin_inset Flex CharStyle:Code
3579 status collapsed
3580
3581 \begin_layout Plain Layout
3582
3583 \backslash
3584 kxmod
3585 \end_layout
3586
3587 \end_inset
3588
3589  deadkey key outstring
3590 \end_layout
3591
3592 \begin_layout Standard
3593 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3594 , so you put in
3595 \end_layout
3596
3597 \begin_layout Quotation
3598 \begin_inset Flex CharStyle:Code
3599 status collapsed
3600
3601 \begin_layout Plain Layout
3602
3603 \backslash
3604 kxmod
3605 \end_layout
3606
3607 \end_inset
3608
3609  caron o "
3610 \backslash
3611 ^o"
3612 \end_layout
3613
3614 \begin_layout Standard
3615 to make it work correctly.
3616  Also, you have to define as exceptions dead keys over i and j, to remove
3617  the dot from them before inserting an accent mark.
3618  I will change this when the time comes, but so far I haven't had time.
3619 \end_layout
3620
3621 \begin_layout Standard
3622 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3623  double backslash.
3624  Also, quotes and
3625 \begin_inset Flex CharStyle:Code
3626 status collapsed
3627
3628 \begin_layout Plain Layout
3629 #
3630 \end_layout
3631
3632 \end_inset
3633
3634  have different meaning.
3635
3636 \begin_inset Flex CharStyle:Code
3637 status collapsed
3638
3639 \begin_layout Plain Layout
3640 #
3641 \end_layout
3642
3643 \end_inset
3644
3645  marks comments, quotes start and end LaTeX-style commands.
3646  To enter quote, you'll need to use
3647 \begin_inset Flex CharStyle:Code
3648 status collapsed
3649
3650 \begin_layout Plain Layout
3651
3652 \backslash
3653 "
3654 \end_layout
3655
3656 \end_inset
3657
3658 , to enter
3659 \begin_inset Flex CharStyle:Code
3660 status collapsed
3661
3662 \begin_layout Plain Layout
3663 #
3664 \end_layout
3665
3666 \end_inset
3667
3668 , use
3669 \begin_inset Flex CharStyle:Code
3670 status collapsed
3671
3672 \begin_layout Plain Layout
3673
3674 \backslash
3675 #
3676 \end_layout
3677
3678 \end_inset
3679
3680 .
3681 \end_layout
3682
3683 \begin_layout Standard
3684 If you make a keyboard description file that works for your language, please
3685  mail it to me, so I can include it in the next keymap distribution.
3686 \end_layout
3687
3688 \begin_layout Standard
3689 More keywords will be supported in keymap configuration file in future,
3690  like
3691 \end_layout
3692
3693 \begin_layout Itemize
3694 \begin_inset Flex CharStyle:Code
3695 status collapsed
3696
3697 \begin_layout Plain Layout
3698
3699 \backslash
3700 kinclude filename
3701 \end_layout
3702
3703 \end_inset
3704
3705
3706 \emph on
3707
3708 \begin_inset space \hfill{}
3709 \end_inset
3710
3711
3712 \begin_inset Flex CharStyle:Code
3713 status collapsed
3714
3715 \begin_layout Plain Layout
3716 include
3717 \end_layout
3718
3719 \end_inset
3720
3721  another file
3722 \end_layout
3723
3724 \begin_layout Itemize
3725 \begin_inset Flex CharStyle:Code
3726 status collapsed
3727
3728 \begin_layout Plain Layout
3729
3730 \backslash
3731 kprog program
3732 \end_layout
3733
3734 \end_inset
3735
3736
3737 \emph on
3738
3739 \begin_inset space \hfill{}
3740 \end_inset
3741
3742
3743 \begin_inset Flex CharStyle:Code
3744 status collapsed
3745
3746 \begin_layout Plain Layout
3747 define
3748 \end_layout
3749
3750 \end_inset
3751
3752  an external keymap translation program
3753 \end_layout
3754
3755 \begin_layout Standard
3756 Also, it should look into
3757 \begin_inset Flex CharStyle:Code
3758 status collapsed
3759
3760 \begin_layout Plain Layout
3761 lyxrc
3762 \end_layout
3763
3764 \end_inset
3765
3766  file for defaults, too (for example, a
3767 \begin_inset Flex CharStyle:Code
3768 status collapsed
3769
3770 \begin_layout Plain Layout
3771
3772 \backslash
3773 kinclude
3774 \end_layout
3775
3776 \end_inset
3777
3778  option to include default keyboard).
3779 \end_layout
3780
3781 \end_inset
3782
3783
3784 \end_layout
3785
3786 \begin_layout Section
3787 \begin_inset CommandInset label
3788 LatexCommand label
3789 name "sec:keymap"
3790
3791 \end_inset
3792
3793 International Keymap Stuff
3794 \end_layout
3795
3796 \begin_layout Standard
3797 \begin_inset Note Note
3798 status open
3799
3800 \begin_layout Plain Layout
3801 In doing the revisions on this document in March 2008, I did not look over
3802  this stuff, as I do not understand it.
3803  It would be good if someone else could do so.
3804  (RH)
3805 \end_layout
3806
3807 \end_inset
3808
3809
3810 \end_layout
3811
3812 \begin_layout Standard
3813 The next two sections describe the
3814 \begin_inset Flex CharStyle:Code
3815 status collapsed
3816
3817 \begin_layout Plain Layout
3818
3819 \shape up
3820 .kmap
3821 \end_layout
3822
3823 \end_inset
3824
3825  and
3826 \begin_inset Flex CharStyle:Code
3827 status collapsed
3828
3829 \begin_layout Plain Layout
3830
3831 \shape up
3832 .cdef
3833 \end_layout
3834
3835 \end_inset
3836
3837  file syntax in detail.
3838  These sections should help you design your own key map if the ones provided
3839  do not meet your needs.
3840 \end_layout
3841
3842 \begin_layout Subsection
3843 The .kmap File
3844 \end_layout
3845
3846 \begin_layout Standard
3847 A
3848 \shape up
3849 .
3850 \begin_inset Flex CharStyle:Code
3851 status collapsed
3852
3853 \begin_layout Plain Layout
3854 kmap
3855 \end_layout
3856
3857 \end_inset
3858
3859  file maps keystrokes to characters or strings.
3860  As the name suggests, it sets a keyboard mapping.
3861  The
3862 \begin_inset Flex CharStyle:Code
3863 status collapsed
3864
3865 \begin_layout Plain Layout
3866 .kmap
3867 \end_layout
3868
3869 \end_inset
3870
3871
3872 \shape default
3873  file keywords
3874 \shape up
3875
3876 \begin_inset Flex CharStyle:Code
3877 status collapsed
3878
3879 \begin_layout Plain Layout
3880
3881 \shape up
3882 kmap
3883 \end_layout
3884
3885 \end_inset
3886
3887
3888 \shape default
3889 ,
3890 \shape up
3891
3892 \shape default
3893
3894 \begin_inset Flex CharStyle:Code
3895 status collapsed
3896
3897 \begin_layout Plain Layout
3898
3899 \shape up
3900 kmod
3901 \end_layout
3902
3903 \end_inset
3904
3905 ,
3906 \shape up
3907
3908 \shape default
3909
3910 \begin_inset Flex CharStyle:Code
3911 status collapsed
3912
3913 \begin_layout Plain Layout
3914
3915 \shape up
3916 ksmod
3917 \end_layout
3918
3919 \end_inset
3920
3921 , and
3922 \begin_inset Flex CharStyle:Code
3923 status collapsed
3924
3925 \begin_layout Plain Layout
3926
3927 \shape up
3928 kcomb
3929 \end_layout
3930
3931 \end_inset
3932
3933  are described in this section.
3934 \end_layout
3935
3936 \begin_layout Labeling
3937 \labelwidthstring 00.00.0000
3938 \begin_inset Flex CharStyle:Code
3939 status collapsed
3940
3941 \begin_layout Plain Layout
3942
3943 \shape up
3944 kmap
3945 \end_layout
3946
3947 \end_inset
3948
3949  Map a character to a string
3950 \end_layout
3951
3952 \begin_layout LyX-Code
3953
3954 \backslash
3955 kmap
3956 \family roman
3957 \emph on
3958 char
3959 \family default
3960 \emph default
3961
3962 \family roman
3963 \emph on
3964 string
3965 \end_layout
3966
3967 \begin_layout Standard
3968 This will ma
3969 \family roman
3970 p
3971 \family default
3972
3973 \family roman
3974 \emph on
3975 char
3976 \family default
3977 \emph default
3978
3979 \family roman
3980 to
3981 \family default
3982
3983 \family roman
3984 \emph on
3985 string
3986 \emph default
3987 .
3988  Note that in
3989 \family default
3990
3991 \family roman
3992 \emph on
3993 string
3994 \emph default
3995 ,
3996 \family default
3997
3998 \family roman
3999 \shape up
4000 the double-quote (")
4001 \family default
4002 \shape default
4003
4004 \family roman
4005 and
4006 \family default
4007
4008 \family roman
4009 \shape up
4010 the backslash (
4011 \backslash
4012 )
4013 \family default
4014 \shape default
4015
4016 \family roman
4017 must be escaped with a preceding backslash (
4018 \shape up
4019
4020 \backslash
4021
4022 \shape default
4023 )
4024 \family default
4025 .
4026 \end_layout
4027
4028 \begin_layout Standard
4029 An example of a
4030 \begin_inset Flex CharStyle:MenuItem
4031 status collapsed
4032
4033 \begin_layout Plain Layout
4034
4035 \shape up
4036 kmap
4037 \end_layout
4038
4039 \end_inset
4040
4041  statement to cause the symbol
4042 \begin_inset Flex CharStyle:MenuItem
4043 status collapsed
4044
4045 \begin_layout Plain Layout
4046
4047 \shape up
4048 /
4049 \end_layout
4050
4051 \end_inset
4052
4053  to be output for the keystroke
4054 \begin_inset Flex CharStyle:MenuItem
4055 status collapsed
4056
4057 \begin_layout Plain Layout
4058
4059 \shape up
4060 &
4061 \end_layout
4062
4063 \end_inset
4064
4065  is:
4066 \end_layout
4067
4068 \begin_layout LyX-Code
4069
4070 \backslash
4071 kmap & /
4072 \end_layout
4073
4074 \begin_layout Labeling
4075 \labelwidthstring 00.00.0000
4076 \begin_inset Flex CharStyle:Code
4077 status collapsed
4078
4079 \begin_layout Plain Layout
4080
4081 \shape up
4082 kmod
4083 \end_layout
4084
4085 \end_inset
4086
4087  Specify an accent character
4088 \end_layout
4089
4090 \begin_layout LyX-Code
4091
4092 \backslash
4093 kmod
4094 \family roman
4095 \emph on
4096 char accent allowed
4097 \end_layout
4098
4099 \begin_layout Standard
4100 This will make the cha
4101 \family roman
4102 racter
4103 \family default
4104
4105 \family roman
4106 \emph on
4107 char
4108 \family default
4109 \emph default
4110
4111 \family roman
4112 \shape up
4113 \emph on
4114 be an accent
4115 \family default
4116 \shape default
4117 \emph default
4118
4119 \family roman
4120 \shape up
4121 on the
4122 \family default
4123 \shape default
4124
4125 \family roman
4126 \shape up
4127 \emph on
4128 allowed
4129 \family default
4130 \shape default
4131 \emph default
4132
4133 \family roman
4134 \shape up
4135 cha
4136 \family default
4137 racter(s).
4138  This is the dead key
4139 \begin_inset Foot
4140 status collapsed
4141
4142 \begin_layout Plain Layout
4143 The term
4144 \family roman
4145 \emph on
4146 dead key
4147 \family default
4148 \emph default
4149  refers to a key that does not produce a character by itself, but when followed
4150  with another key, produces the desired accent character.
4151  For example, a German characte
4152 \family roman
4153 r with an umlaut like
4154 \family default
4155
4156 \family roman
4157 \emph on
4158 ä
4159 \family default
4160 \emph default
4161
4162 \family roman
4163 can be produced in this manner.
4164 \end_layout
4165
4166 \end_inset
4167
4168  mechanism.
4169
4170 \end_layout
4171
4172 \begin_layout Standard
4173 If you
4174 \family roman
4175 hit
4176 \family default
4177
4178 \family roman
4179 \emph on
4180 char
4181 \family default
4182 \emph default
4183
4184 \family roman
4185 and then another key not in
4186 \family default
4187
4188 \family roman
4189 \emph on
4190 allowed
4191 \emph default
4192 , you will get a
4193 \family default
4194
4195 \family roman
4196 \emph on
4197 char
4198 \family default
4199 \emph default
4200
4201 \family roman
4202 followed by the other, not allowed key, as output.
4203
4204 \family default
4205  Note that a
4206 \begin_inset Flex CharStyle:MenuItem
4207 status collapsed
4208
4209 \begin_layout Plain Layout
4210
4211 \shape up
4212 Backspace
4213 \end_layout
4214
4215 \end_inset
4216
4217  cancels a dead key, so if
4218 \family roman
4219 you hit
4220 \family default
4221
4222 \family roman
4223 \emph on
4224 char
4225 \family default
4226 \emph default
4227
4228 \begin_inset Flex CharStyle:MenuItem
4229 status collapsed
4230
4231 \begin_layout Plain Layout
4232
4233 \shape up
4234 \emph on
4235 Backspace
4236 \end_layout
4237
4238 \end_inset
4239
4240 , the cursor will not go one position backwards but will instead cancel
4241  the effect t
4242 \family roman
4243 hat
4244 \family default
4245
4246 \family roman
4247 \shape up
4248 \emph on
4249 char
4250 \family default
4251 \shape default
4252 \emph default
4253
4254 \family roman
4255 \shape up
4256 might have had on the next keystroke.
4257
4258 \end_layout
4259
4260 \begin_layout Standard
4261 The following example specifies that the character ' is to be an acute accent,
4262  allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4263 \end_layout
4264
4265 \begin_layout LyX-Code
4266
4267 \backslash
4268 kmod ' acute aeiouAEIOU
4269 \end_layout
4270
4271 \begin_layout Labeling
4272 \labelwidthstring 00.00.0000
4273 \begin_inset Flex CharStyle:Code
4274 status collapsed
4275
4276 \begin_layout Plain Layout
4277 ksmod
4278 \end_layout
4279
4280 \end_inset
4281
4282  Specify an exception to the accent character
4283 \end_layout
4284
4285 \begin_layout LyX-Code
4286
4287 \backslash
4288 kxmod
4289 \family roman
4290 \emph on
4291 accent char result
4292 \end_layout
4293
4294 \begin_layout Standard
4295 This defines an exce
4296 \family roman
4297 ption for
4298 \family default
4299
4300 \family roman
4301 \emph on
4302 accent
4303 \family default
4304 \emph default
4305
4306 \family roman
4307 on
4308 \family default
4309
4310 \family roman
4311 \emph on
4312 char
4313 \emph default
4314 .
4315  T
4316 \shape up
4317 he
4318 \family default
4319 \shape default
4320
4321 \family roman
4322 \shape up
4323 \emph on
4324 accent
4325 \family default
4326 \shape default
4327 \emph default
4328
4329 \family roman
4330 \shape up
4331 must
4332 \family default
4333 \shape default
4334
4335 \shape up
4336 have been assigned a keystroke with a previous
4337 \shape default
4338
4339 \begin_inset Flex CharStyle:Code
4340 status collapsed
4341
4342 \begin_layout Plain Layout
4343
4344 \shape up
4345
4346 \backslash
4347 kmo
4348 \shape default
4349 d
4350 \end_layout
4351
4352 \end_inset
4353
4354  declar
4355 \family roman
4356 ation and
4357 \family default
4358
4359 \family roman
4360 \emph on
4361 char
4362 \family default
4363 \emph default
4364
4365 \family roman
4366 must not belong in the
4367 \family default
4368
4369 \family roman
4370 \emph on
4371 allowed
4372 \family default
4373 \emph default
4374
4375 \family roman
4376 set of
4377 \family default
4378
4379 \family roman
4380 \emph on
4381 accent
4382 \emph default
4383 .
4384  When
4385 \family default
4386
4387 \family roman
4388 \shape up
4389 you enter the
4390 \family default
4391 \shape default
4392
4393 \family roman
4394 \shape up
4395 \emph on
4396 accent char
4397 \family default
4398 \shape default
4399 \emph default
4400
4401 \family roman
4402 \shape up
4403 sequence,
4404 \family default
4405 \shape default
4406
4407 \family roman
4408 \shape up
4409 \emph on
4410 result
4411 \emph default
4412  is produced.
4413  If such a declaration does not exist in
4414 \family default
4415 \shape default
4416
4417 \shape up
4418 the
4419 \shape default
4420
4421 \begin_inset Flex CharStyle:Code
4422 status collapsed
4423
4424 \begin_layout Plain Layout
4425
4426 \shape up
4427 .kmap
4428 \end_layout
4429
4430 \end_inset
4431
4432  file and yo
4433 \family roman
4434 u enter
4435 \family default
4436
4437 \family roman
4438 \emph on
4439 accent char
4440 \emph default
4441 , you get
4442 \family default
4443
4444 \family roman
4445 \emph on
4446 accent_key char
4447 \emph default
4448  where
4449 \family default
4450
4451 \family roman
4452 \emph on
4453 accent_key
4454 \emph default
4455  is the first arg
4456 \family default
4457 ument of the
4458 \begin_inset Flex CharStyle:Code
4459 status collapsed
4460
4461 \begin_layout Plain Layout
4462
4463 \shape up
4464
4465 \backslash
4466 kmod
4467 \end_layout
4468
4469 \end_inset
4470
4471  declaration.
4472
4473 \end_layout
4474
4475 \begin_layout Standard
4476 The following command produces causes äi to be produced when you enter acute-i
4477  ('i):
4478 \end_layout
4479
4480 \begin_layout LyX-Code
4481
4482 \backslash
4483 kxmod acute i "
4484 \backslash
4485
4486 \backslash
4487 '{
4488 \backslash
4489
4490 \backslash
4491 i}"
4492 \end_layout
4493
4494 \begin_layout Labeling
4495 \labelwidthstring 00.00.0000
4496 \begin_inset Flex CharStyle:Code
4497 status collapsed
4498
4499 \begin_layout Plain Layout
4500 kcomb
4501 \end_layout
4502
4503 \end_inset
4504
4505  Combine two accent characters
4506 \end_layout
4507
4508 \begin_layout LyX-Code
4509
4510 \backslash
4511 kcomb
4512 \family roman
4513 \emph on
4514 accent1 accent2 allowed
4515 \end_layout
4516
4517 \begin_layout Standard
4518 This one is getting pretty esoteric.
4519  It allows you to combine the effect
4520 \family roman
4521 of
4522 \family default
4523
4524 \family roman
4525 \emph on
4526 accent1
4527 \family default
4528 \emph default
4529
4530 \family roman
4531 and
4532 \family default
4533
4534 \family roman
4535 \emph on
4536 accent2
4537 \family default
4538 \emph default
4539
4540 \family roman
4541 (in that order!) on
4542 \family default
4543
4544 \family roman
4545 \emph on
4546 allowed
4547 \family default
4548 \emph default
4549
4550 \family roman
4551 chars.
4552  The keystrokes for
4553 \family default
4554
4555 \family roman
4556 \emph on
4557 accent1
4558 \family default
4559 \emph default
4560
4561 \family roman
4562 and
4563 \family default
4564
4565 \family roman
4566 \emph on
4567 accent2
4568 \family default
4569 \emph default
4570
4571 \family roman
4572 must have be
4573 \family default
4574 en set with a
4575 \begin_inset Flex CharStyle:Code
4576 status collapsed
4577
4578 \begin_layout Plain Layout
4579
4580 \shape up
4581
4582 \backslash
4583 kmod
4584 \end_layout
4585
4586 \end_inset
4587
4588  command at
4589 \family roman
4590 a
4591 \family default
4592
4593 \family roman
4594 \emph on
4595 previous
4596 \family default
4597 \emph default
4598
4599 \family roman
4600 point in the
4601 \family default
4602  file.
4603
4604 \end_layout
4605
4606 \begin_layout Standard
4607 Consider this example from the
4608 \begin_inset Flex CharStyle:Code
4609 status collapsed
4610
4611 \begin_layout Plain Layout
4612
4613 \shape up
4614 greek.kmap
4615 \end_layout
4616
4617 \end_inset
4618
4619  file:
4620 \end_layout
4621
4622 \begin_layout LyX-Code
4623
4624 \backslash
4625 kmod ; acute aeioyvhAEIOYVH
4626 \backslash
4627 kmod : umlaut iyIY
4628 \backslash
4629 kcomb acute umlaut iyIY
4630 \end_layout
4631
4632 \begin_layout Standard
4633 This allows you to press
4634 \begin_inset Flex CharStyle:MenuItem
4635 status collapsed
4636
4637 \begin_layout Plain Layout
4638
4639 \shape up
4640 ;:i
4641 \end_layout
4642
4643 \end_inset
4644
4645  and get the effect of
4646 \begin_inset Flex CharStyle:Code
4647 status collapsed
4648
4649 \begin_layout Plain Layout
4650
4651 \shape up
4652
4653 \backslash
4654 '{
4655 \backslash
4656 "{i}}
4657 \end_layout
4658
4659 \end_inset
4660
4661 .
4662
4663 \family roman
4664 \shape up
4665 A backspace
4666 \family default
4667 \shape default
4668  in this case cancels the last dead key, so if you press
4669 \begin_inset Flex CharStyle:MenuItem
4670 status collapsed
4671
4672 \begin_layout Plain Layout
4673
4674 \shape up
4675 ;: Backspace i
4676 \end_layout
4677
4678 \end_inset
4679
4680  you get
4681 \begin_inset Flex CharStyle:Code
4682 status collapsed
4683
4684 \begin_layout Plain Layout
4685
4686 \shape up
4687
4688 \backslash
4689 '{i}
4690 \end_layout
4691
4692 \end_inset
4693
4694 .
4695 \end_layout
4696
4697 \begin_layout Subsection
4698 The .cdef File
4699 \end_layout
4700
4701 \begin_layout Standard
4702 After the
4703 \begin_inset Flex CharStyle:Code
4704 status collapsed
4705
4706 \begin_layout Plain Layout
4707
4708 \shape up
4709 .kmap
4710 \end_layout
4711
4712 \end_inset
4713
4714  mapping is performed, a
4715 \begin_inset Flex CharStyle:Code
4716 status collapsed
4717
4718 \begin_layout Plain Layout
4719
4720 \shape up
4721 .cde
4722 \shape default
4723 f
4724 \end_layout
4725
4726 \end_inset
4727
4728  file maps the strings that the symbols generate to characters in the current
4729  font.
4730  The LyX distribution currently includes at least the
4731 \begin_inset Flex CharStyle:Code
4732 status collapsed
4733
4734 \begin_layout Plain Layout
4735
4736 \shape up
4737 iso8859-1.cdef
4738 \end_layout
4739
4740 \end_inset
4741
4742  and
4743 \begin_inset Flex CharStyle:Code
4744 status collapsed
4745
4746 \begin_layout Plain Layout
4747
4748 \shape up
4749 iso8859-2.cdef
4750 \end_layout
4751
4752 \end_inset
4753
4754  files.
4755 \end_layout
4756
4757 \begin_layout Standard
4758 In general the
4759 \begin_inset Flex CharStyle:Code
4760 status collapsed
4761
4762 \begin_layout Plain Layout
4763
4764 \shape up
4765 .cdef
4766 \end_layout
4767
4768 \end_inset
4769
4770  file is a sequence of declarations of the form
4771 \end_layout
4772
4773 \begin_layout LyX-Code
4774
4775 \family roman
4776 \emph on
4777 char_index_in_set
4778 \family default
4779 \emph default
4780
4781 \family roman
4782 \emph on
4783  string
4784 \end_layout
4785
4786 \begin_layout Standard
4787 For example, in order to map
4788 \begin_inset Flex CharStyle:MenuItem
4789 status collapsed
4790
4791 \begin_layout Plain Layout
4792
4793 \shape up
4794
4795 \backslash
4796 '{e}
4797 \end_layout
4798
4799 \end_inset
4800
4801  to the corresponding character in the iso-8859-1 set (233), the following
4802  declaration is used
4803 \end_layout
4804
4805 \begin_layout LyX-Code
4806 233 "
4807 \backslash
4808
4809 \backslash
4810 '{e}"
4811 \end_layout
4812
4813 \begin_layout Standard
4814 with
4815 \begin_inset Flex CharStyle:Code
4816 status collapsed
4817
4818 \begin_layout Plain Layout
4819
4820 \backslash
4821
4822 \end_layout
4823
4824 \end_inset
4825
4826  and
4827 \begin_inset Flex CharStyle:Code
4828 status collapsed
4829
4830 \begin_layout Plain Layout
4831 "
4832 \end_layout
4833
4834 \end_inset
4835
4836  being escap
4837 \family roman
4838 ed in
4839 \family default
4840
4841 \family roman
4842 \emph on
4843 string
4844 \emph default
4845 .
4846  Note that
4847 \family default
4848  the same character can apply to more than one string.
4849  In the
4850 \begin_inset Flex CharStyle:Code
4851 status collapsed
4852
4853 \begin_layout Plain Layout
4854 i
4855 \shape up
4856 so-8859-7.cdef
4857 \end_layout
4858
4859 \end_inset
4860
4861  file you have
4862 \end_layout
4863
4864 \begin_layout LyX-Code
4865 192 "
4866 \backslash
4867
4868 \backslash
4869 '{
4870 \backslash
4871
4872 \backslash
4873
4874 \backslash
4875 "{i}}"
4876 \begin_inset Newline newline
4877 \end_inset
4878
4879 192 "
4880 \backslash
4881
4882 \backslash
4883
4884 \backslash
4885 "{
4886 \backslash
4887
4888 \backslash
4889 '{i}}"
4890 \end_layout
4891
4892 \begin_layout Standard
4893 If LyX cannot find a mapping for the string produced by the keystroke or
4894  a deadkey sequence, it will check if it looks like an accented char and
4895  try to draw an accent over the character on screen.
4896 \end_layout
4897
4898 \begin_layout Subsection
4899 Dead Keys
4900 \end_layout
4901
4902 \begin_layout Standard
4903 There is a second way to add support for international characters through
4904  so-called dead-keys.
4905  A dead-key works in combination with a letter to produce an accented character.
4906  Here, we'll explain how to create a really simple dead-key to illustrate
4907  how they work.
4908 \end_layout
4909
4910 \begin_layout Standard
4911 Suppose you happen to need the circumflex character,
4912 \begin_inset Quotes eld
4913 \end_inset
4914
4915  ̂
4916 \begin_inset Quotes erd
4917 \end_inset
4918
4919 .
4920  You could bind the
4921 \begin_inset Flex CharStyle:MenuItem
4922 status collapsed
4923
4924 \begin_layout Plain Layout
4925 ^
4926 \end_layout
4927
4928 \end_inset
4929
4930 -key [a.k.a.
4931 \begin_inset space ~
4932 \end_inset
4933
4934
4935 \begin_inset Flex CharStyle:MenuItem
4936 status collapsed
4937
4938 \begin_layout Plain Layout
4939 Shift-6
4940 \end_layout
4941
4942 \end_inset
4943
4944 ] to the LyX command
4945 \begin_inset Flex CharStyle:Code
4946 status collapsed
4947
4948 \begin_layout Plain Layout
4949 accent-circumflex
4950 \end_layout
4951
4952 \end_inset
4953
4954  in your
4955 \begin_inset Flex CharStyle:Code
4956 status collapsed
4957
4958 \begin_layout Plain Layout
4959 lyxrc
4960 \end_layout
4961
4962 \end_inset
4963
4964  file.
4965  Now, whenever you type the
4966 \begin_inset Flex CharStyle:MenuItem
4967 status collapsed
4968
4969 \begin_layout Plain Layout
4970 ^
4971 \end_layout
4972
4973 \end_inset
4974
4975 -key followed by a letter, that letter will have a circumflex accent on
4976  it.
4977  For example, the sequence
4978 \begin_inset Quotes eld
4979 \end_inset
4980
4981
4982 \begin_inset Flex CharStyle:MenuItem
4983 status collapsed
4984
4985 \begin_layout Plain Layout
4986 ^e
4987 \end_layout
4988
4989 \end_inset
4990
4991
4992 \begin_inset Quotes erd
4993 \end_inset
4994
4995  produces the letter:
4996 \begin_inset Quotes eld
4997 \end_inset
4998
4999 ê
5000 \begin_inset Quotes erd
5001 \end_inset
5002
5003 .
5004  If you tried to type
5005 \begin_inset Quotes eld
5006 \end_inset
5007
5008
5009 \begin_inset Flex CharStyle:MenuItem
5010 status collapsed
5011
5012 \begin_layout Plain Layout
5013 ^t
5014 \end_layout
5015
5016 \end_inset
5017
5018
5019 \begin_inset Quotes erd
5020 \end_inset
5021
5022 , however, LyX will complain with a beep, since a
5023 \begin_inset Quotes eld
5024 \end_inset
5025
5026
5027 \begin_inset Flex CharStyle:MenuItem
5028 status collapsed
5029
5030 \begin_layout Plain Layout
5031 t
5032 \end_layout
5033
5034 \end_inset
5035
5036
5037 \begin_inset Quotes erd
5038 \end_inset
5039
5040  never takes a circumflex accent.
5041  Hitting
5042 \begin_inset Flex CharStyle:MenuItem
5043 status collapsed
5044
5045 \begin_layout Plain Layout
5046 Space
5047 \end_layout
5048
5049 \end_inset
5050
5051  after a dead-key produces the bare-accent.
5052  Please note this last point! If you bind a key to a dead-key, you'll need
5053  to rebind the character on that key to yet another key.
5054  Binding the
5055 \begin_inset Flex CharStyle:MenuItem
5056 status collapsed
5057
5058 \begin_layout Plain Layout
5059 ,-key
5060 \end_layout
5061
5062 \end_inset
5063
5064  to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5065 \end_layout
5066
5067 \begin_layout Standard
5068 One common way to bind dead-keys is to use
5069 \begin_inset Flex CharStyle:MenuItem
5070 status collapsed
5071
5072 \begin_layout Plain Layout
5073 Meta-
5074 \end_layout
5075
5076 \end_inset
5077
5078 ,
5079 \begin_inset Flex CharStyle:MenuItem
5080 status collapsed
5081
5082 \begin_layout Plain Layout
5083 Ctrl-
5084 \end_layout
5085
5086 \end_inset
5087
5088 , and
5089 \begin_inset Flex CharStyle:MenuItem
5090 status collapsed
5091
5092 \begin_layout Plain Layout
5093 Shift-
5094 \end_layout
5095
5096 \end_inset
5097
5098  in combination with an accent, like
5099 \begin_inset Quotes eld
5100 \end_inset
5101
5102
5103 \begin_inset Flex CharStyle:MenuItem
5104 status collapsed
5105
5106 \begin_layout Plain Layout
5107 ~
5108 \end_layout
5109
5110 \end_inset
5111
5112
5113 \begin_inset Quotes erd
5114 \end_inset
5115
5116  or
5117 \begin_inset Quotes eld
5118 \end_inset
5119
5120
5121 \begin_inset Flex CharStyle:MenuItem
5122 status collapsed
5123
5124 \begin_layout Plain Layout
5125 ,
5126 \end_layout
5127
5128 \end_inset
5129
5130
5131 \begin_inset Quotes erd
5132 \end_inset
5133
5134  or
5135 \begin_inset Quotes eld
5136 \end_inset
5137
5138
5139 \begin_inset Flex CharStyle:MenuItem
5140 status collapsed
5141
5142 \begin_layout Plain Layout
5143 ^
5144 \end_layout
5145
5146 \end_inset
5147
5148
5149 \begin_inset Quotes erd
5150 \end_inset
5151
5152 .
5153  Another way involves using
5154 \begin_inset Flex CharStyle:Code
5155 status collapsed
5156
5157 \begin_layout Plain Layout
5158 xmodmap
5159 \end_layout
5160
5161 \end_inset
5162
5163  and
5164 \begin_inset Flex CharStyle:Code
5165 status collapsed
5166
5167 \begin_layout Plain Layout
5168 xkeycaps
5169 \end_layout
5170
5171 \end_inset
5172
5173  to set up the special
5174 \begin_inset Flex CharStyle:Code
5175 status collapsed
5176
5177 \begin_layout Plain Layout
5178 Mode_Switch
5179 \end_layout
5180
5181 \end_inset
5182
5183  key.
5184  The
5185 \begin_inset Flex CharStyle:Code
5186 status collapsed
5187
5188 \begin_layout Plain Layout
5189 Mode_Switch
5190 \end_layout
5191
5192 \end_inset
5193
5194  acts in some ways just like
5195 \begin_inset Flex CharStyle:MenuItem
5196 status collapsed
5197
5198 \begin_layout Plain Layout
5199 Shift
5200 \end_layout
5201
5202 \end_inset
5203
5204  and permits you to bind keys to accented characters.
5205  You can also turn keys into dead-keys by binding them to something like
5206
5207 \begin_inset Flex CharStyle:Code
5208 status collapsed
5209
5210 \begin_layout Plain Layout
5211 usldead_cedilla
5212 \end_layout
5213
5214 \end_inset
5215
5216  and then binding this symbolic key to the corresponding LyX command.
5217 \begin_inset Foot
5218 status collapsed
5219
5220 \begin_layout Plain Layout
5221 Note from
5222 \noun on
5223 John Weiss
5224 \noun default
5225 : This is exactly what I do in my
5226 \begin_inset Flex CharStyle:Code
5227 status collapsed
5228
5229 \begin_layout Plain Layout
5230 ~/.lyx/lyxrc
5231 \end_layout
5232
5233 \end_inset
5234
5235  and my
5236 \begin_inset Flex CharStyle:Code
5237 status collapsed
5238
5239 \begin_layout Plain Layout
5240 ~/.xmodmap
5241 \end_layout
5242
5243 \end_inset
5244
5245  files.
5246  I have my
5247 \begin_inset Flex CharStyle:MenuItem
5248 status collapsed
5249
5250 \begin_layout Plain Layout
5251 Scroll
5252 \begin_inset space ~
5253 \end_inset
5254
5255 Lock
5256 \end_layout
5257
5258 \end_inset
5259
5260  key set up as
5261 \begin_inset Flex CharStyle:Code
5262 status collapsed
5263
5264 \begin_layout Plain Layout
5265 Mode_Shift
5266 \end_layout
5267
5268 \end_inset
5269
5270  and a bunch of these
5271 \begin_inset Quotes eld
5272 \end_inset
5273
5274
5275 \begin_inset Flex CharStyle:Code
5276 status collapsed
5277
5278 \begin_layout Plain Layout
5279 usldead_*
5280 \end_layout
5281
5282 \end_inset
5283
5284
5285 \begin_inset Quotes erd
5286 \end_inset
5287
5288  symbolic keys bound such things as
5289 \begin_inset Flex CharStyle:MenuItem
5290 status collapsed
5291
5292 \begin_layout Plain Layout
5293 Scroll
5294 \begin_inset space ~
5295 \end_inset
5296
5297 Lock-^
5298 \end_layout
5299
5300 \end_inset
5301
5302  and
5303 \begin_inset Flex CharStyle:MenuItem
5304 status collapsed
5305
5306 \begin_layout Plain Layout
5307 Scroll
5308 \begin_inset space ~
5309 \end_inset
5310
5311 Lock-~
5312 \end_layout
5313
5314 \end_inset
5315
5316 .
5317  This is how I produce my accented characters.
5318 \end_layout
5319
5320 \end_inset
5321
5322  You can make just about anything into the
5323 \begin_inset Flex CharStyle:Code
5324 status collapsed
5325
5326 \begin_layout Plain Layout
5327 Mode_Switch
5328 \end_layout
5329
5330 \end_inset
5331
5332  key: One of the
5333 \begin_inset Flex CharStyle:MenuItem
5334 status collapsed
5335
5336 \begin_layout Plain Layout
5337 Ctrl-
5338 \end_layout
5339
5340 \end_inset
5341
5342  keys, a spare function key, etc.
5343  As for the LyX commands that produce accents, check the entry for
5344 \begin_inset Flex CharStyle:Code
5345 status collapsed
5346
5347 \begin_layout Plain Layout
5348 accent-acute
5349 \end_layout
5350
5351 \end_inset
5352
5353  in the
5354 \emph on
5355 Reference Manual
5356 \emph default
5357 .
5358  You'll find the complete list there.
5359 \end_layout
5360
5361 \begin_layout Subsection
5362 Saving your Language Configuration
5363 \end_layout
5364
5365 \begin_layout Standard
5366 You can edit your preferences so that your desired language environment
5367  is automatically configured when LyX starts up, via the
5368 \begin_inset Flex CharStyle:MenuItem
5369 status collapsed
5370
5371 \begin_layout Plain Layout
5372 Edit\SpecialChar \menuseparator
5373 Preferences
5374 \end_layout
5375
5376 \end_inset
5377
5378  dialog.
5379 \end_layout
5380
5381 \begin_layout Chapter
5382 Installing New Document Classes, Layouts, and Templates
5383 \begin_inset CommandInset label
5384 LatexCommand label
5385 name "chap:textclass"
5386
5387 \end_inset
5388
5389
5390 \begin_inset OptArg
5391 status collapsed
5392
5393 \begin_layout Plain Layout
5394 Installing New Document Classes
5395 \end_layout
5396
5397 \end_inset
5398
5399
5400 \end_layout
5401
5402 \begin_layout Standard
5403 In this chapter, we describe the procedures for creating and installing
5404  new LyX layout and template files, as well as offer a refresher on correctly
5405  installing new LaTeX document classes.
5406  Some definitions: a document class is a LaTeX file (usually ending in
5407 \begin_inset Flex CharStyle:Code
5408 status collapsed
5409
5410 \begin_layout Plain Layout
5411 .cls
5412 \end_layout
5413
5414 \end_inset
5415
5416  or
5417 \begin_inset Flex CharStyle:Code
5418 status collapsed
5419
5420 \begin_layout Plain Layout
5421 .sty
5422 \end_layout
5423
5424 \end_inset
5425
5426 ) that describes the format of a document such as an article, report, journal
5427  preprint, etc, and all the commands needed to realize that format.
5428  A layout file is a LyX file that corresponds to a LaTeX document class
5429  and that tells LyX how to
5430 \begin_inset Quotes eld
5431 \end_inset
5432
5433 draw
5434 \begin_inset Quotes erd
5435 \end_inset
5436
5437  things on the screen to make the display look something like the final
5438  printed page.
5439  More precisely, a layout file describes a
5440 \begin_inset Quotes eld
5441 \end_inset
5442
5443 text class
5444 \begin_inset Quotes erd
5445 \end_inset
5446
5447  which is the internal construct LyX uses to render the screen display.
5448
5449 \begin_inset Quotes eld
5450 \end_inset
5451
5452 Layout
5453 \begin_inset Quotes erd
5454 \end_inset
5455
5456  and
5457 \begin_inset Quotes eld
5458 \end_inset
5459
5460 text class
5461 \begin_inset Quotes erd
5462 \end_inset
5463
5464  can be used somewhat interchangeably, but it is better to refer to the
5465  file as the layout, and the thing living in LyX's memory as the text class.
5466  A template file is simply a LyX document that contains a set of predefined
5467  entries for a given document class—entries that are generally required
5468  for that class.
5469  Templates are especially useful for things like journal manuscripts that
5470  are to be submitted electronically.
5471 \end_layout
5472
5473 \begin_layout Section
5474 Installing a new LaTeX package
5475 \end_layout
5476
5477 \begin_layout Standard
5478 Some installations may not include a LaTeX package that you would like to
5479  use within LyX.
5480  For example, you might need FoilTeX, a package for preparing slides or
5481  viewgraphs for overhead projectors.
5482  Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5483  a user interface for that.
5484  For example on MiKTeX you start its program
5485 \begin_inset Quotes eld
5486 \end_inset
5487
5488 Browse Packages
5489 \begin_inset Quotes erd
5490 \end_inset
5491
5492  to get a list of available packages.
5493  To install one, right click on it or use the installing toolbar button.
5494  When the package you want to install is not in the list, but you have it
5495  in form of a
5496 \begin_inset Flex CharStyle:Code
5497 status collapsed
5498
5499 \begin_layout Plain Layout
5500 .cls
5501 \end_layout
5502
5503 \end_inset
5504
5505  or
5506 \begin_inset Flex CharStyle:Code
5507 status collapsed
5508
5509 \begin_layout Plain Layout
5510 .sty
5511 \end_layout
5512
5513 \end_inset
5514
5515 -file, then copy these files to a subfolder of your LaTeX distribution,
5516  for example to the folder
5517 \family sans
5518 ~
5519 \backslash
5520 tex
5521 \backslash
5522 latex
5523 \family default
5524 .
5525  Then update the file name database of your LaTeX-distribution.
5526  For example on MiKTeX this is done by pressing the button
5527 \family sans
5528 Refresh
5529 \begin_inset space ~
5530 \end_inset
5531
5532 FNDB
5533 \family default
5534  that you find in MiKTeX's
5535 \begin_inset Quotes eld
5536 \end_inset
5537
5538 Settings
5539 \begin_inset Quotes erd
5540 \end_inset
5541
5542  program.
5543  In both cases you need afterwards to reconfigure LyX using the menu
5544 \begin_inset Flex CharStyle:MenuItem
5545 status collapsed
5546
5547 \begin_layout Plain Layout
5548 Tools\SpecialChar \menuseparator
5549 Reconfigure
5550 \end_layout
5551
5552 \end_inset
5553
5554  and then to restart LyX.
5555 \end_layout
5556
5557 \begin_layout Standard
5558 If your LaTeX distribution doesn't provide a user interface, then you can
5559  follow these steps by using a UNIX/Linux console.
5560 \end_layout
5561
5562 \begin_layout Enumerate
5563 Get the package from
5564 \begin_inset CommandInset href
5565 LatexCommand href
5566 name "CTAN"
5567 target "http://www.ctan.org/"
5568
5569 \end_inset
5570
5571  or wherever.
5572 \end_layout
5573
5574 \begin_layout Enumerate
5575 You can install this package in several different places.
5576  If you want it to be available for all users on your system, then you should
5577  install it in your `local' TeX tree; if you want (or need) it to be available
5578  just for you, then you can install it in your own `user' TeX tree.
5579  Where these should be created, if they do not already exist, depends upon
5580  the details of your system.
5581  To find out, look in the file
5582 \begin_inset Flex CharStyle:Code
5583 status collapsed
5584
5585 \begin_layout Plain Layout
5586 texmf.cnf
5587 \end_layout
5588
5589 \end_inset
5590
5591 .
5592 \begin_inset Foot
5593 status collapsed
5594
5595 \begin_layout Plain Layout
5596 This usually lives in the directory
5597 \begin_inset Flex CharStyle:Code
5598 status collapsed
5599
5600 \begin_layout Plain Layout
5601 $TEXMF/web2c
5602 \end_layout
5603
5604 \end_inset
5605
5606 , though you can run
5607 \begin_inset Flex CharStyle:Code
5608 status collapsed
5609
5610 \begin_layout Plain Layout
5611 kpsewhich texmf.cnf
5612 \end_layout
5613
5614 \end_inset
5615
5616  to locate it.
5617 \end_layout
5618
5619 \end_inset
5620
5621  The location of the `local' TeX tree is defined by
5622 \begin_inset Flex CharStyle:Code
5623 status collapsed
5624
5625 \begin_layout Plain Layout
5626 TEXMFLOCAL
5627 \end_layout
5628
5629 \end_inset
5630
5631 ; this is usually somewhere like
5632 \begin_inset Flex CharStyle:Code
5633 status collapsed
5634
5635 \begin_layout Plain Layout
5636 /usr/local/share/texmf/
5637 \end_layout
5638
5639 \end_inset
5640
5641 .
5642  The `user' TeX tree is defined by
5643 \begin_inset Flex CharStyle:Code
5644 status collapsed
5645
5646 \begin_layout Plain Layout
5647 TEXMFHOME
5648 \end_layout
5649
5650 \end_inset
5651
5652  and is commonly at
5653 \begin_inset Flex CharStyle:Code
5654 status collapsed
5655
5656 \begin_layout Plain Layout
5657 $HOME/texmf/
5658 \end_layout
5659
5660 \end_inset
5661
5662 .
5663  (If these variables are not predefined, you can define them.) You'll probably
5664  need root permissions to create or modify the `local' tree; but your `user'
5665  tree shouldn't have such limitations.
5666 \end_layout
5667
5668 \begin_layout Enumerate
5669 Make sure
5670 \begin_inset Flex CharStyle:Code
5671 status collapsed
5672
5673 \begin_layout Plain Layout
5674 TEXMF
5675 \end_layout
5676
5677 \end_inset
5678
5679  includes the
5680 \begin_inset Flex CharStyle:Code
5681 status collapsed
5682
5683 \begin_layout Plain Layout
5684 TEXMFLOCAL
5685 \end_layout
5686
5687 \end_inset
5688
5689  and
5690 \begin_inset Flex CharStyle:Code
5691 status collapsed
5692
5693 \begin_layout Plain Layout
5694 TEXMFHOME
5695 \end_layout
5696
5697 \end_inset
5698
5699  variables; e.
5700 \begin_inset space \thinspace{}
5701 \end_inset
5702
5703 g.
5704 \begin_inset Newline newline
5705 \end_inset
5706
5707
5708 \begin_inset Flex CharStyle:Code
5709 status collapsed
5710
5711 \begin_layout Plain Layout
5712 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5713 \end_layout
5714
5715 \end_inset
5716
5717
5718 \begin_inset Newline newline
5719 \end_inset
5720
5721 But, again, most of this will
5722 \begin_inset Quotes eld
5723 \end_inset
5724
5725 just work
5726 \begin_inset Quotes erd
5727 \end_inset
5728
5729 .
5730 \end_layout
5731
5732 \begin_layout Enumerate
5733 Create your local
5734 \begin_inset Foot
5735 status collapsed
5736
5737 \begin_layout Plain Layout
5738 We'll assume henceforth that you're defining `local' TeX tree.
5739  If you're defining a user tree, just adjust as necessary.
5740 \end_layout
5741
5742 \end_inset
5743
5744  TeX tree.
5745  You must follow the directory structure of your existing
5746 \begin_inset Flex CharStyle:Code
5747 status collapsed
5748
5749 \begin_layout Plain Layout
5750 texmf
5751 \end_layout
5752
5753 \end_inset
5754
5755  directory, which will be found at
5756 \begin_inset Flex CharStyle:Code
5757 status collapsed
5758
5759 \begin_layout Plain Layout
5760 TEXMFMAIN
5761 \end_layout
5762
5763 \end_inset
5764
5765 .
5766  For example, latex packages should go under
5767 \begin_inset Flex CharStyle:Code
5768 status collapsed
5769
5770 \begin_layout Plain Layout
5771 $TEXMFLOCAL/tex/latex/
5772 \end_layout
5773
5774 \end_inset
5775
5776 .
5777 \end_layout
5778
5779 \begin_layout Enumerate
5780 Install the package.
5781  For example, you would unpack the FoilTeX tarball and copy it to
5782 \begin_inset Flex CharStyle:Code
5783 status collapsed
5784
5785 \begin_layout Plain Layout
5786 $TEXMFLOCAL/tex/latex/foiltex
5787 \end_layout
5788
5789 \end_inset
5790
5791 .
5792  The
5793 \begin_inset Flex CharStyle:Code
5794 status collapsed
5795
5796 \begin_layout Plain Layout
5797 foiltex
5798 \end_layout
5799
5800 \end_inset
5801
5802  directory contains various files.
5803 \end_layout
5804
5805 \begin_layout Enumerate
5806 Run:
5807 \begin_inset Flex CharStyle:Code
5808 status collapsed
5809
5810 \begin_layout Plain Layout
5811 texhash
5812 \end_layout
5813
5814 \end_inset
5815
5816 .
5817  This should create
5818 \begin_inset Flex CharStyle:Code
5819 status collapsed
5820
5821 \begin_layout Plain Layout
5822 $TEXMFLOCAL/ls-R
5823 \end_layout
5824
5825 \end_inset
5826
5827  amongst others.
5828 \end_layout
5829
5830 \begin_layout Standard
5831 Your package is now installed and available to LaTeX.
5832  To make it available to LyX, you need to create a Layout file, if one is
5833  not already available.
5834  (See the next section.) Once you have a layout file, you need only reconfigure
5835  (
5836 \begin_inset Flex CharStyle:MenuItem
5837 status collapsed
5838
5839 \begin_layout Plain Layout
5840 Tools\SpecialChar \menuseparator
5841 Reconfigure
5842 \end_layout
5843
5844 \end_inset
5845
5846 ) and then restart LyX.
5847  You should then see your new package—for example
5848 \begin_inset Flex CharStyle:MenuItem
5849 status collapsed
5850
5851 \begin_layout Plain Layout
5852 slides (FoilTeX)
5853 \end_layout
5854
5855 \end_inset
5856
5857 —under
5858 \begin_inset Flex CharStyle:MenuItem
5859 status collapsed
5860
5861 \begin_layout Plain Layout
5862 Document\SpecialChar \menuseparator
5863 Settings
5864 \end_layout
5865
5866 \end_inset
5867
5868  in the
5869 \begin_inset Flex CharStyle:MenuItem
5870 status collapsed
5871
5872 \begin_layout Plain Layout
5873 Document Class
5874 \end_layout
5875
5876 \end_inset
5877
5878  drop box.
5879
5880 \end_layout
5881
5882 \begin_layout Section
5883 Layouts
5884 \end_layout
5885
5886 \begin_layout Standard
5887 This section describes how to write and install your own LyX layout files
5888  and walks through the
5889 \begin_inset Flex CharStyle:Code
5890 status collapsed
5891
5892 \begin_layout Plain Layout
5893 article
5894 \end_layout
5895
5896 \end_inset
5897
5898  text class format as an example.
5899  The
5900 \begin_inset Flex CharStyle:Code
5901 status collapsed
5902
5903 \begin_layout Plain Layout
5904 .layout
5905 \end_layout
5906
5907 \end_inset
5908
5909  files describe what paragraph and character styles are available for a
5910  given document class and how LyX should display them.
5911  We try to provide a thorough description of the process here; however,
5912  there are so many different types of documents supported by LaTeX classes
5913  that we can't hope to cover every different possibility or problem you
5914  might encounter.
5915  (The LyX users' list is frequented by people with lots of experience with
5916  layout design who are willing to share what they've learned.)
5917 \end_layout
5918
5919 \begin_layout Standard
5920 As you prepare to write a new layout, it is extremely helpful to look at
5921  the example layouts distributed with LyX.
5922  If you use a nice LaTeX document class that might be of interest for others,
5923  too, and have a nice corresponding LyX layout, feel free to contribute
5924  the stuff to us, so we may put it into the distribution.
5925  There is also a
5926 \begin_inset CommandInset href
5927 LatexCommand href
5928 name "section on the LyX wiki"
5929 target "http://wiki.lyx.org/Layouts/Layouts"
5930
5931 \end_inset
5932
5933  for this kind of material.
5934 \end_layout
5935
5936 \begin_layout Standard
5937 All the tags described in this chapter are case-insensitive; this means
5938  that
5939 \begin_inset Flex CharStyle:Code
5940 status collapsed
5941
5942 \begin_layout Plain Layout
5943 Style
5944 \end_layout
5945
5946 \end_inset
5947
5948 ,
5949 \begin_inset Flex CharStyle:Code
5950 status collapsed
5951
5952 \begin_layout Plain Layout
5953 style
5954 \end_layout
5955
5956 \end_inset
5957
5958  and
5959 \begin_inset Flex CharStyle:Code
5960 status collapsed
5961
5962 \begin_layout Plain Layout
5963 StYlE
5964 \end_layout
5965
5966 \end_inset
5967
5968  are really the same command.
5969  The possible values are printed in brackets after the feature's name.
5970  The default value if a feature isn't specified inside a text class-description
5971  is typeset
5972 \begin_inset Flex CharStyle:Code
5973 status collapsed
5974
5975 \begin_layout Plain Layout
5976
5977 \emph on
5978 emphasized
5979 \end_layout
5980
5981 \end_inset
5982
5983 .
5984  If the argument has a data type like
5985 \begin_inset Quotes eld
5986 \end_inset
5987
5988 string
5989 \begin_inset Quotes erd
5990 \end_inset
5991
5992  or
5993 \begin_inset Quotes eld
5994 \end_inset
5995
5996 float
5997 \begin_inset Quotes erd
5998 \end_inset
5999
6000 , the default is shown like this:
6001 \begin_inset Flex CharStyle:Code
6002 status collapsed
6003
6004 \begin_layout Plain Layout
6005 float=
6006 \emph on
6007 default
6008 \end_layout
6009
6010 \end_inset
6011
6012 .
6013 \end_layout
6014
6015 \begin_layout Subsection
6016 \begin_inset CommandInset label
6017 LatexCommand label
6018 name "sub:Layout-modules"
6019
6020 \end_inset
6021
6022 Layout modules
6023 \end_layout
6024
6025 \begin_layout Standard
6026 Similar to layout files, and new with LyX 1.6, are layout
6027 \emph on
6028 modules
6029 \emph default
6030 .
6031  Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6032  some modules—such as the endnotes module—provide support for just such
6033  a package.
6034  In a sense, layout modules are similar to included files—files like
6035 \begin_inset Flex CharStyle:Code
6036 status collapsed
6037
6038 \begin_layout Plain Layout
6039 stdsections.inc
6040 \end_layout
6041
6042 \end_inset
6043
6044 —in that modules are not specific to a given document layout but may be
6045  used with many different layouts.
6046  The difference is that using a layout module does not require editing the
6047  layout file.
6048  Rather, modules are selected in the
6049 \begin_inset Flex CharStyle:MenuItem
6050 status collapsed
6051
6052 \begin_layout Plain Layout
6053 Document\SpecialChar \menuseparator
6054 Settings
6055 \end_layout
6056
6057 \end_inset
6058
6059  dialog.
6060 \end_layout
6061
6062 \begin_layout Standard
6063 Building modules is the easiest way to get started with layout editing,
6064  since it can be as simple as adding a single new paragraph or flex inset.
6065  But modules may, in principle, contain anything a layout file can contain.
6066 \end_layout
6067
6068 \begin_layout Standard
6069 A module must begin with a line like the following:
6070 \end_layout
6071
6072 \begin_layout LyX-Code
6073 #
6074 \backslash
6075 DeclareLyXModule[endnotes.sty]{Endnotes}
6076 \end_layout
6077
6078 \begin_layout Standard
6079 The argument in square brackets is optional: It declares any LaTeX packages
6080  on which the module depends.
6081  The mandatory argument, in curly brackets, is the name of the module, as
6082  it should appear in
6083 \begin_inset Flex CharStyle:MenuItem
6084 status collapsed
6085
6086 \begin_layout Plain Layout
6087 Document\SpecialChar \menuseparator
6088 Settings
6089 \end_layout
6090
6091 \end_inset
6092
6093 .
6094
6095 \end_layout
6096
6097 \begin_layout Standard
6098 The module declaration should then be followed by lines like the following:
6099 \end_layout
6100
6101 \begin_layout LyX-Code
6102 #DescriptionBegin
6103 \end_layout
6104
6105 \begin_layout LyX-Code
6106 #Adds an endnote command, in addition to footnotes.
6107
6108 \end_layout
6109
6110 \begin_layout LyX-Code
6111 #You will need to add
6112 \backslash
6113 theendnotes in TeX code where you
6114 \end_layout
6115
6116 \begin_layout LyX-Code
6117 #want the endnotes to appear.
6118
6119 \end_layout
6120
6121 \begin_layout LyX-Code
6122 #DescriptionEnd
6123 \end_layout
6124
6125 \begin_layout LyX-Code
6126 #Requires: somemodule | othermodule
6127 \end_layout
6128
6129 \begin_layout LyX-Code
6130 #Excludes: badmodule
6131 \end_layout
6132
6133 \begin_layout Standard
6134 The description is used in
6135 \begin_inset Flex CharStyle:MenuItem
6136 status collapsed
6137
6138 \begin_layout Plain Layout
6139 Document\SpecialChar \menuseparator
6140 Settings
6141 \end_layout
6142
6143 \end_inset
6144
6145  to provide the user with information about what the module does.
6146  The
6147 \begin_inset Flex CharStyle:Code
6148 status collapsed
6149
6150 \begin_layout Plain Layout
6151 Requires
6152 \end_layout
6153
6154 \end_inset
6155
6156  line is used to identify other modules with which this one must be used;
6157  the
6158 \begin_inset Flex CharStyle:Code
6159 status collapsed
6160
6161 \begin_layout Plain Layout
6162 Excludes
6163 \end_layout
6164
6165 \end_inset
6166
6167  line is used to identify modules with which this one may not be used.
6168  Both are optional, and, as shown, multiple modules should be separated
6169  with the pipe symbol: |.
6170  Note that the required modules are treated disjunctively:
6171 \emph on
6172 at least one
6173 \emph default
6174  of the required modules must be used.
6175  Similarly,
6176 \emph on
6177 no
6178 \emph default
6179  excluded module may be used.
6180  Note that modules are identified here by their
6181 \emph on
6182 filenames
6183 \emph default
6184  without the .module extension.
6185  So
6186 \begin_inset Flex CharStyle:Code
6187 status collapsed
6188
6189 \begin_layout Plain Layout
6190 somemodule
6191 \end_layout
6192
6193 \end_inset
6194
6195  is really
6196 \begin_inset Flex CharStyle:Code
6197 status collapsed
6198
6199 \begin_layout Plain Layout
6200 somemodule.module
6201 \end_layout
6202
6203 \end_inset
6204
6205 .
6206 \end_layout
6207
6208 \begin_layout Standard
6209 After creating a new module, you will need to reconfigure and then restart
6210  LyX for the module to appear in the menu.
6211  However, changes you make to the module will be seen immediately, if you
6212  open
6213 \begin_inset Flex CharStyle:MenuItem
6214 status collapsed
6215
6216 \begin_layout Plain Layout
6217 Document\SpecialChar \menuseparator
6218 Settings
6219 \end_layout
6220
6221 \end_inset
6222
6223 , highlight something, and then hit
6224 \begin_inset Quotes eld
6225 \end_inset
6226
6227 OK
6228 \begin_inset Quotes erd
6229 \end_inset
6230
6231 .
6232
6233 \emph on
6234 It is strongly recommended that you save your work before doing so
6235 \emph default
6236 .
6237  In fact,
6238 \emph on
6239 it is strongly recommended that you not attempt to edit modules while simultaneo
6240 usly working on documents
6241 \emph default
6242 .
6243  Though of course the developers strive to keep LyX stable in such situations,
6244  syntax errors and the like in your module file could cause strange behavior.
6245 \end_layout
6246
6247 \begin_layout Subsection
6248 Supporting new document classes
6249 \end_layout
6250
6251 \begin_layout Standard
6252 There are two situations you are likely to encounter when wanting to support
6253  a new LaTeX document class, involving LaTeX2e class (
6254 \begin_inset Flex CharStyle:Code
6255 status collapsed
6256
6257 \begin_layout Plain Layout
6258 .cls
6259 \end_layout
6260
6261 \end_inset
6262
6263 ) and style (
6264 \begin_inset Flex CharStyle:Code
6265 status collapsed
6266
6267 \begin_layout Plain Layout
6268 .sty
6269 \end_layout
6270
6271 \end_inset
6272
6273 ) files.
6274  Supporting a style file is usually fairly easy.
6275  Supporting a new document class is a bit harder.
6276 \end_layout
6277
6278 \begin_layout Subsection
6279 A layout for a
6280 \begin_inset Flex CharStyle:MenuItem
6281 status collapsed
6282
6283 \begin_layout Plain Layout
6284 sty
6285 \end_layout
6286
6287 \end_inset
6288
6289  file
6290 \end_layout
6291
6292 \begin_layout Standard
6293 If your new document class is provided as a style file that is used in conjuncti
6294 on with an existing, supported document class—for the sake of the example,
6295  we'll assume that the style file is called
6296 \begin_inset Flex CharStyle:MenuItem
6297 status collapsed
6298
6299 \begin_layout Plain Layout
6300 myclass.sty
6301 \end_layout
6302
6303 \end_inset
6304
6305  and it is meant to be used with
6306 \begin_inset Flex CharStyle:MenuItem
6307 status collapsed
6308
6309 \begin_layout Plain Layout
6310 report.cls
6311 \end_layout
6312
6313 \end_inset
6314
6315 , which is a standard class—start by copying the existing class's layout
6316  file into your local directory:
6317 \end_layout
6318
6319 \begin_layout LyX-Code
6320 cp report.layout ~/.lyx/layouts/myclass.layout
6321 \end_layout
6322
6323 \begin_layout Standard
6324 Then edit
6325 \begin_inset Flex CharStyle:Code
6326 status collapsed
6327
6328 \begin_layout Plain Layout
6329 myclass.layout
6330 \end_layout
6331
6332 \end_inset
6333
6334  and change the line:
6335 \end_layout
6336
6337 \begin_layout LyX-Code
6338
6339 \backslash
6340 DeclareLaTeXClass{report}
6341 \end_layout
6342
6343 \begin_layout Standard
6344 to read
6345 \end_layout
6346
6347 \begin_layout LyX-Code
6348
6349 \backslash
6350 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6351 \end_layout
6352
6353 \begin_layout Standard
6354 Then add:
6355 \end_layout
6356
6357 \begin_layout LyX-Code
6358 Preamble
6359 \begin_inset Newline newline
6360 \end_inset
6361
6362
6363 \backslash
6364 usepackage{myclass}
6365 \begin_inset Newline newline
6366 \end_inset
6367
6368 EndPreamble
6369 \end_layout
6370
6371 \begin_layout Standard
6372 near the top of the file.
6373 \end_layout
6374
6375 \begin_layout Standard
6376 Start LyX and select
6377 \begin_inset Flex CharStyle:MenuItem
6378 status collapsed
6379
6380 \begin_layout Plain Layout
6381 Tools\SpecialChar \menuseparator
6382 Reconfigure
6383 \end_layout
6384
6385 \end_inset
6386
6387 .
6388  Then restart LyX and try creating a new document.
6389  You should see "
6390 \begin_inset Flex CharStyle:MenuItem
6391 status collapsed
6392
6393 \begin_layout Plain Layout
6394 report (myclass)
6395 \end_layout
6396
6397 \end_inset
6398
6399 " as a document class option in the
6400 \begin_inset Flex CharStyle:MenuItem
6401 status collapsed
6402
6403 \begin_layout Plain Layout
6404 Document\SpecialChar \menuseparator
6405 Settings
6406 \end_layout
6407
6408 \end_inset
6409
6410  dialog.
6411  It is likely that some of the sectioning commands and such in your new
6412  class will work differently from how they worked in the base class—
6413 \begin_inset Flex CharStyle:Code
6414 status collapsed
6415
6416 \begin_layout Plain Layout
6417 report
6418 \end_layout
6419
6420 \end_inset
6421
6422  in this example—so you can fiddle around with the settings for the different
6423  sections if you wish.
6424 \end_layout
6425
6426 \begin_layout Subsection
6427 Layout for a
6428 \begin_inset Flex CharStyle:MenuItem
6429 status collapsed
6430
6431 \begin_layout Plain Layout
6432 cls
6433 \end_layout
6434
6435 \end_inset
6436
6437  file
6438 \end_layout
6439
6440 \begin_layout Standard
6441 There are two possibilities here.
6442  One is that the class file is itself based upon an existing document class.
6443  For example, many thesis classes are based upon
6444 \begin_inset Flex CharStyle:MenuItem
6445 status collapsed
6446
6447 \begin_layout Plain Layout
6448 book.cls
6449 \end_layout
6450
6451 \end_inset
6452
6453 .
6454  To see whether yours is, look for a line like
6455 \end_layout
6456
6457 \begin_layout LyX-Code
6458
6459 \backslash
6460 LoadClass{book}
6461 \end_layout
6462
6463 \begin_layout Standard
6464 in the file.
6465  If so, then you may proceed largely as in the previous section, though
6466  the DeclareLaTeXClass line will be different.
6467  If your new class is thesis, and it is based upon book, then the line should
6468  read:
6469 \begin_inset Foot
6470 status collapsed
6471
6472 \begin_layout Plain Layout
6473 And it will be easiest if you save the file to
6474 \begin_inset Flex CharStyle:Code
6475 status collapsed
6476
6477 \begin_layout Plain Layout
6478 thesis.layout
6479 \end_layout
6480
6481 \end_inset
6482
6483 : LyX assumes that the document class has the same name as the layout file.
6484
6485 \end_layout
6486
6487 \end_inset
6488
6489
6490 \end_layout
6491
6492 \begin_layout LyX-Code
6493
6494 \backslash
6495 DeclareLaTeXClass[thesis,book]{thesis}
6496 \end_layout
6497
6498 \begin_layout Standard
6499 If, on the other hand, the new class is not based upon an existing class,
6500  you will probably have to
6501 \begin_inset Quotes eld
6502 \end_inset
6503
6504 roll your own
6505 \begin_inset Quotes erd
6506 \end_inset
6507
6508  layout.
6509  We strongly suggest copying an existing layout file which uses a similar
6510  LaTeX class and then modifying it, if you can do so.
6511  At least use an existing file as a starting point so you can find out what
6512  items you need to worry about.
6513  Again, the specifics are covered below.
6514 \end_layout
6515
6516 \begin_layout Section
6517 Declaring a new text class
6518 \end_layout
6519
6520 \begin_layout Standard
6521 When it's finally time to get your hands dirty and create or edit your own
6522  layout file, the following sections describe what you're up against.
6523  Our advice is to go slowly, save and test often, listen to soothing music,
6524  and enjoy one or two of your favorite adult beverages; more if you are
6525  getting particularly stuck.
6526  It's really not that hard, except that the multitude of options can become
6527  overwhelming if you try to do to much in one sitting.
6528  Go have another adult beverage, just for good measure.
6529 \end_layout
6530
6531 \begin_layout Standard
6532 Here we go!
6533 \end_layout
6534
6535 \begin_layout Standard
6536 Lines in a layout file which begin with a
6537 \begin_inset Flex CharStyle:Code
6538 status collapsed
6539
6540 \begin_layout Plain Layout
6541 #
6542 \end_layout
6543
6544 \end_inset
6545
6546  are comments.
6547  There is one exception to this rule: all layouts should begin with lines
6548  like:
6549 \end_layout
6550
6551 \begin_layout LyX-Code
6552
6553 \size small
6554 #% Do not delete the line below; configure depends on this
6555 \end_layout
6556
6557 \begin_layout LyX-Code
6558
6559 \size small
6560 #
6561 \backslash
6562 DeclareLaTeXClass{article}
6563 \end_layout
6564
6565 \begin_layout Standard
6566 The second line is used when you configure LyX.
6567  The layout file is read by the LaTeX script
6568 \begin_inset Flex CharStyle:Code
6569 status collapsed
6570
6571 \begin_layout Plain Layout
6572 chkconfig.ltx
6573 \end_layout
6574
6575 \end_inset
6576
6577 , in a special mode where
6578 \begin_inset Flex CharStyle:Code
6579 status collapsed
6580
6581 \begin_layout Plain Layout
6582 #
6583 \end_layout
6584
6585 \end_inset
6586
6587  is ignored.
6588  The first line is just a LaTeX comment, and the second one contains the
6589  declaration of the text class.
6590  If these lines appear in a file named
6591 \begin_inset Flex CharStyle:Code
6592 status collapsed
6593
6594 \begin_layout Plain Layout
6595 article.layout
6596 \end_layout
6597
6598 \end_inset
6599
6600 , then they define a text class of name
6601 \begin_inset Flex CharStyle:Code
6602 status collapsed
6603
6604 \begin_layout Plain Layout
6605 article
6606 \end_layout
6607
6608 \end_inset
6609
6610  (the name of the layout file) which uses the LaTeX document class
6611 \begin_inset Flex CharStyle:Code
6612 status collapsed
6613
6614 \begin_layout Plain Layout
6615 article.cls
6616 \end_layout
6617
6618 \end_inset
6619
6620  (the default is to use the same name as the layout).
6621  The string
6622 \begin_inset Quotes eld
6623 \end_inset
6624
6625 article
6626 \begin_inset Quotes erd
6627 \end_inset
6628
6629  that appears above is used as a description of the text class in the
6630 \begin_inset Flex CharStyle:MenuItem
6631 status collapsed
6632
6633 \begin_layout Plain Layout
6634 Document\SpecialChar \menuseparator
6635 Settings
6636 \end_layout
6637
6638 \end_inset
6639
6640  dialog.
6641 \end_layout
6642
6643 \begin_layout Standard
6644 Let's assume that you wrote your own text class that uses the
6645 \begin_inset Flex CharStyle:Code
6646 status collapsed
6647
6648 \begin_layout Plain Layout
6649 article.cls
6650 \end_layout
6651
6652 \end_inset
6653
6654  document class, but where you changed the appearance of the section headings.
6655  If you put it in a file
6656 \begin_inset Flex CharStyle:Code
6657 status collapsed
6658
6659 \begin_layout Plain Layout
6660 myarticle.layout
6661 \end_layout
6662
6663 \end_inset
6664
6665 , the header of this file should be:
6666 \end_layout
6667
6668 \begin_layout LyX-Code
6669
6670 \size small
6671 #% Do not delete the line below; configure depends on this
6672 \end_layout
6673
6674 \begin_layout LyX-Code
6675
6676 \size small
6677 #
6678 \backslash
6679 DeclareLaTeXClass[article]{article (with my own headings)}
6680 \end_layout
6681
6682 \begin_layout Standard
6683 This declares a text class
6684 \begin_inset Flex CharStyle:Code
6685 status collapsed
6686
6687 \begin_layout Plain Layout
6688 myarticle
6689 \end_layout
6690
6691 \end_inset
6692
6693 , associated with the LaTeX document class
6694 \begin_inset Flex CharStyle:Code
6695 status collapsed
6696
6697 \begin_layout Plain Layout
6698 article.cls
6699 \end_layout
6700
6701 \end_inset
6702
6703  and described as
6704 \begin_inset Quotes eld
6705 \end_inset
6706
6707 article (with my own headings)
6708 \begin_inset Quotes erd
6709 \end_inset
6710
6711 .
6712  If your text class depends on several packages, you can declare it as:
6713 \end_layout
6714
6715 \begin_layout LyX-Code
6716
6717 \size small
6718 #% Do not delete the line below; configure depends on this
6719 \end_layout
6720
6721 \begin_layout LyX-Code
6722
6723 \size small
6724 #
6725 \backslash
6726 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6727 \end_layout
6728
6729 \begin_layout Standard
6730 This indicates that your text class uses the foo.sty package.
6731  Finally, it is also possible to declare classes for DocBook code.
6732  Typical declarations will look like
6733 \end_layout
6734
6735 \begin_layout LyX-Code
6736
6737 \size small
6738 #% Do not delete the line below; configure depends on this
6739 \end_layout
6740
6741 \begin_layout LyX-Code
6742
6743 \size small
6744 #
6745 \backslash
6746 DeclareDocBookClass[article]{SGML (DocBook article)}
6747 \end_layout
6748
6749 \begin_layout Standard
6750 Note that these declarations can also be given an optional parameter declaring
6751  the name of the document class (but not a list).
6752 \end_layout
6753
6754 \begin_layout Standard
6755 So, to be as explicit as possible, the form of the layout declaration is:
6756 \end_layout
6757
6758 \begin_layout LyX-Code
6759
6760 \size small
6761 #
6762 \backslash
6763 DeclareLaTeXClass[class,package.sty]{layout description}
6764 \end_layout
6765
6766 \begin_layout Standard
6767 The class need only be specified if the name of the LaTeX class file and
6768  the name of the layout file are different; if the name of the class file
6769  is not specified, then LyX will simply assume that it is the same as the
6770  name of the layout file.
6771 \end_layout
6772
6773 \begin_layout Standard
6774 When the text class has been modified to your taste, all you have to do
6775  is to copy it either to
6776 \begin_inset Flex CharStyle:Code
6777 status collapsed
6778
6779 \begin_layout Plain Layout
6780 LyXDir/layouts/
6781 \end_layout
6782
6783 \end_inset
6784
6785  or to
6786 \begin_inset Flex CharStyle:Code
6787 status collapsed
6788
6789 \begin_layout Plain Layout
6790 UserDir/layouts
6791 \end_layout
6792
6793 \end_inset
6794
6795 , run
6796 \begin_inset Flex CharStyle:MenuItem
6797 status collapsed
6798
6799 \begin_layout Plain Layout
6800 Tools\SpecialChar \menuseparator
6801 Reconfigure
6802 \end_layout
6803
6804 \end_inset
6805
6806 , exit LyX and restart it.
6807  Then your new text class should be available along with the others.
6808 \end_layout
6809
6810 \begin_layout Standard
6811 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6812  you made to your layout files.
6813  As a result, editing layout files could be very time consuming.
6814  Beginning with 1.6, however, you can force a reload of the layout currently
6815  in use by using the LyX function
6816 \begin_inset Flex CharStyle:MenuItem
6817 status collapsed
6818
6819 \begin_layout Plain Layout
6820 layout-reload
6821 \end_layout
6822
6823 \end_inset
6824
6825 .
6826  There is no default binding for this function—though, of course, you can
6827  bind it to a key yourself.
6828  If you want to use this function, then, you should simply enter it in the
6829  mini-buffer.
6830
6831 \emph on
6832 Warning
6833 \emph default
6834 : This is very much an `advanced feature'.
6835  It is
6836 \emph on
6837 strongly
6838 \emph default
6839  recommended that you save your work before using this function.
6840  In fact, it is
6841 \emph on
6842 strongly
6843 \emph default
6844  recommended that you not attempt to edit your layout while simultaneously
6845  working on a document that you care about.
6846  Use a test document.
6847  Syntax errors and the like in your layout file could cause peculiar behavior.
6848  In particular, such errors could cause LyX to regard the current layout
6849  as invalid and to attempt to switch to some other layout.
6850  The LyX team strives to keep LyX stable in such situations, but safe is
6851  better than sorry.
6852 \end_layout
6853
6854 \begin_layout Subsection
6855 File format
6856 \end_layout
6857
6858 \begin_layout Standard
6859 The first non-comment line must contain the file format number:
6860 \end_layout
6861
6862 \begin_layout Description
6863 \begin_inset Flex CharStyle:Code
6864 status collapsed
6865
6866 \begin_layout Plain Layout
6867 Format
6868 \end_layout
6869
6870 \end_inset
6871
6872  [
6873 \begin_inset Flex CharStyle:Code
6874 status collapsed
6875
6876 \begin_layout Plain Layout
6877 int
6878 \end_layout
6879
6880 \end_inset
6881
6882 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6883  don't have an explicit file format).
6884  The file format that is documented here is format 1
6885 \change_deleted 0 1234611237
6886 2
6887 \change_inserted 0 1234611237
6888 4
6889 \change_unchanged
6890 .
6891 \change_inserted 0 1234613411
6892
6893 \end_layout
6894
6895 \begin_layout Description
6896
6897 \change_inserted 0 1234613417
6898 FIXME: Format 13 is missing!
6899 \change_unchanged
6900
6901 \end_layout
6902
6903 \begin_layout Subsection
6904 General text class parameters
6905 \end_layout
6906
6907 \begin_layout Standard
6908 These are the general parameters which describe the form of the entire document:
6909 \end_layout
6910
6911 \begin_layout Description
6912 \begin_inset Flex CharStyle:Code
6913 status collapsed
6914
6915 \begin_layout Plain Layout
6916 AddToPreamble
6917 \end_layout
6918
6919 \end_inset
6920
6921  Adds information to the document preamble.
6922  Must end with
6923 \begin_inset Quotes eld
6924 \end_inset
6925
6926
6927 \begin_inset Flex CharStyle:Code
6928 status collapsed
6929
6930 \begin_layout Plain Layout
6931 EndPreamble
6932 \end_layout
6933
6934 \end_inset
6935
6936
6937 \begin_inset Quotes erd
6938 \end_inset
6939
6940 .
6941 \end_layout
6942
6943 \begin_layout Description
6944 \begin_inset Flex CharStyle:Code
6945 status collapsed
6946
6947 \begin_layout Plain Layout
6948 ClassOptions
6949 \end_layout
6950
6951 \end_inset
6952
6953  Describes various global options supported by the document class.
6954  See Section
6955 \begin_inset space ~
6956 \end_inset
6957
6958
6959 \begin_inset CommandInset ref
6960 LatexCommand ref
6961 reference "sec:classoptions"
6962
6963 \end_inset
6964
6965  for a description.
6966  Must end with
6967 \begin_inset Quotes eld
6968 \end_inset
6969
6970
6971 \begin_inset Flex CharStyle:Code
6972 status collapsed
6973
6974 \begin_layout Plain Layout
6975 End
6976 \end_layout
6977
6978 \end_inset
6979
6980
6981 \begin_inset Quotes erd
6982 \end_inset
6983
6984 .
6985 \end_layout
6986
6987 \begin_layout Description
6988 \begin_inset Flex CharStyle:Code
6989 status collapsed
6990
6991 \begin_layout Plain Layout
6992 Columns
6993 \end_layout
6994
6995 \end_inset
6996
6997  [
6998 \begin_inset Flex CharStyle:Code
6999 status collapsed
7000
7001 \begin_layout Plain Layout
7002
7003 \emph on
7004 1
7005 \end_layout
7006
7007 \end_inset
7008
7009 ,
7010 \begin_inset Flex CharStyle:Code
7011 status collapsed
7012
7013 \begin_layout Plain Layout
7014 2
7015 \end_layout
7016
7017 \end_inset
7018
7019 ] Whether the class should default to having one or two columns.
7020  Can be changed in the
7021 \begin_inset Flex CharStyle:MenuItem
7022 status collapsed
7023
7024 \begin_layout Plain Layout
7025 Document\SpecialChar \menuseparator
7026 Settings
7027 \end_layout
7028
7029 \end_inset
7030
7031  dialog.
7032 \end_layout
7033
7034 \begin_layout Description
7035 \begin_inset Flex CharStyle:Code
7036 status collapsed
7037
7038 \begin_layout Plain Layout
7039 Counter
7040 \end_layout
7041
7042 \end_inset
7043
7044  This sequence defines a new counter.
7045  See Section
7046 \begin_inset space ~
7047 \end_inset
7048
7049
7050 \begin_inset CommandInset ref
7051 LatexCommand ref
7052 reference "sec:counter"
7053
7054 \end_inset
7055
7056  for details.
7057  Must end with
7058 \begin_inset Quotes eld
7059 \end_inset
7060
7061
7062 \begin_inset Flex CharStyle:Code
7063 status collapsed
7064
7065 \begin_layout Plain Layout
7066 End
7067 \end_layout
7068
7069 \end_inset
7070
7071
7072 \begin_inset Quotes erd
7073 \end_inset
7074
7075 .
7076 \end_layout
7077
7078 \begin_layout Description
7079 \begin_inset Flex CharStyle:Code
7080 status collapsed
7081
7082 \begin_layout Plain Layout
7083 DefaultFont
7084 \end_layout
7085
7086 \end_inset
7087
7088  Sets the default font used to display the document.
7089  See Section
7090 \begin_inset space ~
7091 \end_inset
7092
7093
7094 \begin_inset CommandInset ref
7095 LatexCommand ref
7096 reference "sec:fonts"
7097
7098 \end_inset
7099
7100  for how to declare fonts.
7101  Must end with
7102 \begin_inset Quotes eld
7103 \end_inset
7104
7105
7106 \begin_inset Flex CharStyle:Code
7107 status collapsed
7108
7109 \begin_layout Plain Layout
7110 EndFont
7111 \end_layout
7112
7113 \end_inset
7114
7115
7116 \begin_inset Quotes erd
7117 \end_inset
7118
7119 .
7120 \end_layout
7121
7122 \begin_layout Description
7123 \begin_inset Flex CharStyle:Code
7124 status collapsed
7125
7126 \begin_layout Plain Layout
7127 DefaultModule
7128 \end_layout
7129
7130 \end_inset
7131
7132  [
7133 \begin_inset Flex CharStyle:Code
7134 status collapsed
7135
7136 \begin_layout Plain Layout
7137 string]
7138 \end_layout
7139
7140 \end_inset
7141
7142  Specifies a module to be included by default with this document class,
7143  which should be specified by filename without the
7144 \begin_inset Flex CharStyle:Code
7145 status collapsed
7146
7147 \begin_layout Plain Layout
7148 .module
7149 \end_layout
7150
7151 \end_inset
7152
7153  extension.
7154  The user can still remove the module, but it will be active at the outset.
7155  (This applies only when new files are created, or when this class is chosen
7156  for an existing document.)
7157 \end_layout
7158
7159 \begin_layout Description
7160 \begin_inset Flex CharStyle:Code
7161 status collapsed
7162
7163 \begin_layout Plain Layout
7164 DefaultStyle
7165 \end_layout
7166
7167 \end_inset
7168
7169  [
7170 \begin_inset Flex CharStyle:Code
7171 status collapsed
7172
7173 \begin_layout Plain Layout
7174 string
7175 \end_layout
7176
7177 \end_inset
7178
7179 ] This is the style that will be assigned to new paragraphs, usually
7180 \begin_inset Flex CharStyle:MenuItem
7181 status collapsed
7182
7183 \begin_layout Plain Layout
7184 Standard
7185 \end_layout
7186
7187 \end_inset
7188
7189 .
7190  This will default to the first defined style if not given, but you are
7191  highly encouraged to use this directive.
7192 \end_layout
7193
7194 \begin_layout Description
7195 \begin_inset Flex CharStyle:Code
7196 status collapsed
7197
7198 \begin_layout Plain Layout
7199 ExcludesModule
7200 \end_layout
7201
7202 \end_inset
7203
7204  [
7205 \begin_inset Flex CharStyle:Code
7206 status collapsed
7207
7208 \begin_layout Plain Layout
7209 string
7210 \end_layout
7211
7212 \end_inset
7213
7214 ] Indicates that the module in question—which should be specified by filename
7215  without the
7216 \begin_inset Flex CharStyle:Code
7217 status collapsed
7218
7219 \begin_layout Plain Layout
7220 .module
7221 \end_layout
7222
7223 \end_inset
7224
7225  extension—cannot be used with this document class.
7226  This might be used in a journal-specific layout file to prevent, say, the
7227  use of the
7228 \begin_inset Flex CharStyle:Code
7229 status collapsed
7230
7231 \begin_layout Plain Layout
7232 theorems-sec
7233 \end_layout
7234
7235 \end_inset
7236
7237  module that numbers theorems by section.
7238  This tag may
7239 \emph on
7240 not
7241 \emph default
7242  be used in a module.
7243  Modules have their own way of excluding other modules (see
7244 \begin_inset CommandInset ref
7245 LatexCommand ref
7246 reference "sub:Layout-modules"
7247
7248 \end_inset
7249
7250 ).
7251 \end_layout
7252
7253 \begin_layout Description
7254 \begin_inset Flex CharStyle:Code
7255 status collapsed
7256
7257 \begin_layout Plain Layout
7258 Float
7259 \end_layout
7260
7261 \end_inset
7262
7263  Defines a new float.
7264  See Section
7265 \begin_inset space ~
7266 \end_inset
7267
7268
7269 \begin_inset CommandInset ref
7270 LatexCommand ref
7271 reference "sec:floats"
7272
7273 \end_inset
7274
7275  for details.
7276  Must end with
7277 \begin_inset Quotes eld
7278 \end_inset
7279
7280
7281 \begin_inset Flex CharStyle:Code
7282 status collapsed
7283
7284 \begin_layout Plain Layout
7285 End
7286 \end_layout
7287
7288 \end_inset
7289
7290
7291 \begin_inset Quotes erd
7292 \end_inset
7293
7294 .
7295 \end_layout
7296
7297 \begin_layout Description
7298 \begin_inset Flex CharStyle:Code
7299 status collapsed
7300
7301 \begin_layout Plain Layout
7302 Input
7303 \end_layout
7304
7305 \end_inset
7306
7307  As its name implies, this command allows you to include another layout
7308  definition file within yours to avoid duplicating commands.
7309  Common examples are the standard layout files, for example,
7310 \begin_inset Flex CharStyle:Code
7311 status collapsed
7312
7313 \begin_layout Plain Layout
7314 stdclass.inc
7315 \end_layout
7316
7317 \end_inset
7318
7319 , which contains most of the basic layouts.
7320 \end_layout
7321
7322 \begin_layout Description
7323 \begin_inset Flex CharStyle:Code
7324 status collapsed
7325
7326 \begin_layout Plain Layout
7327 InsetLayout
7328 \end_layout
7329
7330 \end_inset
7331
7332  This section (re-)defines the layout of an inset.
7333  It can be applied to an existing inset of to a new, user-defined inset,
7334  e.
7335 \begin_inset space \thinspace{}
7336 \end_inset
7337
7338 g.
7339 \begin_inset space \space{}
7340 \end_inset
7341
7342 a new character style.
7343  See Section
7344 \begin_inset space ~
7345 \end_inset
7346
7347
7348 \begin_inset CommandInset ref
7349 LatexCommand ref
7350 reference "sec:charstyle"
7351
7352 \end_inset
7353
7354  for more information.
7355  Must end with
7356 \begin_inset Quotes eld
7357 \end_inset
7358
7359
7360 \begin_inset Flex CharStyle:Code
7361 status collapsed
7362
7363 \begin_layout Plain Layout
7364 End
7365 \end_layout
7366
7367 \end_inset
7368
7369
7370 \begin_inset Quotes erd
7371 \end_inset
7372
7373 .
7374 \end_layout
7375
7376 \begin_layout Description
7377 \begin_inset Flex CharStyle:Code
7378 status collapsed
7379
7380 \begin_layout Plain Layout
7381 LeftMargin
7382 \end_layout
7383
7384 \end_inset
7385
7386  A string that indicates the width of the left margin on the screen, for
7387  example,
7388 \begin_inset Quotes eld
7389 \end_inset
7390
7391 MMMMM
7392 \begin_inset Quotes erd
7393 \end_inset
7394
7395 .
7396 \end_layout
7397
7398 \begin_layout Description
7399 \begin_inset Flex CharStyle:Code
7400 status collapsed
7401
7402 \begin_layout Plain Layout
7403 NoFloat
7404 \end_layout
7405
7406 \end_inset
7407
7408  This command deletes an existing float.
7409  This is particularly useful when you want to suppress a float that has
7410  be defined in an input file.
7411 \end_layout
7412
7413 \begin_layout Description
7414 \begin_inset Flex CharStyle:Code
7415 status collapsed
7416
7417 \begin_layout Plain Layout
7418 NoStyle
7419 \end_layout
7420
7421 \end_inset
7422
7423  This command deletes an existing style.
7424  This is particularly useful when you want to suppress a style that has
7425  be defined in an input file.
7426 \end_layout
7427
7428 \begin_layout Description
7429 \begin_inset Flex CharStyle:Code
7430 status collapsed
7431
7432 \begin_layout Plain Layout
7433 OutputType
7434 \end_layout
7435
7436 \end_inset
7437
7438  A string indicating what sort of output documents using this class will
7439  produce.
7440  At present, the options are: `docbook', `latex', and `literate'.
7441 \end_layout
7442
7443 \begin_layout Description
7444 \begin_inset Flex CharStyle:Code
7445 status collapsed
7446
7447 \begin_layout Plain Layout
7448
7449 \series medium
7450 PageStyle
7451 \end_layout
7452
7453 \end_inset
7454
7455  [
7456 \emph on
7457
7458 \begin_inset Flex CharStyle:Code
7459 status collapsed
7460
7461 \begin_layout Plain Layout
7462
7463 \emph on
7464 plain
7465 \end_layout
7466
7467 \end_inset
7468
7469
7470 \emph default
7471 ,
7472 \begin_inset Flex CharStyle:Code
7473 status collapsed
7474
7475 \begin_layout Plain Layout
7476 empty
7477 \end_layout
7478
7479 \end_inset
7480
7481 ,
7482 \begin_inset Flex CharStyle:Code
7483 status collapsed
7484
7485 \begin_layout Plain Layout
7486 headings
7487 \end_layout
7488
7489 \end_inset
7490
7491 ] The class default pagestyle.
7492  Can be changed in the
7493 \begin_inset Flex CharStyle:MenuItem
7494 status collapsed
7495
7496 \begin_layout Plain Layout
7497 Document\SpecialChar \menuseparator
7498 Settings
7499 \end_layout
7500
7501 \end_inset
7502
7503  dialog.
7504 \end_layout
7505
7506 \begin_layout Description
7507 \begin_inset Flex CharStyle:Code
7508 status collapsed
7509
7510 \begin_layout Plain Layout
7511 Preamble
7512 \end_layout
7513
7514 \end_inset
7515
7516  Sets the preamble for the LaTeX document.
7517  Note that this will completely override any prior
7518 \begin_inset Flex CharStyle:Code
7519 status collapsed
7520
7521 \begin_layout Plain Layout
7522 Preamble
7523 \end_layout
7524
7525 \end_inset
7526
7527  or
7528 \begin_inset Flex CharStyle:Code
7529 status collapsed
7530
7531 \begin_layout Plain Layout
7532 AddToPreamble
7533 \end_layout
7534
7535 \end_inset
7536
7537  declarations.
7538  Must end with
7539 \begin_inset Quotes eld
7540 \end_inset
7541
7542
7543 \begin_inset Flex CharStyle:Code
7544 status collapsed
7545
7546 \begin_layout Plain Layout
7547 EndPreamble
7548 \end_layout
7549
7550 \end_inset
7551
7552
7553 \begin_inset Quotes erd
7554 \end_inset
7555
7556 .
7557 \end_layout
7558
7559 \begin_layout Description
7560 \begin_inset Flex CharStyle:Code
7561 status collapsed
7562
7563 \begin_layout Plain Layout
7564 Provides
7565 \end_layout
7566
7567 \end_inset
7568
7569  [
7570 \begin_inset Flex CharStyle:Code
7571 status collapsed
7572
7573 \begin_layout Plain Layout
7574 string
7575 \end_layout
7576
7577 \end_inset
7578
7579 ] [
7580 \begin_inset Flex CharStyle:Code
7581 status collapsed
7582
7583 \begin_layout Plain Layout
7584
7585 \emph on
7586 0
7587 \end_layout
7588
7589 \end_inset
7590
7591 ,
7592 \begin_inset Flex CharStyle:Code
7593 status collapsed
7594
7595 \begin_layout Plain Layout
7596 1
7597 \end_layout
7598
7599 \end_inset
7600
7601 ] Whether the class already provides the feature
7602 \begin_inset Flex CharStyle:Code
7603 status collapsed
7604
7605 \begin_layout Plain Layout
7606 string
7607 \end_layout
7608
7609 \end_inset
7610
7611 .
7612  A feature is in general the name of a package (
7613 \begin_inset Flex CharStyle:Code
7614 status collapsed
7615
7616 \begin_layout Plain Layout
7617 amsmath
7618 \end_layout
7619
7620 \end_inset
7621
7622 ,
7623 \begin_inset Flex CharStyle:Code
7624 status collapsed
7625
7626 \begin_layout Plain Layout
7627 makeidx
7628 \end_layout
7629
7630 \end_inset
7631
7632 , \SpecialChar \ldots{}
7633 ) or a macro (
7634 \begin_inset Flex CharStyle:Code
7635 status collapsed
7636
7637 \begin_layout Plain Layout
7638 url
7639 \end_layout
7640
7641 \end_inset
7642
7643 ,
7644 \begin_inset Flex CharStyle:Code
7645 status collapsed
7646
7647 \begin_layout Plain Layout
7648 boldsymbol
7649 \end_layout
7650
7651 \end_inset
7652
7653 ,\SpecialChar \ldots{}
7654 ); the complete list of supported features is unfortunately not documented
7655  outside the LyX source code—but see
7656 \begin_inset Flex CharStyle:Code
7657 status collapsed
7658
7659 \begin_layout Plain Layout
7660 LaTeXFeatures.cpp
7661 \end_layout
7662
7663 \end_inset
7664
7665  if you're interested.
7666
7667 \begin_inset Flex CharStyle:MenuItem
7668 status collapsed
7669
7670 \begin_layout Plain Layout
7671 Help\SpecialChar \menuseparator
7672 LaTeX Configuration
7673 \end_layout
7674
7675 \end_inset
7676
7677  also gives an overview of the supported packages.
7678 \end_layout
7679
7680 \begin_layout Description
7681 \begin_inset Flex CharStyle:Code
7682 status collapsed
7683
7684 \begin_layout Plain Layout
7685 ProvidesModule
7686 \end_layout
7687
7688 \end_inset
7689
7690  [
7691 \begin_inset Flex CharStyle:Code
7692 status collapsed
7693
7694 \begin_layout Plain Layout
7695 string
7696 \end_layout
7697
7698 \end_inset
7699
7700 ] Indicates that this layout provides the functionality of the module mentioned,
7701  which should be specified by the filename without the
7702 \begin_inset Flex CharStyle:Code
7703 status collapsed
7704
7705 \begin_layout Plain Layout
7706 .module
7707 \end_layout
7708
7709 \end_inset
7710
7711  extension.
7712  This will typically be used if the layout includes the module directly,
7713  rather than using the
7714 \begin_inset Flex CharStyle:Code
7715 status collapsed
7716
7717 \begin_layout Plain Layout
7718 DefaultModule
7719 \end_layout
7720
7721 \end_inset
7722
7723  tag to indicate that it ought to be used.
7724  It could be used in a module that provided an alternate implementation
7725  of the same functionality.
7726 \end_layout
7727
7728 \begin_layout Description
7729 \begin_inset Flex CharStyle:Code
7730 status collapsed
7731
7732 \begin_layout Plain Layout
7733 Requires
7734 \end_layout
7735
7736 \end_inset
7737
7738  [
7739 \begin_inset Flex CharStyle:Code
7740 status collapsed
7741
7742 \begin_layout Plain Layout
7743 string
7744 \end_layout
7745
7746 \end_inset
7747
7748 ] Whether the class requires the feature
7749 \begin_inset Flex CharStyle:Code
7750 status collapsed
7751
7752 \begin_layout Plain Layout
7753 string
7754 \end_layout
7755
7756 \end_inset
7757
7758 .
7759  Multiple features must be separated by commas.
7760  Note that you can only request supported features.
7761 \end_layout
7762
7763 \begin_layout Description
7764 \begin_inset Flex CharStyle:Code
7765 status collapsed
7766
7767 \begin_layout Plain Layout
7768 RightMargin
7769 \end_layout
7770
7771 \end_inset
7772
7773  A string that indicates the width of the right margin on the screen, for
7774  example,
7775 \begin_inset Quotes eld
7776 \end_inset
7777
7778 MMMMM
7779 \begin_inset Quotes erd
7780 \end_inset
7781
7782 .
7783 \end_layout
7784
7785 \begin_layout Description
7786 \begin_inset Flex CharStyle:Code
7787 status collapsed
7788
7789 \begin_layout Plain Layout
7790 SecNumDepth
7791 \end_layout
7792
7793 \end_inset
7794
7795  Sets which divisions get numbered.
7796  Corresponds to the
7797 \begin_inset Flex CharStyle:Code
7798 status collapsed
7799
7800 \begin_layout Plain Layout
7801 secnumdepth
7802 \end_layout
7803
7804 \end_inset
7805
7806  counter in LaTeX.
7807 \end_layout
7808
7809 \begin_layout Description
7810 \begin_inset Flex CharStyle:Code
7811 status collapsed
7812
7813 \begin_layout Plain Layout
7814 Sides
7815 \end_layout
7816
7817 \end_inset
7818
7819  [
7820 \emph on
7821
7822 \begin_inset Flex CharStyle:Code
7823 status collapsed
7824
7825 \begin_layout Plain Layout
7826
7827 \emph on
7828 1
7829 \end_layout
7830
7831 \end_inset
7832
7833
7834 \emph default
7835 ,
7836 \begin_inset Flex CharStyle:Code
7837 status collapsed
7838
7839 \begin_layout Plain Layout
7840 2
7841 \end_layout
7842
7843 \end_inset
7844
7845 ] Whether the class-default should be printing on one or both sides of the
7846  paper.
7847  Can be changed in the
7848 \begin_inset Flex CharStyle:MenuItem
7849 status collapsed
7850
7851 \begin_layout Plain Layout
7852 Document\SpecialChar \menuseparator
7853 Settings
7854 \end_layout
7855
7856 \end_inset
7857
7858  dialog.
7859 \end_layout
7860
7861 \begin_layout Description
7862 \begin_inset Flex CharStyle:Code
7863 status collapsed
7864
7865 \begin_layout Plain Layout
7866 Style
7867 \end_layout
7868
7869 \end_inset
7870
7871  This sequence defines a new paragraph style.
7872  If the style already exists, it will redefine some of its parameters instead.
7873  See Section
7874 \begin_inset space ~
7875 \end_inset
7876
7877
7878 \begin_inset CommandInset ref
7879 LatexCommand ref
7880 reference "sec:style"
7881
7882 \end_inset
7883
7884  for details.
7885  Must end with
7886 \begin_inset Quotes eld
7887 \end_inset
7888
7889
7890 \begin_inset Flex CharStyle:Code
7891 status collapsed
7892
7893 \begin_layout Plain Layout
7894 End
7895 \end_layout
7896
7897 \end_inset
7898
7899
7900 \begin_inset Quotes erd
7901 \end_inset
7902
7903 .
7904 \end_layout
7905
7906 \begin_layout Description
7907 \begin_inset Flex CharStyle:Code
7908 status collapsed
7909
7910 \begin_layout Plain Layout
7911 TitleLatexName
7912 \end_layout
7913
7914 \end_inset
7915
7916  [
7917 \begin_inset Flex CharStyle:Code
7918 status collapsed
7919
7920 \begin_layout Plain Layout
7921 string="maketitle"
7922 \end_layout
7923
7924 \end_inset
7925
7926 ] The name of the command or environment to be used with
7927 \begin_inset Flex CharStyle:Code
7928 status collapsed
7929
7930 \begin_layout Plain Layout
7931 TitleLatexType
7932 \end_layout
7933
7934 \end_inset
7935
7936 .
7937 \end_layout
7938
7939 \begin_layout Description
7940 \begin_inset Flex CharStyle:Code
7941 status collapsed
7942
7943 \begin_layout Plain Layout
7944 TitleLatexType
7945 \end_layout
7946
7947 \end_inset
7948
7949  [
7950 \begin_inset Flex CharStyle:Code
7951 status collapsed
7952
7953 \begin_layout Plain Layout
7954
7955 \emph on
7956 CommandAfter
7957 \end_layout
7958
7959 \end_inset
7960
7961 ,
7962 \begin_inset Flex CharStyle:Code
7963 status collapsed
7964
7965 \begin_layout Plain Layout
7966 Environment
7967 \end_layout
7968
7969 \end_inset
7970
7971 ] Indicates what kind of markup is used to define the title of a document.
7972
7973 \begin_inset Flex CharStyle:Code
7974 status collapsed
7975
7976 \begin_layout Plain Layout
7977 CommandAfter
7978 \end_layout
7979
7980 \end_inset
7981
7982  means that the macro with name
7983 \begin_inset Flex CharStyle:Code
7984 status collapsed
7985
7986 \begin_layout Plain Layout
7987 TitleLatexName
7988 \end_layout
7989
7990 \end_inset
7991
7992  will be inserted after the last layout which has
7993 \begin_inset Quotes eld
7994 \end_inset
7995
7996
7997 \begin_inset Flex CharStyle:Code
7998 status collapsed
7999
8000 \begin_layout Plain Layout
8001 InTitle 1
8002 \end_layout
8003
8004 \end_inset
8005
8006
8007 \begin_inset Quotes erd
8008 \end_inset
8009
8010 .
8011
8012 \begin_inset Flex CharStyle:Code
8013 status collapsed
8014
8015 \begin_layout Plain Layout
8016 Environment
8017 \end_layout
8018
8019 \end_inset
8020
8021  corresponds to the case where the block of paragraphs which have
8022 \begin_inset Quotes eld
8023 \end_inset
8024
8025
8026 \begin_inset Flex CharStyle:Code
8027 status collapsed
8028
8029 \begin_layout Plain Layout
8030 InTitle 1
8031 \end_layout
8032
8033 \end_inset
8034
8035
8036 \begin_inset Quotes erd
8037 \end_inset
8038
8039  should be enclosed into the
8040 \begin_inset Flex CharStyle:Code
8041 status collapsed
8042
8043 \begin_layout Plain Layout
8044 TitleLatexName
8045 \end_layout
8046
8047 \end_inset
8048
8049  environment.
8050 \end_layout
8051
8052 \begin_layout Description
8053 \begin_inset Flex CharStyle:Code
8054 status collapsed
8055
8056 \begin_layout Plain Layout
8057 TocDepth
8058 \end_layout
8059
8060 \end_inset
8061
8062  Sets which divisions are included in the table of contents.
8063  Corresponds to the
8064 \begin_inset Flex CharStyle:Code
8065 status collapsed
8066
8067 \begin_layout Plain Layout
8068 tocdepth
8069 \end_layout
8070
8071 \end_inset
8072
8073  counter in LaTeX.
8074 \end_layout
8075
8076 \begin_layout Subsection
8077 \begin_inset Flex CharStyle:Code
8078 status collapsed
8079
8080 \begin_layout Plain Layout
8081 ClassOptions
8082 \end_layout
8083
8084 \end_inset
8085
8086  section
8087 \end_layout
8088
8089 \begin_layout Standard
8090 \begin_inset CommandInset label
8091 LatexCommand label
8092 name "sec:classoptions"
8093
8094 \end_inset
8095
8096 The
8097 \begin_inset Flex CharStyle:Code
8098 status collapsed
8099
8100 \begin_layout Plain Layout
8101 ClassOptions
8102 \end_layout
8103
8104 \end_inset
8105
8106  section can contain the following entries:
8107 \end_layout
8108
8109 \begin_layout Description
8110 \begin_inset Flex CharStyle:Code
8111 status collapsed
8112
8113 \begin_layout Plain Layout
8114 FontSize
8115 \end_layout
8116
8117 \end_inset
8118
8119  [
8120 \begin_inset Flex CharStyle:Code
8121 status collapsed
8122
8123 \begin_layout Plain Layout
8124 string="10|11|12"
8125 \end_layout
8126
8127 \end_inset
8128
8129 ] The list of available font sizes for the document's main font, separated
8130  by
8131 \begin_inset Quotes eld
8132 \end_inset
8133
8134
8135 \begin_inset Flex CharStyle:Code
8136 status collapsed
8137
8138 \begin_layout Plain Layout
8139 |
8140 \end_layout
8141
8142 \end_inset
8143
8144
8145 \begin_inset Quotes erd
8146 \end_inset
8147
8148 .
8149 \end_layout
8150
8151 \begin_layout Description
8152 \begin_inset Flex CharStyle:Code
8153 status collapsed
8154
8155 \begin_layout Plain Layout
8156 Header
8157 \end_layout
8158
8159 \end_inset
8160
8161  Used to set the DTD line with XML-based output classes.
8162  E.
8163 \begin_inset space \thinspace{}
8164 \end_inset
8165
8166 g.: PUBLIC
8167 \begin_inset Quotes eld
8168 \end_inset
8169
8170 -//OASIS//DTD DocBook V4.2//EN
8171 \begin_inset Quotes erd
8172 \end_inset
8173
8174 .
8175 \end_layout
8176
8177 \begin_layout Description
8178 \begin_inset Flex CharStyle:Code
8179 status collapsed
8180
8181 \begin_layout Plain Layout
8182 PageStyle
8183 \end_layout
8184
8185 \end_inset
8186
8187  [
8188 \begin_inset Flex CharStyle:Code
8189 status collapsed
8190
8191 \begin_layout Plain Layout
8192 string="empty|plain|headings|fancy"
8193 \end_layout
8194
8195 \end_inset
8196
8197 ] The list of available page styles, separated by
8198 \begin_inset Quotes eld
8199 \end_inset
8200
8201
8202 \begin_inset Flex CharStyle:Code
8203 status collapsed
8204
8205 \begin_layout Plain Layout
8206 |
8207 \end_layout
8208
8209 \end_inset
8210
8211
8212 \begin_inset Quotes erd
8213 \end_inset
8214
8215 .
8216 \end_layout
8217
8218 \begin_layout Description
8219 \begin_inset Flex CharStyle:Code
8220 status collapsed
8221
8222 \begin_layout Plain Layout
8223 Other
8224 \end_layout
8225
8226 \end_inset
8227
8228  [
8229 \begin_inset Flex CharStyle:Code
8230 status collapsed
8231
8232 \begin_layout Plain Layout
8233 string=""
8234 \end_layout
8235
8236 \end_inset
8237
8238 ] Some document class options, separated by a comma, that will be added
8239  to the optional part of the
8240 \begin_inset Flex CharStyle:Code
8241 status collapsed
8242
8243 \begin_layout Plain Layout
8244
8245 \backslash
8246 documentclass
8247 \end_layout
8248
8249 \end_inset
8250
8251  command.
8252 \end_layout
8253
8254 \begin_layout Standard
8255 The
8256 \begin_inset Flex CharStyle:Code
8257 status collapsed
8258
8259 \begin_layout Plain Layout
8260 ClassOptions
8261 \end_layout
8262
8263 \end_inset
8264
8265  section must end with
8266 \begin_inset Quotes eld
8267 \end_inset
8268
8269
8270 \begin_inset Flex CharStyle:Code
8271 status collapsed
8272
8273 \begin_layout Plain Layout
8274 End
8275 \end_layout
8276
8277 \end_inset
8278
8279
8280 \begin_inset Quotes erd
8281 \end_inset
8282
8283 .
8284 \end_layout
8285
8286 \begin_layout Subsection
8287 Paragraph Styles
8288 \end_layout
8289
8290 \begin_layout Standard
8291 \begin_inset CommandInset label
8292 LatexCommand label
8293 name "sec:style"
8294
8295 \end_inset
8296
8297 A paragraph style description looks like this:
8298 \begin_inset Foot
8299 status collapsed
8300
8301 \begin_layout Plain Layout
8302 Note that this will either define a new layout or modify an existing one.
8303 \end_layout
8304
8305 \end_inset
8306
8307
8308 \end_layout
8309
8310 \begin_layout LyX-Code
8311 Style
8312 \family roman
8313 \emph on
8314 name
8315 \end_layout
8316
8317 \begin_layout LyX-Code
8318  ...
8319 \end_layout
8320
8321 \begin_layout LyX-Code
8322 End
8323 \end_layout
8324
8325 \begin_layout Standard
8326 where the following commands are allowed:
8327 \end_layout
8328
8329 \begin_layout Description
8330 \begin_inset Flex CharStyle:Code
8331 status collapsed
8332
8333 \begin_layout Plain Layout
8334 Align
8335 \end_layout
8336
8337 \end_inset
8338
8339  [
8340 \begin_inset Flex CharStyle:Code
8341 status collapsed
8342
8343 \begin_layout Plain Layout
8344
8345 \emph on
8346 block
8347 \emph default
8348 , left, right, center
8349 \end_layout
8350
8351 \end_inset
8352
8353 ] Paragraph alignment.
8354 \end_layout
8355
8356 \begin_layout Description
8357 \begin_inset Flex CharStyle:Code
8358 status collapsed
8359
8360 \begin_layout Plain Layout
8361 AlignPossible
8362 \end_layout
8363
8364 \end_inset
8365
8366  [
8367 \begin_inset Flex CharStyle:Code
8368 status collapsed
8369
8370 \begin_layout Plain Layout
8371
8372 \emph on
8373 block
8374 \emph default
8375 , left, right, center
8376 \end_layout
8377
8378 \end_inset
8379
8380 ] A comma separated list of permitted alignments.
8381  (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8382  sense.
8383  For example a right-aligned or centered enumeration isn't possible.)
8384 \end_layout
8385
8386 \begin_layout Description
8387 \begin_inset Flex CharStyle:Code
8388 status collapsed
8389
8390 \begin_layout Plain Layout
8391 BottomSep
8392 \end_layout
8393
8394 \end_inset
8395
8396  [
8397 \begin_inset Flex CharStyle:Code
8398 status collapsed
8399
8400 \begin_layout Plain Layout
8401 float=0
8402 \end_layout
8403
8404 \end_inset
8405
8406 ]
8407 \begin_inset Foot
8408 status collapsed
8409
8410 \begin_layout Plain Layout
8411 Note that a `float' here is a real number, such as: 1.5.
8412 \end_layout
8413
8414 \end_inset
8415
8416  The vertical space with which the last of a chain of paragraphs with this
8417  layout is separated from the following paragraph.
8418  If the next paragraph has another layout, the separations are not simply
8419  added, but the maximum is taken.
8420 \end_layout
8421
8422 \begin_layout Description
8423 \begin_inset Flex CharStyle:Code
8424 status collapsed
8425
8426 \begin_layout Plain Layout
8427 Category
8428 \end_layout
8429
8430 \end_inset
8431
8432
8433 \begin_inset Flex CharStyle:Code
8434 status collapsed
8435
8436 \begin_layout Plain Layout
8437 [string]
8438 \end_layout
8439
8440 \end_inset
8441
8442  The category for this style.
8443  This is used to group related styles in the Layout combobox on the toolbar.
8444  Any string can be used, but you may want to use existing categories with
8445  your own styles.
8446
8447 \end_layout
8448
8449 \begin_layout Description
8450 \begin_inset Flex CharStyle:Code
8451 status collapsed
8452
8453 \begin_layout Plain Layout
8454 CommandDepth
8455 \end_layout
8456
8457 \end_inset
8458
8459  Depth of XML command.
8460  Used only with XML-type formats.
8461 \end_layout
8462
8463 \begin_layout Description
8464 \begin_inset Flex CharStyle:Code
8465 status collapsed
8466
8467 \begin_layout Plain Layout
8468 CopyStyle
8469 \end_layout
8470
8471 \end_inset
8472
8473
8474 \begin_inset CommandInset label
8475 LatexCommand label
8476 name "des:CopyStyle"
8477
8478 \end_inset
8479
8480
8481 \begin_inset Flex CharStyle:Code
8482 status collapsed
8483
8484 \begin_layout Plain Layout
8485 [string]
8486 \end_layout
8487
8488 \end_inset
8489
8490  Copies all the features of an existing style into the current one.
8491
8492 \end_layout
8493
8494 \begin_layout Description
8495 \begin_inset Flex CharStyle:Code
8496 status collapsed
8497
8498 \begin_layout Plain Layout
8499 DependsOn
8500 \end_layout
8501
8502 \end_inset
8503
8504  The name of a style whose preamble should be output
8505 \emph on
8506 before
8507 \emph default
8508  this one.
8509  This allows to ensure some ordering of the preamble snippets when macros
8510  definitions depend on one another.
8511 \begin_inset Foot
8512 status collapsed
8513
8514 \begin_layout Plain Layout
8515 Note that, besides that functionality, there is no way to ensure any ordering
8516  of preambles.
8517  The ordering that you see in a given version of LyX may change without
8518  warning in later versions.
8519 \end_layout
8520
8521 \end_inset
8522
8523
8524 \end_layout
8525
8526 \begin_layout Description
8527 \begin_inset Flex CharStyle:Code
8528 status collapsed
8529
8530 \begin_layout Plain Layout
8531 EndLabeltype
8532 \end_layout
8533
8534 \end_inset
8535
8536  [
8537 \begin_inset Flex CharStyle:Code
8538 status collapsed
8539
8540 \begin_layout Plain Layout
8541
8542 \emph on
8543 No_Label
8544 \emph default
8545 , Box, Filled_Box, Static
8546 \end_layout
8547
8548 \end_inset
8549
8550 ] The type of label that stands at the end of the paragraph (or sequence
8551  of paragraphs if
8552 \begin_inset Flex CharStyle:Code
8553 status collapsed
8554
8555 \begin_layout Plain Layout
8556 LatexType
8557 \end_layout
8558
8559 \end_inset
8560
8561  is
8562 \begin_inset Flex CharStyle:Code
8563 status collapsed
8564
8565 \begin_layout Plain Layout
8566 Environment
8567 \end_layout
8568
8569 \end_inset
8570
8571 ,
8572 \begin_inset Flex CharStyle:Code
8573 status collapsed
8574
8575 \begin_layout Plain Layout
8576 Item_Environment
8577 \end_layout
8578
8579 \end_inset
8580
8581  or
8582 \begin_inset Flex CharStyle:Code
8583 status collapsed
8584
8585 \begin_layout Plain Layout
8586 List_Environment
8587 \end_layout
8588
8589 \end_inset
8590
8591 ).
8592
8593 \begin_inset Flex CharStyle:Code
8594 status collapsed
8595
8596 \begin_layout Plain Layout
8597 No_Label
8598 \end_layout
8599
8600 \end_inset
8601
8602  means
8603 \begin_inset Quotes eld
8604 \end_inset
8605
8606 nothing
8607 \begin_inset Quotes erd
8608 \end_inset
8609
8610 ,
8611 \begin_inset Flex CharStyle:Code
8612 status collapsed
8613
8614 \begin_layout Plain Layout
8615 Box
8616 \end_layout
8617
8618 \end_inset
8619
8620  (resp.
8621 \begin_inset Flex CharStyle:Code
8622 status collapsed
8623
8624 \begin_layout Plain Layout
8625 \begin_inset space ~
8626 \end_inset
8627
8628 Filled_Box
8629 \end_layout
8630
8631 \end_inset
8632
8633 ) is a white (resp.
8634 \begin_inset space ~
8635 \end_inset
8636
8637 black) square suitable for end of proof markers,
8638 \begin_inset Flex CharStyle:Code
8639 status collapsed
8640
8641 \begin_layout Plain Layout
8642 Static
8643 \end_layout
8644
8645 \end_inset
8646
8647  is an explicit text string.
8648 \end_layout
8649
8650 \begin_layout Description
8651 \begin_inset Flex CharStyle:Code
8652 status collapsed
8653
8654 \begin_layout Plain Layout
8655 EndLabelString
8656 \end_layout
8657
8658 \end_inset
8659
8660  [
8661 \begin_inset Flex CharStyle:Code
8662 status collapsed
8663
8664 \begin_layout Plain Layout
8665 string=""
8666 \end_layout
8667
8668 \end_inset
8669
8670 ] The string used for a label with a
8671 \begin_inset Flex CharStyle:Code
8672 status collapsed
8673
8674 \begin_layout Plain Layout
8675 Static
8676 \end_layout
8677
8678 \end_inset
8679
8680
8681 \begin_inset Flex CharStyle:Code
8682 status collapsed
8683
8684 \begin_layout Plain Layout
8685 EndLabelType
8686 \end_layout
8687
8688 \end_inset
8689
8690 .
8691
8692 \end_layout
8693
8694 \begin_layout Description
8695 \begin_inset Flex CharStyle:Code
8696 status collapsed
8697
8698 \begin_layout Plain Layout
8699 Fill_Bottom
8700 \end_layout
8701
8702 \end_inset
8703
8704  [
8705 \begin_inset Flex CharStyle:Code
8706 status collapsed
8707
8708 \begin_layout Plain Layout
8709
8710 \emph on
8711 0
8712 \emph default
8713 ,1
8714 \end_layout
8715
8716 \end_inset
8717
8718 ] Similar to
8719 \begin_inset Flex CharStyle:Code
8720 status collapsed
8721
8722 \begin_layout Plain Layout
8723 Fill_Top
8724 \end_layout
8725
8726 \end_inset
8727
8728 .
8729 \end_layout
8730
8731 \begin_layout Description
8732 \begin_inset Flex CharStyle:Code
8733 status collapsed
8734
8735 \begin_layout Plain Layout
8736 Fill_Top
8737 \end_layout
8738
8739 \end_inset
8740
8741  [
8742 \begin_inset Flex CharStyle:Code
8743 status collapsed
8744
8745 \begin_layout Plain Layout
8746
8747 \emph on
8748 0
8749 \emph default
8750 ,1
8751 \end_layout
8752
8753 \end_inset
8754
8755 ] With this parameter the
8756 \begin_inset Flex CharStyle:MenuItem
8757 status collapsed
8758
8759 \begin_layout Plain Layout
8760 Fill
8761 \end_layout
8762
8763 \end_inset
8764
8765  value of the
8766 \begin_inset Quotes eld
8767 \end_inset
8768
8769 Vertical space above
8770 \begin_inset Quotes erd
8771 \end_inset
8772
8773  list of the
8774 \begin_inset Flex CharStyle:MenuItem
8775 status collapsed
8776
8777 \begin_layout Plain Layout
8778 Edit\SpecialChar \menuseparator
8779 Paragraph
8780 \begin_inset space ~
8781 \end_inset
8782
8783 Settings
8784 \end_layout
8785
8786 \end_inset
8787
8788  dialog can be set when initializing a paragraph with this style.
8789 \begin_inset Foot
8790 status collapsed
8791
8792 \begin_layout Plain Layout
8793
8794 \emph on
8795 Note from Jean-Marc:
8796 \emph default
8797  I'm not sure that this setting has much use, and it should probably be
8798  removed in later versions.
8799 \end_layout
8800
8801 \end_inset
8802
8803
8804 \end_layout
8805
8806 \begin_layout Description
8807 \begin_inset Flex CharStyle:Code
8808 status collapsed
8809
8810 \begin_layout Plain Layout
8811 Font
8812 \end_layout
8813
8814 \end_inset
8815
8816  The font used for both the text body
8817 \emph on
8818 and
8819 \emph default
8820  the label.
8821  See section
8822 \begin_inset space ~
8823 \end_inset
8824
8825
8826 \begin_inset CommandInset ref
8827 LatexCommand ref
8828 reference "sec:fonts"
8829
8830 \end_inset
8831
8832 .
8833  Note that defining this font automatically defines the
8834 \begin_inset Flex CharStyle:Code
8835 status collapsed
8836
8837 \begin_layout Plain Layout
8838 LabelFont
8839 \end_layout
8840
8841 \end_inset
8842
8843  to the same value.
8844  So you should define this one first if you also want to define
8845 \begin_inset Flex CharStyle:Code
8846 status collapsed
8847
8848 \begin_layout Plain Layout
8849 LabelFont
8850 \end_layout
8851
8852 \end_inset
8853
8854 .
8855 \end_layout
8856
8857 \begin_layout Description
8858 \begin_inset Flex CharStyle:Code
8859 status collapsed
8860
8861 \begin_layout Plain Layout
8862 FreeSpacing
8863 \end_layout
8864
8865 \end_inset
8866
8867
8868 \begin_inset CommandInset label
8869 LatexCommand label
8870 name "des:FreeSpacing"
8871
8872 \end_inset
8873
8874 [
8875 \emph on
8876
8877 \begin_inset Flex CharStyle:Code
8878 status collapsed
8879
8880 \begin_layout Plain Layout
8881
8882 \emph on
8883 0
8884 \end_layout
8885
8886 \end_inset
8887
8888
8889 \emph default
8890 ,
8891 \begin_inset Flex CharStyle:Code
8892 status collapsed
8893
8894 \begin_layout Plain Layout
8895 1
8896 \end_layout
8897
8898 \end_inset
8899
8900 ] Usually LyX doesn't allow you to insert more than one space between words,
8901  since a space is considered as the separation between two words, not a
8902  character or symbol of its own.
8903  This is a very fine thing but sometimes annoying, for example, when typing
8904  program code or plain LaTeX code.
8905  For this reason,
8906 \begin_inset Flex CharStyle:Code
8907 status collapsed
8908
8909 \begin_layout Plain Layout
8910 FreeSpacing
8911 \end_layout
8912
8913 \end_inset
8914
8915  can be enabled.
8916  Note that LyX will create protected blanks for the additional blanks when
8917  in another mode than LaTeX-mode.
8918 \end_layout
8919
8920 \begin_layout Description
8921 \begin_inset Flex CharStyle:Code
8922 status collapsed
8923
8924 \begin_layout Plain Layout
8925
8926 \change_inserted 0 1234613251
8927 Babel
8928 \change_deleted 0 1234611266
8929 I18N
8930 \change_unchanged
8931 Preamble
8932 \end_layout
8933
8934 \end_inset
8935
8936  Language dependent information to be included in the LaTeX preamble when
8937  this style is used.
8938  Note that this will completely override any prior
8939 \begin_inset Flex CharStyle:Code
8940 status collapsed
8941
8942 \begin_layout Plain Layout
8943
8944 \change_inserted 0 1234613436
8945 Babel
8946 \change_deleted 0 1234611275
8947 I18N
8948 \change_unchanged
8949 Preamble
8950 \end_layout
8951
8952 \end_inset
8953
8954  declarations.
8955  Must end with
8956 \begin_inset Quotes eld
8957 \end_inset
8958
8959
8960 \begin_inset Flex CharStyle:Code
8961 status collapsed
8962
8963 \begin_layout Plain Layout
8964 End
8965 \change_deleted 0 1234611280
8966 I18N
8967 \change_inserted 0 1234613262
8968 Babel
8969 \change_unchanged
8970 Preamble
8971 \end_layout
8972
8973 \end_inset
8974
8975
8976 \begin_inset Quotes erd
8977 \end_inset
8978
8979 .
8980  The contents of this tag will occur once in the LaTeX preamble for each
8981  language used by the document.
8982  Each time, the following substitutions are made:
8983 \end_layout
8984
8985 \begin_deeper
8986 \begin_layout Itemize
8987 \begin_inset Flex CharStyle:Code
8988 status collapsed
8989
8990 \begin_layout Plain Layout
8991 $$lang
8992 \end_layout
8993
8994 \end_inset
8995
8996  is replaced by the language name (as used by the babel package).
8997 \end_layout
8998
8999 \begin_layout Itemize
9000 The
9001 \begin_inset Quotes eld
9002 \end_inset
9003
9004 Function
9005 \begin_inset Quotes erd
9006 \end_inset
9007
9008
9009 \begin_inset Flex CharStyle:Code
9010 status collapsed
9011
9012 \begin_layout Plain Layout
9013 _()
9014 \end_layout
9015
9016 \end_inset
9017
9018  replaces its argument by the translation of the argument to the current
9019  language.
9020 \change_inserted 0 1234611470
9021
9022 \end_layout
9023
9024 \begin_layout Standard
9025
9026 \change_inserted 0 1234615134
9027 This preamble snippet will only be used if the document contains more than
9028  one language and the babel package is used.
9029 \change_unchanged
9030
9031 \end_layout
9032
9033 \end_deeper
9034 \begin_layout Description
9035
9036 \change_inserted 0 1234614203
9037 \begin_inset Flex CharStyle:Code
9038 status collapsed
9039
9040 \begin_layout Plain Layout
9041
9042 \change_inserted 0 1234614202
9043 LangPreamble
9044 \end_layout
9045
9046 \end_inset
9047
9048  Like
9049 \begin_inset Flex CharStyle:Code
9050 status collapsed
9051
9052 \begin_layout Plain Layout
9053
9054 \change_inserted 0 1234614202
9055 BabelPreamble
9056 \end_layout
9057
9058 \end_inset
9059
9060 , but this preamble snippet occurs independently from the babel package,
9061  and only for the document language.
9062  Must end with
9063 \begin_inset Quotes eld
9064 \end_inset
9065
9066
9067 \begin_inset Flex CharStyle:Code
9068 status collapsed
9069
9070 \begin_layout Plain Layout
9071
9072 \change_inserted 0 1234614202
9073 EndLangPreamble
9074 \end_layout
9075
9076 \end_inset
9077
9078
9079 \begin_inset Quotes erd
9080 \end_inset
9081
9082 .
9083 \end_layout
9084
9085 \begin_deeper
9086 \begin_layout Standard
9087 If the style defines text that appears in the typeset document, it may use
9088
9089 \begin_inset Flex CharStyle:Code
9090 status collapsed
9091
9092 \begin_layout Plain Layout
9093
9094 \change_inserted 0 1234611302
9095 Lang
9096 \change_deleted 0 1234611306
9097 I18N
9098 \change_unchanged
9099 Preamble
9100 \end_layout
9101
9102 \end_inset
9103
9104
9105 \change_inserted 0 1234611823
9106  and
9107 \change_unchanged
9108
9109 \change_inserted 0 1234611832
9110
9111 \begin_inset Flex CharStyle:Code
9112 status collapsed
9113
9114 \begin_layout Plain Layout
9115
9116 \change_inserted 0 1234611838
9117 BabelPreamble
9118 \end_layout
9119
9120 \end_inset
9121
9122
9123 \change_unchanged
9124 to support non-english and even multilanguage documents correctly.
9125  The following excerpt (from the
9126 \begin_inset Flex CharStyle:Code
9127 status collapsed
9128
9129 \begin_layout Plain Layout
9130 theorems-ams.inc
9131 \end_layout
9132
9133 \end_inset
9134
9135  file) shows how this works:
9136 \end_layout
9137
9138 \begin_layout LyX-Code
9139 Preamble
9140 \end_layout
9141
9142 \begin_layout LyX-Code
9143
9144 \change_deleted 0 1234612061
9145
9146 \backslash
9147 providecommand{
9148 \backslash
9149 claimname}{Claim}
9150 \end_layout
9151
9152 \begin_layout LyX-Code
9153
9154 \backslash
9155 theoremstyle{remark}
9156 \end_layout
9157
9158 \begin_layout LyX-Code
9159
9160 \backslash
9161 newtheorem{claim}[thm]{
9162 \backslash
9163 protect
9164 \backslash
9165 claimname}
9166 \end_layout
9167
9168 \begin_layout LyX-Code
9169 EndPreamble
9170 \end_layout
9171
9172 \begin_layout LyX-Code
9173
9174 \change_inserted 0 1234612037
9175 LangPreamble
9176 \end_layout
9177
9178 \begin_layout LyX-Code
9179
9180 \change_inserted 0 1234612045
9181
9182 \backslash
9183 providecommand{
9184 \backslash
9185 claimname}{_(Claim)}
9186 \end_layout
9187
9188 \begin_layout LyX-Code
9189
9190 \change_inserted 0 1234611897
9191
9192 \end_layout
9193
9194 \begin_layout LyX-Code
9195
9196 \change_inserted 0 1234612050
9197 EndLangPreamble
9198 \end_layout
9199
9200 \begin_layout LyX-Code
9201
9202 \change_inserted 0 1234611892
9203 Babel
9204 \change_deleted 0 1234611847
9205 I18n
9206 \change_unchanged
9207 Preamble
9208 \end_layout
9209
9210 \begin_layout LyX-Code
9211
9212 \change_deleted 0 1234612079
9213
9214 \backslash
9215 AtBeginDocument{
9216 \backslash
9217 ifx
9218 \backslash
9219 LdfInit
9220 \backslash
9221 undefined
9222 \backslash
9223 relax
9224 \backslash
9225 else%
9226 \end_layout
9227
9228 \begin_layout LyX-Code
9229
9230 \backslash
9231 addto
9232 \backslash
9233 captions$$lang{
9234 \backslash
9235 renewcommand{
9236 \backslash
9237 claimname}{_(Claim)}}
9238 \change_deleted 0 1234612086
9239 %
9240 \end_layout
9241
9242 \begin_layout LyX-Code
9243
9244 \change_deleted 0 1234612089
9245
9246 \backslash
9247 fi}
9248 \change_unchanged
9249
9250 \end_layout
9251
9252 \begin_layout LyX-Code
9253 End
9254 \change_inserted 0 1234611859
9255 Babel
9256 \change_deleted 0 1234611856
9257 I18n
9258 \change_unchanged
9259 Preamble
9260 \end_layout
9261
9262 \begin_layout Standard
9263 The key to correct translation of the user visible text is the definition
9264  of the command
9265 \begin_inset Flex CharStyle:Code
9266 status collapsed
9267
9268 \begin_layout Plain Layout
9269
9270 \backslash
9271 claimname
9272 \end_layout
9273
9274 \end_inset
9275
9276  in the
9277 \change_inserted 0 1234612144
9278 language
9279 \change_deleted 0 1234612146
9280 standard
9281 \change_unchanged
9282  preamble.
9283  This command holds the name of the theorem that will appear in the output.
9284  The
9285 \begin_inset Flex CharStyle:Code
9286 status collapsed
9287
9288 \begin_layout Plain Layout
9289
9290 \change_inserted 0 1234612157
9291 Babel
9292 \change_deleted 0 1234612155
9293 I18N
9294 \change_unchanged
9295 Preamble
9296 \end_layout
9297
9298 \end_inset
9299
9300  then uses the commands offered by the babel package to redefine
9301 \begin_inset Flex CharStyle:Code
9302 status collapsed
9303
9304 \begin_layout Plain Layout
9305
9306 \backslash
9307 claimname
9308 \end_layout
9309
9310 \end_inset
9311
9312  for each used language
9313 \change_inserted 0 1234622073
9314  in multilanguage documents
9315 \change_unchanged
9316 .
9317
9318 \change_deleted 0 1234612171
9319  The
9320 \begin_inset Flex CharStyle:Code
9321 status collapsed
9322
9323 \begin_layout Plain Layout
9324
9325 \backslash
9326 ifx
9327 \backslash
9328 LdfInit
9329 \end_layout
9330
9331 \end_inset
9332
9333  test ensures that no LaTeX error occurs in documents that do not use babel.
9334  Since LyX loads babel after the style-specific preamble, the whole command
9335  is deferred to the actual start of the document with
9336 \begin_inset Flex CharStyle:Code
9337 status collapsed
9338
9339 \begin_layout Plain Layout
9340
9341 \backslash
9342 AtBeginDocument
9343 \end_layout
9344
9345 \end_inset
9346
9347 .
9348 \change_unchanged
9349
9350 \end_layout
9351
9352 \end_deeper
9353 \begin_layout Description
9354 \begin_inset Flex CharStyle:Code
9355 status collapsed
9356
9357 \begin_layout Plain Layout
9358 InnerTag
9359 \end_layout
9360
9361 \end_inset
9362
9363  [[FIXME]] (Used only with XML-type formats.)
9364 \end_layout
9365
9366 \begin_layout Description
9367 \begin_inset Flex CharStyle:Code
9368 status collapsed
9369
9370 \begin_layout Plain Layout
9371 InTitle
9372 \end_layout
9373
9374 \end_inset
9375
9376
9377 \begin_inset Flex CharStyle:Code
9378 status collapsed
9379
9380 \begin_layout Plain Layout
9381 [1, 0]
9382 \end_layout
9383
9384 \end_inset
9385
9386  If 1, marks the layout as being part of a title block (see also the
9387 \begin_inset Flex CharStyle:Code
9388 status collapsed
9389
9390 \begin_layout Plain Layout
9391 TitleLatexType
9392 \end_layout
9393
9394 \end_inset
9395
9396  and
9397 \begin_inset Flex CharStyle:Code
9398 status collapsed
9399
9400 \begin_layout Plain Layout
9401 TitleLatexName
9402 \end_layout
9403
9404 \end_inset
9405
9406  global entries).
9407 \end_layout
9408
9409 \begin_layout Description
9410 \begin_inset Flex CharStyle:Code
9411 status collapsed
9412
9413 \begin_layout Plain Layout
9414 ItemSep
9415 \end_layout
9416
9417 \end_inset
9418
9419  [
9420 \begin_inset Flex CharStyle:Code
9421 status collapsed
9422
9423 \begin_layout Plain Layout
9424 float=0
9425 \end_layout
9426
9427 \end_inset
9428
9429 ] This provides extra space between paragraphs that have the same layout.
9430  If you put other layouts into an environment, each is separated with the
9431  environment's
9432 \begin_inset Flex CharStyle:Code
9433 status collapsed
9434
9435 \begin_layout Plain Layout
9436 Parsep
9437 \end_layout
9438
9439 \end_inset
9440
9441 .
9442  But the whole items of the environment are additionally separated with
9443  this
9444 \begin_inset Flex CharStyle:Code
9445 status collapsed
9446
9447 \begin_layout Plain Layout
9448 Itemsep
9449 \end_layout
9450
9451 \end_inset
9452
9453 .
9454  Note that this is a
9455 \emph on
9456  multiplier.
9457 \end_layout
9458
9459 \begin_layout Description
9460 \begin_inset Flex CharStyle:Code
9461 status collapsed
9462
9463 \begin_layout Plain Layout
9464 ItemTag
9465 \end_layout
9466
9467 \end_inset
9468
9469  [[FIXME]] (Used only with XML-type formats.)
9470 \end_layout
9471
9472 \begin_layout Description
9473 \begin_inset Flex CharStyle:Code
9474 status collapsed
9475
9476 \begin_layout Plain Layout
9477 KeepEmpty
9478 \end_layout
9479
9480 \end_inset
9481
9482
9483 \begin_inset CommandInset label
9484 LatexCommand label
9485 name "des:KeepEmpty"
9486
9487 \end_inset
9488
9489 [
9490 \emph on
9491
9492 \begin_inset Flex CharStyle:Code
9493 status collapsed
9494
9495 \begin_layout Plain Layout
9496
9497 \emph on
9498 0
9499 \end_layout
9500
9501 \end_inset
9502
9503
9504 \emph default
9505 ,
9506 \begin_inset Flex CharStyle:Code
9507 status collapsed
9508
9509 \begin_layout Plain Layout
9510 1
9511 \end_layout
9512
9513 \end_inset
9514
9515 ] Usually LyX does not allow you to leave a paragraph empty, since it would
9516  lead to empty LaTeX output.
9517  There are some cases where this could be desirable however: in a letter
9518  template, the required fields can be provided as empty fields, so that
9519  people do not forget them; in some special classes, a layout can be used
9520  as some kind of break, which does not contain actual text.
9521 \end_layout
9522
9523 \begin_layout Description
9524 \begin_inset Flex CharStyle:Code
9525 status collapsed
9526
9527 \begin_layout Plain Layout
9528 LabelBottomsep
9529 \end_layout
9530
9531 \end_inset
9532
9533  [float=0] The vertical space between the label and the text body.
9534  Only used for labels that are above the text body (
9535 \begin_inset Flex CharStyle:Code
9536 status collapsed
9537
9538 \begin_layout Plain Layout
9539 Top_Environment
9540 \end_layout
9541
9542 \end_inset
9543
9544 ,
9545 \begin_inset Flex CharStyle:Code
9546 status collapsed
9547
9548 \begin_layout Plain Layout
9549 Centered_Top_Environment
9550 \end_layout
9551
9552 \end_inset
9553
9554 ).
9555 \end_layout
9556
9557 \begin_layout Description
9558 \begin_inset Flex CharStyle:Code
9559 status collapsed
9560
9561 \begin_layout Plain Layout
9562 LabelCounter
9563 \end_layout
9564
9565 \end_inset
9566
9567  [
9568 \begin_inset Flex CharStyle:Code
9569 status collapsed
9570
9571 \begin_layout Plain Layout
9572 string=""
9573 \end_layout
9574
9575 \end_inset
9576
9577 ]
9578 \begin_inset Newline newline
9579 \end_inset
9580
9581 The name of the counter for automatic numbering (see Section
9582 \begin_inset CommandInset ref
9583 LatexCommand ref
9584 reference "sec:counter"
9585
9586 \end_inset
9587
9588  for details).
9589  This must be given if
9590 \begin_inset Flex CharStyle:Code
9591 status collapsed
9592
9593 \begin_layout Plain Layout
9594 Labeltype
9595 \end_layout
9596
9597 \end_inset
9598
9599  is
9600 \begin_inset Flex CharStyle:Code
9601 status collapsed
9602
9603 \begin_layout Plain Layout
9604 Counter
9605 \end_layout
9606
9607 \end_inset
9608
9609 .
9610 \end_layout
9611
9612 \begin_layout Description
9613 \begin_inset Flex CharStyle:Code
9614 status collapsed
9615
9616 \begin_layout Plain Layout
9617 LabelFont
9618 \end_layout
9619
9620 \end_inset
9621
9622  The font used for the label.
9623  See section
9624 \begin_inset space ~
9625 \end_inset
9626
9627
9628 \begin_inset CommandInset ref
9629 LatexCommand ref
9630 reference "sec:fonts"
9631
9632 \end_inset
9633
9634 .
9635 \end_layout
9636
9637 \begin_layout Description
9638 \begin_inset Flex CharStyle:Code
9639 status collapsed
9640
9641 \begin_layout Plain Layout
9642 LabelIndent
9643 \end_layout
9644
9645 \end_inset
9646
9647  Text that indicates how far a label should be indented.
9648 \end_layout
9649
9650 \begin_layout Description
9651 \begin_inset Flex CharStyle:Code
9652 status collapsed
9653
9654 \begin_layout Plain Layout
9655 Labelsep
9656 \end_layout
9657
9658 \end_inset
9659
9660  [
9661 \begin_inset Flex CharStyle:Code
9662 status collapsed
9663
9664 \begin_layout Plain Layout
9665 string=""
9666 \end_layout
9667
9668 \end_inset
9669
9670 ] The horizontal space between the label and the text body.
9671  Only used for labels that are not above the text body.
9672 \end_layout
9673
9674 \begin_layout Description
9675 \begin_inset Flex CharStyle:Code
9676 status collapsed
9677
9678 \begin_layout Plain Layout
9679 LabelString
9680 \end_layout
9681
9682 \end_inset
9683
9684  [
9685 \begin_inset Flex CharStyle:Code
9686 status collapsed
9687
9688 \begin_layout Plain Layout
9689 string=""
9690 \end_layout
9691
9692 \end_inset
9693
9694 ] The string used for a label with a
9695 \begin_inset Flex CharStyle:Code
9696 status collapsed
9697
9698 \begin_layout Plain Layout
9699 Static
9700 \end_layout
9701
9702 \end_inset
9703
9704  labeltype.
9705  When
9706 \begin_inset Flex CharStyle:Code
9707 status collapsed
9708
9709 \begin_layout Plain Layout
9710 LabelCounter
9711 \end_layout
9712
9713 \end_inset
9714
9715  is set, this string can be contain the special formatting commands described
9716  in Section
9717 \begin_inset CommandInset ref
9718 LatexCommand ref
9719 reference "sec:counter"
9720
9721 \end_inset
9722
9723 .
9724 \begin_inset Foot
9725 status collapsed
9726
9727 \begin_layout Plain Layout
9728 For the sake of backwards compatibility, the string
9729 \begin_inset Flex CharStyle:Code
9730 status collapsed
9731
9732 \begin_layout Plain Layout
9733 @
9734 \emph on
9735 style-name
9736 \emph default
9737 @
9738 \end_layout
9739
9740 \end_inset
9741
9742  will be replaced by the expanded
9743 \begin_inset Flex CharStyle:Code
9744 status collapsed
9745
9746 \begin_layout Plain Layout
9747 LabelString
9748 \end_layout
9749
9750 \end_inset
9751
9752  of style
9753 \begin_inset Flex CharStyle:Code
9754 status collapsed
9755
9756 \begin_layout Plain Layout
9757
9758 \emph on
9759 style-name
9760 \end_layout
9761
9762 \end_inset
9763
9764 .
9765  This feature is now obsolete and should be replaced by the mechanisms of
9766  Section
9767 \begin_inset CommandInset ref
9768 LatexCommand ref
9769 reference "sec:counter"
9770
9771 \end_inset
9772
9773 .
9774 \end_layout
9775
9776 \end_inset
9777
9778
9779 \end_layout
9780
9781 \begin_layout Description
9782 \begin_inset Flex CharStyle:Code
9783 status collapsed
9784
9785 \begin_layout Plain Layout
9786 LabelStringAppendix
9787 \end_layout
9788
9789 \end_inset
9790
9791  [
9792 \begin_inset Flex CharStyle:Code
9793 status collapsed
9794
9795 \begin_layout Plain Layout
9796 string=""
9797 \end_layout
9798
9799 \end_inset
9800
9801 ] This is used inside the appendix instead of
9802 \begin_inset Flex CharStyle:Code
9803 status collapsed
9804
9805 \begin_layout Plain Layout
9806 LabelString
9807 \end_layout
9808
9809 \end_inset
9810
9811 .
9812  Note that every
9813 \begin_inset Flex CharStyle:Code
9814 status collapsed
9815
9816 \begin_layout Plain Layout
9817 LabelString
9818 \end_layout
9819
9820 \end_inset
9821
9822  statement resets
9823 \begin_inset Flex CharStyle:Code
9824 status collapsed
9825
9826 \begin_layout Plain Layout
9827 LabelStringAppendix
9828 \end_layout
9829
9830 \end_inset
9831
9832  too.
9833 \end_layout
9834
9835 \begin_layout Description
9836 \begin_inset Flex CharStyle:Code
9837 status collapsed
9838
9839 \begin_layout Plain Layout
9840 LabelTag
9841 \end_layout
9842
9843 \end_inset
9844
9845  [FIXME] (Used only with XML-type formats.)
9846 \end_layout
9847
9848 \begin_layout Description
9849 \begin_inset Flex CharStyle:Code
9850 status collapsed
9851
9852 \begin_layout Plain Layout
9853 Labeltype
9854 \end_layout
9855
9856 \end_inset
9857
9858  [
9859 \begin_inset Flex CharStyle:Code
9860 status collapsed
9861
9862 \begin_layout Plain Layout
9863
9864 \emph on
9865 No_Label
9866 \emph default
9867 , Manual, Static, Top_Environment,
9868 \begin_inset Newline newline
9869 \end_inset
9870
9871 Centered_Top_Environment, Sensitive, Counter
9872 \end_layout
9873
9874 \end_inset
9875
9876 ]
9877 \begin_inset Newline newline
9878 \end_inset
9879
9880
9881 \begin_inset Flex CharStyle:Code
9882 status collapsed
9883
9884 \begin_layout Plain Layout
9885 Manual
9886 \end_layout
9887
9888 \end_inset
9889
9890  means the label is the very first word (up to the first real blank).
9891 \begin_inset Foot
9892 status collapsed
9893
9894 \begin_layout Plain Layout
9895 Use protected spaces if you want more than one word as the label.
9896 \end_layout
9897
9898 \end_inset
9899
9900
9901 \begin_inset Flex CharStyle:Code
9902 status collapsed
9903
9904 \begin_layout Plain Layout
9905 Static
9906 \end_layout
9907
9908 \end_inset
9909
9910  means it is defined in the layout (see
9911 \begin_inset Flex CharStyle:Code
9912 status collapsed
9913
9914 \begin_layout Plain Layout
9915 LabelString
9916 \end_layout
9917
9918 \end_inset
9919
9920 ).
9921
9922 \begin_inset Flex CharStyle:Code
9923 status collapsed
9924
9925 \begin_layout Plain Layout
9926 Top_Environment
9927 \end_layout
9928
9929 \end_inset
9930
9931  and
9932 \begin_inset Flex CharStyle:Code
9933 status collapsed
9934
9935 \begin_layout Plain Layout
9936 Centered_Top_Environment
9937 \end_layout
9938
9939 \end_inset
9940
9941  are special cases of
9942 \begin_inset Flex CharStyle:Code
9943 status collapsed
9944
9945 \begin_layout Plain Layout
9946 Static
9947 \end_layout
9948
9949 \end_inset
9950
9951 .
9952  The label will be printed above the paragraph, but only at the top of an
9953  environment or the top of a chain of paragraphs with this layout.
9954  Usage is for example the
9955 \begin_inset Flex CharStyle:MenuItem
9956 status collapsed
9957
9958 \begin_layout Plain Layout
9959 Abstract
9960 \end_layout
9961
9962 \end_inset
9963
9964  layout or the
9965 \begin_inset Flex CharStyle:MenuItem
9966 status collapsed
9967
9968 \begin_layout Plain Layout
9969 Bibliography
9970 \end_layout
9971
9972 \end_inset
9973
9974  layout.
9975  This is also the case for
9976 \begin_inset Flex CharStyle:Code
9977 status collapsed
9978
9979 \begin_layout Plain Layout
9980 Manual
9981 \end_layout
9982
9983 \end_inset
9984
9985  labels with latex type
9986 \begin_inset Flex CharStyle:Code
9987 status collapsed
9988
9989 \begin_layout Plain Layout
9990 Environment
9991 \end_layout
9992
9993 \end_inset
9994
9995 , in order to make layouts for theorems work correctly.
9996
9997 \begin_inset Flex CharStyle:Code
9998 status collapsed
9999
10000 \begin_layout Plain Layout
10001 Sensitive
10002 \end_layout
10003
10004 \end_inset
10005
10006  is a special case for the caption-labels
10007 \begin_inset Quotes eld
10008 \end_inset
10009
10010 Figure
10011 \begin_inset Quotes erd
10012 \end_inset
10013
10014  and
10015 \begin_inset Quotes eld
10016 \end_inset
10017
10018 Table
10019 \begin_inset Quotes erd
10020 \end_inset
10021
10022 .
10023
10024 \begin_inset Flex CharStyle:Code
10025 status collapsed
10026
10027 \begin_layout Plain Layout
10028 Sensitive
10029 \end_layout
10030
10031 \end_inset
10032
10033  means the (hardcoded) label string depends on the kind of float.
10034  The
10035 \begin_inset Flex CharStyle:Code
10036 status collapsed
10037
10038 \begin_layout Plain Layout
10039 Counter
10040 \end_layout
10041
10042 \end_inset
10043
10044  label type defines automatically numbered labels.
10045  See Section
10046 \begin_inset CommandInset ref
10047 LatexCommand ref
10048 reference "sec:counter"
10049
10050 \end_inset
10051
10052 .
10053 \end_layout
10054
10055 \begin_layout Description
10056 \begin_inset Flex CharStyle:Code
10057 status collapsed
10058
10059 \begin_layout Plain Layout
10060 LatexName
10061 \end_layout
10062
10063 \end_inset
10064
10065  The name of the corresponding LaTeX stuff.
10066  Either the environment or command name.
10067 \end_layout
10068
10069 \begin_layout Description
10070 \begin_inset Flex CharStyle:Code
10071 status collapsed
10072
10073 \begin_layout Plain Layout
10074 LatexParam
10075 \end_layout
10076
10077 \end_inset
10078
10079  An optional parameter for the corresponding
10080 \begin_inset Flex CharStyle:Code
10081 status collapsed
10082
10083 \begin_layout Plain Layout
10084 LatexName
10085 \end_layout
10086
10087 \end_inset
10088
10089  stuff.
10090  This parameter cannot be changed from within LyX.
10091 \end_layout
10092
10093 \begin_layout Description
10094 \begin_inset Flex CharStyle:Code
10095 status collapsed
10096
10097 \begin_layout Plain Layout
10098 LatexType
10099 \end_layout
10100
10101 \end_inset
10102
10103
10104 \begin_inset CommandInset label
10105 LatexCommand label
10106 name "des:LatexType"
10107
10108 \end_inset
10109
10110 [
10111 \begin_inset Flex CharStyle:Code
10112 status collapsed
10113
10114 \begin_layout Plain Layout
10115
10116 \emph on
10117 Paragraph
10118 \emph default
10119 , Command, Environment, Item_Environment,
10120 \end_layout
10121
10122 \end_inset
10123
10124
10125 \begin_inset Flex CharStyle:Code
10126 status collapsed
10127
10128 \begin_layout Plain Layout
10129 List_Environment
10130 \end_layout
10131
10132 \end_inset
10133
10134 ] How the layout should be translated into LaTeX.
10135
10136 \begin_inset Flex CharStyle:Code
10137 status collapsed
10138
10139 \begin_layout Plain Layout
10140 Paragraph
10141 \end_layout
10142
10143 \end_inset
10144
10145  means nothing special.
10146
10147 \begin_inset Flex CharStyle:Code
10148 status collapsed
10149
10150 \begin_layout Plain Layout
10151 Command
10152 \end_layout
10153
10154 \end_inset
10155
10156  means
10157 \begin_inset Flex CharStyle:Code
10158 status collapsed
10159
10160 \begin_layout Plain Layout
10161
10162 \backslash
10163
10164 \emph on
10165 LatexName
10166 \emph default
10167 {\SpecialChar \ldots{}
10168 }
10169 \end_layout
10170
10171 \end_inset
10172
10173  and
10174 \begin_inset Flex CharStyle:Code
10175 status collapsed
10176
10177 \begin_layout Plain Layout
10178 Environment
10179 \end_layout
10180
10181 \end_inset
10182
10183  means
10184 \begin_inset Flex CharStyle:Code
10185 status collapsed
10186
10187 \begin_layout Plain Layout
10188
10189 \backslash
10190 begin{
10191 \emph on
10192 LatexName
10193 \emph default
10194 }\SpecialChar \ldots{}
10195
10196 \backslash
10197 end{
10198 \emph on
10199 LatexName
10200 \emph default
10201 }
10202 \end_layout
10203
10204 \end_inset
10205
10206 .
10207
10208 \begin_inset Flex CharStyle:Code
10209 status collapsed
10210
10211 \begin_layout Plain Layout
10212 Item_Environment
10213 \end_layout
10214
10215 \end_inset
10216
10217  is the same as
10218 \begin_inset Flex CharStyle:Code
10219 status collapsed
10220
10221 \begin_layout Plain Layout
10222 Environment
10223 \end_layout
10224
10225 \end_inset
10226
10227 , except that a
10228 \begin_inset Flex CharStyle:Code
10229 status collapsed
10230
10231 \begin_layout Plain Layout
10232
10233 \backslash
10234 item
10235 \end_layout
10236
10237 \end_inset
10238
10239  is generated for each paragraph of this environment.
10240
10241 \begin_inset Flex CharStyle:Code
10242 status collapsed
10243
10244 \begin_layout Plain Layout
10245 List_Environment
10246 \end_layout
10247
10248 \end_inset
10249
10250  is the same as
10251 \begin_inset Flex CharStyle:Code
10252 status collapsed
10253
10254 \begin_layout Plain Layout
10255 Item_Environment
10256 \end_layout
10257
10258 \end_inset
10259
10260 , except that
10261 \begin_inset Flex CharStyle:Code
10262 status collapsed
10263
10264 \begin_layout Plain Layout
10265 LabelWidthString
10266 \end_layout
10267
10268 \end_inset
10269
10270  is passed as an argument to the environment.
10271
10272 \begin_inset Flex CharStyle:Code
10273 status collapsed
10274
10275 \begin_layout Plain Layout
10276 LabelWidthString
10277 \end_layout
10278
10279 \end_inset
10280
10281  can be defined in the
10282 \begin_inset Flex CharStyle:MenuItem
10283 status collapsed
10284
10285 \begin_layout Plain Layout
10286
10287 \bar under
10288 L
10289 \bar default
10290 ayout\SpecialChar \menuseparator
10291
10292 \bar under
10293 P
10294 \bar default
10295 aragraph
10296 \end_layout
10297
10298 \end_inset
10299
10300  dialog.
10301
10302 \begin_inset Flex CharStyle:Code
10303 status collapsed
10304
10305 \begin_layout Plain Layout
10306
10307 \emph on
10308 LatexType
10309 \end_layout
10310
10311 \end_inset
10312
10313  is perhaps a bit misleading, since these rules apply to SGML classes, too.
10314  Visit the SGML class files for specific examples.
10315 \end_layout
10316
10317 \begin_layout Standard
10318 Putting the last few things together, the LaTeX output will be either:
10319 \end_layout
10320
10321 \begin_layout LyX-Code
10322
10323 \backslash
10324 latexname[latexparam]{\SpecialChar \ldots{}
10325 }
10326 \end_layout
10327
10328 \begin_layout Standard
10329 or:
10330 \end_layout
10331
10332 \begin_layout LyX-Code
10333
10334 \backslash
10335 begin{latexname}[latexparam] \SpecialChar \ldots{}
10336
10337 \backslash
10338 end{latexname}.
10339 \end_layout
10340
10341 \begin_layout Standard
10342 depending upon the LaTeX type.
10343 \end_layout
10344
10345 \begin_layout Description
10346 \begin_inset Flex CharStyle:Code
10347 status collapsed
10348
10349 \begin_layout Plain Layout
10350 LeftMargin
10351 \end_layout
10352
10353 \end_inset
10354
10355  [
10356 \begin_inset Flex CharStyle:Code
10357 status collapsed
10358
10359 \begin_layout Plain Layout
10360 string=""
10361 \end_layout
10362
10363 \end_inset
10364
10365 ] If you put layouts into environments, the leftmargins are not simply added,
10366  but added with a factor
10367 \begin_inset Formula $\frac{4}{depth+4}$
10368 \end_inset
10369
10370 .
10371  Note that this parameter is also used when the margin is defined as
10372 \begin_inset Flex CharStyle:Code
10373 status collapsed
10374
10375 \begin_layout Plain Layout
10376 Manual
10377 \end_layout
10378
10379 \end_inset
10380
10381  or
10382 \begin_inset Flex CharStyle:Code
10383 status collapsed
10384
10385 \begin_layout Plain Layout
10386 Dynamic
10387 \end_layout
10388
10389 \end_inset
10390
10391 .
10392  Then it is added to the manual or dynamic margin.
10393
10394 \begin_inset Newline newline
10395 \end_inset
10396
10397 The argument is passed as a string.
10398  For example
10399 \begin_inset Quotes eld
10400 \end_inset
10401
10402
10403 \begin_inset Flex CharStyle:Code
10404 status collapsed
10405
10406 \begin_layout Plain Layout
10407 MM
10408 \end_layout
10409
10410 \end_inset
10411
10412
10413 \begin_inset Quotes erd
10414 \end_inset
10415
10416  means that the paragraph is indented with the width of
10417 \begin_inset Quotes eld
10418 \end_inset
10419
10420
10421 \begin_inset Flex CharStyle:Code
10422 status collapsed
10423
10424 \begin_layout Plain Layout
10425 MM
10426 \end_layout
10427
10428 \end_inset
10429
10430
10431 \begin_inset Quotes erd
10432 \end_inset
10433
10434  in the normal font.
10435  You can get a negative width by prefixing the string with
10436 \begin_inset Quotes eld
10437 \end_inset
10438
10439
10440 \begin_inset Flex CharStyle:Code
10441 status collapsed
10442
10443 \begin_layout Plain Layout
10444 -
10445 \end_layout
10446
10447 \end_inset
10448
10449
10450 \begin_inset Quotes erd
10451 \end_inset
10452
10453 .
10454  This way was chosen so that the look is the same with each used screen
10455  font.
10456
10457 \end_layout
10458
10459 \begin_layout Description
10460 \begin_inset Flex CharStyle:Code
10461 status collapsed
10462
10463 \begin_layout Plain Layout
10464 Margin
10465 \end_layout
10466
10467 \end_inset
10468
10469  [
10470 \begin_inset Flex CharStyle:Code
10471 status collapsed
10472
10473 \begin_layout Plain Layout
10474
10475 \emph on
10476 Static
10477 \emph default
10478 , Manual, Dynamic, First_Dynamic, Right_Address_Box
10479 \end_layout
10480
10481 \end_inset
10482
10483 ]
10484 \begin_inset Newline newline
10485 \end_inset
10486
10487 The kind of margin that the layout has on the left side.
10488
10489 \begin_inset Flex CharStyle:Code
10490 status collapsed
10491
10492 \begin_layout Plain Layout
10493 Static
10494 \end_layout
10495
10496 \end_inset
10497
10498  just means a fixed margin.
10499
10500 \begin_inset Flex CharStyle:Code
10501 status collapsed
10502
10503 \begin_layout Plain Layout
10504 Manual
10505 \end_layout
10506
10507 \end_inset
10508
10509  means that the left margin depends on the string entered in the
10510 \begin_inset Flex CharStyle:MenuItem
10511 status collapsed
10512
10513 \begin_layout Plain Layout
10514 Edit\SpecialChar \menuseparator
10515 Paragraph
10516 \begin_inset space ~
10517 \end_inset
10518
10519 Settings
10520 \end_layout
10521
10522 \end_inset
10523
10524  dialog.
10525  This is used to typeset nice lists without tabulators.
10526
10527 \begin_inset Flex CharStyle:Code
10528 status collapsed
10529
10530 \begin_layout Plain Layout
10531 Dynamic
10532 \end_layout
10533
10534 \end_inset
10535
10536  means that the margin depends on the size of the label.
10537  This is used for automatic enumerated headlines.
10538  It is obvious that the headline
10539 \begin_inset Quotes eld
10540 \end_inset
10541
10542 5.4.3.2.1 Very long headline
10543 \begin_inset Quotes erd
10544 \end_inset
10545
10546  must have a wider left margin (as wide as
10547 \begin_inset Quotes eld
10548 \end_inset
10549
10550 5.4.3.2.1
10551 \begin_inset Quotes erd
10552 \end_inset
10553
10554  plus the space) than
10555 \begin_inset Quotes eld
10556 \end_inset
10557
10558 3.2 Very long headline
10559 \begin_inset Quotes erd
10560 \end_inset
10561
10562 , even if standard
10563 \begin_inset Quotes eld
10564 \end_inset
10565
10566 word processors
10567 \begin_inset Quotes erd
10568 \end_inset
10569
10570  are not able to do this.
10571
10572 \begin_inset Flex CharStyle:Code
10573 status collapsed
10574
10575 \begin_layout Plain Layout
10576 First_Dynamic
10577 \end_layout
10578
10579 \end_inset
10580
10581  is similar, but only the very first row of the paragraph is dynamic, while
10582  the others are static; this is used, for example, for descriptions.
10583
10584 \begin_inset Flex CharStyle:Code
10585 status collapsed
10586
10587 \begin_layout Plain Layout
10588 Right_Address_Box
10589 \end_layout
10590
10591 \end_inset
10592
10593  means the margin is chosen in a way that the longest row of this paragraph
10594  fits to the right margin.
10595  This is used to typeset an address on the right edge of the page.
10596 \end_layout
10597
10598 \begin_layout Description
10599 \begin_inset Flex CharStyle:Code
10600 status collapsed
10601
10602 \begin_layout Plain Layout
10603 NeedProtect
10604 \end_layout
10605
10606 \end_inset
10607
10608  [
10609 \begin_inset Flex CharStyle:Code
10610 status collapsed
10611
10612 \begin_layout Plain Layout
10613
10614 \emph on
10615 0
10616 \end_layout
10617
10618 \end_inset
10619
10620 ,
10621 \begin_inset Flex CharStyle:Code
10622 status collapsed
10623
10624 \begin_layout Plain Layout
10625 1
10626 \end_layout
10627
10628 \end_inset
10629
10630 ] Whether fragile commands in this layout should be
10631 \begin_inset Flex CharStyle:Code
10632 status collapsed
10633
10634 \begin_layout Plain Layout
10635
10636 \backslash
10637 protect
10638 \end_layout
10639
10640 \end_inset
10641
10642 'ed.
10643  (Note: This is
10644 \emph on
10645 not
10646 \emph default
10647  whether this command should itself be protected.)
10648 \end_layout
10649
10650 \begin_layout Description
10651 \begin_inset Flex CharStyle:Code
10652 status collapsed
10653
10654 \begin_layout Plain Layout
10655 Newline
10656 \end_layout
10657
10658 \end_inset
10659
10660  [
10661 \begin_inset Flex CharStyle:Code
10662 status collapsed
10663
10664 \begin_layout Plain Layout
10665 0
10666 \end_layout
10667
10668 \end_inset
10669
10670 ,
10671 \begin_inset Flex CharStyle:Code
10672 status collapsed
10673
10674 \begin_layout Plain Layout
10675
10676 \emph on
10677 1
10678 \end_layout
10679
10680 \end_inset
10681
10682 ] Whether newlines are translated into LaTeX newlines (
10683 \begin_inset Flex CharStyle:Code
10684 status collapsed
10685
10686 \begin_layout Plain Layout
10687
10688 \backslash
10689
10690 \backslash
10691
10692 \end_layout
10693
10694 \end_inset
10695
10696 ) or not.
10697  The translation can be switched off to allow more comfortable LaTeX editing
10698  inside LyX.
10699 \end_layout
10700
10701 \begin_layout Description
10702 \begin_inset Flex CharStyle:Code
10703 status collapsed
10704
10705 \begin_layout Plain Layout
10706 NextNoIndent
10707 \end_layout
10708
10709 \end_inset
10710
10711  [
10712 \begin_inset Flex CharStyle:Code
10713 status collapsed
10714
10715 \begin_layout Plain Layout
10716 1
10717 \end_layout
10718
10719 \end_inset
10720
10721 ,
10722 \begin_inset Flex CharStyle:Code
10723 status collapsed
10724
10725 \begin_layout Plain Layout
10726
10727 \emph on
10728 0
10729 \end_layout
10730
10731 \end_inset
10732
10733 ] Whether the following Paragraph is allowed to indent its very first row.
10734
10735 \begin_inset Flex CharStyle:Code
10736 status collapsed
10737
10738 \begin_layout Plain Layout
10739 1
10740 \end_layout
10741
10742 \end_inset
10743
10744  means that it is not allowed to do so;
10745 \begin_inset Flex CharStyle:Code
10746 status collapsed
10747
10748 \begin_layout Plain Layout
10749 0
10750 \end_layout
10751
10752 \end_inset
10753
10754  means it could do so if it wants to.
10755 \end_layout
10756
10757 \begin_layout Description
10758 \begin_inset Flex CharStyle:Code
10759 status collapsed
10760
10761 \begin_layout Plain Layout
10762 ObsoletedBy
10763 \end_layout
10764
10765 \end_inset
10766
10767  Name of a layout that has replaced this layout.
10768  This is used to rename a layout, while keeping backward compatibility.
10769 \end_layout
10770
10771 \begin_layout Description
10772 \begin_inset Flex CharStyle:Code
10773 status collapsed
10774
10775 \begin_layout Plain Layout
10776 OptionalArgs
10777 \end_layout
10778
10779 \end_inset
10780
10781  [
10782 \begin_inset Flex CharStyle:Code
10783 status collapsed
10784
10785 \begin_layout Plain Layout
10786 int=0
10787 \end_layout
10788
10789 \end_inset
10790
10791 ] The number of optional arguments that can be used with this layout.
10792  This is useful for things like section headings, and only makes sense with
10793  LaTeX.
10794 \end_layout
10795
10796 \begin_layout Description
10797 \begin_inset Flex CharStyle:Code
10798 status collapsed
10799
10800 \begin_layout Plain Layout
10801 ParIndent
10802 \end_layout
10803
10804 \end_inset
10805
10806  [
10807 \begin_inset Flex CharStyle:Code
10808 status collapsed
10809
10810 \begin_layout Plain Layout
10811 string=""
10812 \end_layout
10813
10814 \end_inset
10815
10816 ] The indent of the very first line of a paragraph.
10817  The
10818 \begin_inset Flex CharStyle:Code
10819 status collapsed
10820
10821 \begin_layout Plain Layout
10822 Parindent
10823 \end_layout
10824
10825 \end_inset
10826
10827  will be fixed for a certain layout.
10828  The exception is Standard layout, since the indentation of a Standard layout
10829  paragraph can be prohibited with
10830 \begin_inset Flex CharStyle:Code
10831 status collapsed
10832
10833 \begin_layout Plain Layout
10834 NextNoIndent
10835 \end_layout
10836
10837 \end_inset
10838
10839 .
10840  Also, Standard layout paragraphs inside environments use the
10841 \begin_inset Flex CharStyle:Code
10842 status collapsed
10843
10844 \begin_layout Plain Layout
10845 Parindent
10846 \end_layout
10847
10848 \end_inset
10849
10850  of the environment, not their native one.
10851  For example, Standard paragraphs inside an enumeration are not indented.
10852 \end_layout
10853
10854 \begin_layout Description
10855 \begin_inset Flex CharStyle:Code
10856 status collapsed
10857
10858 \begin_layout Plain Layout
10859 Parsep
10860 \end_layout
10861
10862 \end_inset
10863
10864  [
10865 \begin_inset Flex CharStyle:Code
10866 status collapsed
10867
10868 \begin_layout Plain Layout
10869 float=0
10870 \end_layout
10871
10872 \end_inset
10873
10874 ] The vertical space between two paragraphs of this layout.
10875 \end_layout
10876
10877 \begin_layout Description
10878 \begin_inset Flex CharStyle:Code
10879 status collapsed
10880
10881 \begin_layout Plain Layout
10882 Parskip
10883 \end_layout
10884
10885 \end_inset
10886
10887  [
10888 \begin_inset Flex CharStyle:Code
10889 status collapsed
10890
10891 \begin_layout Plain Layout
10892 float=0
10893 \end_layout
10894
10895 \end_inset
10896
10897 ] LyX allows the user to choose either
10898 \begin_inset Quotes eld
10899 \end_inset
10900
10901 indent
10902 \begin_inset Quotes erd
10903 \end_inset
10904
10905  or
10906 \begin_inset Quotes eld
10907 \end_inset
10908
10909 skip
10910 \begin_inset Quotes erd
10911 \end_inset
10912
10913  to typeset a document.
10914  When
10915 \begin_inset Quotes eld
10916 \end_inset
10917
10918 indent
10919 \begin_inset Quotes erd
10920 \end_inset
10921
10922  is chosen, this value is completely ignored.
10923  When
10924 \begin_inset Quotes eld
10925 \end_inset
10926
10927 skip
10928 \begin_inset Quotes erd
10929 \end_inset
10930
10931  is chosen, the parindent of a LaTeXtype
10932 \begin_inset Quotes eld
10933 \end_inset
10934
10935 Paragraph
10936 \begin_inset Quotes erd
10937 \end_inset
10938
10939  layout is ignored and all paragraphs are separated by this parskip argument.
10940  The vertical space is calculated with
10941 \begin_inset Flex CharStyle:Code
10942 status collapsed
10943
10944 \begin_layout Plain Layout
10945 value
10946 \begin_inset space ~
10947 \end_inset
10948
10949 * DefaultHeight
10950 \end_layout
10951
10952 \end_inset
10953
10954  where
10955 \begin_inset Flex CharStyle:Code
10956 status collapsed
10957
10958 \begin_layout Plain Layout
10959 DefaultHeight
10960 \end_layout
10961
10962 \end_inset
10963
10964  is the height of a row with the normal font.
10965  This way, the look stays the same with different screen fonts.
10966 \end_layout
10967
10968 \begin_layout Description
10969 \begin_inset Flex CharStyle:Code
10970 status collapsed
10971
10972 \begin_layout Plain Layout
10973 PassThru
10974 \end_layout
10975
10976 \end_inset
10977
10978
10979 \begin_inset CommandInset label
10980 LatexCommand label
10981 name "des:PathThru"
10982
10983 \end_inset
10984
10985 [
10986 \emph on
10987
10988 \begin_inset Flex CharStyle:Code
10989 status collapsed
10990
10991 \begin_layout Plain Layout
10992
10993 \emph on
10994 0
10995 \end_layout
10996
10997 \end_inset
10998
10999
11000 \emph default
11001 ,
11002 \begin_inset Flex CharStyle:Code
11003 status collapsed
11004
11005 \begin_layout Plain Layout
11006 1
11007 \end_layout
11008
11009 \end_inset
11010
11011 ] Whether the contents of this paragraph should be output in raw form, meaning
11012  without special translations that LaTeX would require.
11013 \end_layout
11014
11015 \begin_layout Description
11016 \begin_inset Flex CharStyle:Code
11017 status collapsed
11018
11019 \begin_layout Plain Layout
11020 Preamble
11021 \end_layout
11022
11023 \end_inset
11024
11025
11026 \begin_inset CommandInset label
11027 LatexCommand label
11028 name "des:Preamble"
11029
11030 \end_inset
11031
11032 Information to be included in the LaTeX preamble when this style is used.
11033  Used to define macros, load packages, etc., required by this particular
11034  style.
11035  Must end with
11036 \begin_inset Quotes eld
11037 \end_inset
11038
11039
11040 \begin_inset Flex CharStyle:Code
11041 status collapsed
11042
11043 \begin_layout Plain Layout
11044 EndPreamble
11045 \end_layout
11046
11047 \end_inset
11048
11049
11050 \begin_inset Quotes erd
11051 \end_inset
11052
11053 .
11054 \end_layout
11055
11056 \begin_layout Description
11057 \begin_inset Flex CharStyle:Code
11058 status collapsed
11059
11060 \begin_layout Plain Layout
11061 Requires
11062 \end_layout
11063
11064 \end_inset
11065
11066 [
11067 \begin_inset Flex CharStyle:Code
11068 status collapsed
11069
11070 \begin_layout Plain Layout
11071 string
11072 \end_layout
11073
11074 \end_inset
11075
11076 ]
11077 \begin_inset CommandInset label
11078 LatexCommand label
11079 name "des:Requires"
11080
11081 \end_inset
11082
11083 Whether the layout requires the feature
11084 \begin_inset Flex CharStyle:Code
11085 status collapsed
11086
11087 \begin_layout Plain Layout
11088 string
11089 \end_layout
11090
11091 \end_inset
11092
11093 .
11094  See the description of
11095 \begin_inset Flex CharStyle:Code
11096 status collapsed
11097
11098 \begin_layout Plain Layout
11099 Provides
11100 \end_layout
11101
11102 \end_inset
11103
11104  above (page
11105 \begin_inset CommandInset ref
11106 LatexCommand pageref
11107 reference "des:FreeSpacing"
11108
11109 \end_inset
11110
11111 ) for information on `features'.
11112
11113 \end_layout
11114
11115 \begin_layout Description
11116 \begin_inset Flex CharStyle:Code
11117 status collapsed
11118
11119 \begin_layout Plain Layout
11120 RightMargin
11121 \end_layout
11122
11123 \end_inset
11124
11125  [
11126 \begin_inset Flex CharStyle:Code
11127 status collapsed
11128
11129 \begin_layout Plain Layout
11130 string=""
11131 \end_layout
11132
11133 \end_inset
11134
11135 ] Similar to
11136 \begin_inset Flex CharStyle:Code
11137 status collapsed
11138
11139 \begin_layout Plain Layout
11140 LeftMargin
11141 \end_layout
11142
11143 \end_inset
11144
11145 .
11146 \end_layout
11147
11148 \begin_layout Description
11149 \begin_inset Flex CharStyle:Code
11150 status collapsed
11151
11152 \begin_layout Plain Layout
11153 Spacing
11154 \end_layout
11155
11156 \end_inset
11157
11158  [
11159 \begin_inset Flex CharStyle:Code
11160 status collapsed
11161
11162 \begin_layout Plain Layout
11163
11164 \emph on
11165 single
11166 \emph default
11167 , onehalf, double, other
11168 \end_layout
11169
11170 \end_inset
11171
11172
11173 \emph on
11174 value
11175 \emph default
11176 ] This defines what the default spacing should be in the layout.
11177  The arguments
11178 \begin_inset Flex CharStyle:Code
11179 status collapsed
11180
11181 \begin_layout Plain Layout
11182 single
11183 \end_layout
11184
11185 \end_inset
11186
11187 ,
11188 \begin_inset Flex CharStyle:Code
11189 status collapsed
11190
11191 \begin_layout Plain Layout
11192 onehalf
11193 \end_layout
11194
11195 \end_inset
11196
11197  and
11198 \begin_inset Flex CharStyle:Code
11199 status collapsed
11200
11201 \begin_layout Plain Layout
11202 double
11203 \end_layout
11204
11205 \end_inset
11206
11207  correspond respectively to a multiplier value of 1, 1.25 and 1.667.
11208  If you specify the argument
11209 \begin_inset Flex CharStyle:Code
11210 status collapsed
11211
11212 \begin_layout Plain Layout
11213 other
11214 \end_layout
11215
11216 \end_inset
11217
11218 , then you should also provide a numerical argument which will be the actual
11219  multiplier value.
11220  Note that, contrary to other parameters,
11221 \begin_inset Flex CharStyle:Code
11222 status collapsed
11223
11224 \begin_layout Plain Layout
11225 Spacing
11226 \end_layout
11227
11228 \end_inset
11229
11230  implies the generation of specific LaTeX code, using the package
11231 \family roman
11232
11233 \begin_inset Flex CharStyle:Code
11234 status collapsed
11235
11236 \begin_layout Plain Layout
11237 setspace.sty
11238 \end_layout
11239
11240 \end_inset
11241
11242 .
11243 \end_layout
11244
11245 \begin_layout Description
11246 \begin_inset Flex CharStyle:Code
11247 status collapsed
11248
11249 \begin_layout Plain Layout
11250 TextFont
11251 \end_layout
11252
11253 \end_inset
11254
11255  The font used for the text body .
11256  See section
11257 \begin_inset CommandInset ref
11258 LatexCommand ref
11259 reference "sec:fonts"
11260
11261 \end_inset
11262
11263 .
11264 \end_layout
11265
11266 \begin_layout Description
11267 \begin_inset Flex CharStyle:Code
11268 status collapsed
11269
11270 \begin_layout Plain Layout
11271
11272 \series medium
11273 TocLevel [int]
11274 \end_layout
11275
11276 \end_inset
11277
11278  The level of the style in the table of contents.
11279  This is used for automatic numbering of section headings.
11280 \end_layout
11281
11282 \begin_layout Description
11283 \begin_inset Flex CharStyle:Code
11284 status collapsed
11285
11286 \begin_layout Plain Layout
11287 TopSep
11288 \end_layout
11289
11290 \end_inset
11291
11292  [
11293 \begin_inset Flex CharStyle:Code
11294 status collapsed
11295
11296 \begin_layout Plain Layout
11297 float=0
11298 \end_layout
11299
11300 \end_inset
11301
11302 ] The vertical space with which the very first of a chain of paragraphs
11303  with this layout is separated from the previous paragraph.
11304  If the previous paragraph has another layout, the separations are not simply
11305  added, but the maximum is taken.
11306 \end_layout
11307
11308 \begin_layout Subsection
11309 Floats
11310 \end_layout
11311
11312 \begin_layout Standard
11313 \begin_inset CommandInset label
11314 LatexCommand label
11315 name "sec:floats"
11316
11317 \end_inset
11318
11319 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11320  define the floats (
11321 \begin_inset Flex CharStyle:MenuItem
11322 status collapsed
11323
11324 \begin_layout Plain Layout
11325 figure
11326 \end_layout
11327
11328 \end_inset
11329
11330 ,
11331 \begin_inset Flex CharStyle:MenuItem
11332 status collapsed
11333
11334 \begin_layout Plain Layout
11335 table
11336 \end_layout
11337
11338 \end_inset
11339
11340 , \SpecialChar \ldots{}
11341 ) in the text class itself.
11342  Standard floats are included in the file
11343 \begin_inset Flex CharStyle:Code
11344 status collapsed
11345
11346 \begin_layout Plain Layout
11347 stdfloats.inc
11348 \end_layout
11349
11350 \end_inset
11351
11352 , so you may have to do no more than add
11353 \end_layout
11354
11355 \begin_layout LyX-Code
11356 Input stdfloats.inc
11357 \end_layout
11358
11359 \begin_layout Standard
11360 to your layout file.
11361  If you want to implement a text class that proposes some other float types
11362  (like the AGU class bundled with LyX), the information below will hopefully
11363  help you:
11364 \end_layout
11365
11366 \begin_layout Description
11367 \begin_inset Flex CharStyle:Code
11368 status collapsed
11369
11370 \begin_layout Plain Layout
11371 Extension
11372 \end_layout
11373
11374 \end_inset
11375
11376  [
11377 \begin_inset Flex CharStyle:Code
11378 status collapsed
11379
11380 \begin_layout Plain Layout
11381 string
11382 \end_layout
11383
11384 \end_inset
11385
11386 =
11387 \begin_inset Quotes erd
11388 \end_inset
11389
11390
11391 \begin_inset Quotes erd
11392 \end_inset
11393
11394 ] The file name extension of an auxiliary file for the list of figures (or
11395  whatever).
11396  LaTeX writes the captions to this file.
11397 \end_layout
11398
11399 \begin_layout Description
11400 \begin_inset Flex CharStyle:Code
11401 status collapsed
11402
11403 \begin_layout Plain Layout
11404 GuiName
11405 \end_layout
11406
11407 \end_inset
11408
11409  [
11410 \begin_inset Flex CharStyle:Code
11411 status collapsed
11412
11413 \begin_layout Plain Layout
11414 string
11415 \end_layout
11416
11417 \end_inset
11418
11419 =
11420 \begin_inset Quotes erd
11421 \end_inset
11422
11423
11424 \begin_inset Quotes erd
11425 \end_inset
11426
11427 ] The string that will be used in the menus and also for the caption.
11428 \end_layout
11429
11430 \begin_layout Description
11431 \begin_inset Flex CharStyle:Code
11432 status collapsed
11433
11434 \begin_layout Plain Layout
11435 LaTeXBuiltin
11436 \end_layout
11437
11438 \end_inset
11439
11440  [
11441 \begin_inset Flex CharStyle:Code
11442 status collapsed
11443
11444 \begin_layout Plain Layout
11445
11446 \emph on
11447 0
11448 \end_layout
11449
11450 \end_inset
11451
11452 ,
11453 \begin_inset Flex CharStyle:Code
11454 status collapsed
11455
11456 \begin_layout Plain Layout
11457 1
11458 \end_layout
11459
11460 \end_inset
11461
11462 ] Set to
11463 \begin_inset Flex CharStyle:Code
11464 status collapsed
11465
11466 \begin_layout Plain Layout
11467 1
11468 \end_layout
11469
11470 \end_inset
11471
11472  if the float is already defined by the LaTeX document class.
11473  If this is set to
11474 \begin_inset Flex CharStyle:Code
11475 status collapsed
11476
11477 \begin_layout Plain Layout
11478 0
11479 \end_layout
11480
11481 \end_inset
11482
11483 , the float will be defined using the LaTeX package
11484 \begin_inset Flex CharStyle:Code
11485 status collapsed
11486
11487 \begin_layout Plain Layout
11488 float
11489 \end_layout
11490
11491 \end_inset
11492
11493 .
11494 \end_layout
11495
11496 \begin_layout Description
11497 \begin_inset Flex CharStyle:Code
11498 status collapsed
11499
11500 \begin_layout Plain Layout
11501 ListName
11502 \end_layout
11503
11504 \end_inset
11505
11506  [
11507 \begin_inset Flex CharStyle:Code
11508 status collapsed
11509
11510 \begin_layout Plain Layout
11511 string
11512 \end_layout
11513
11514 \end_inset
11515
11516 =
11517 \begin_inset Quotes erd
11518 \end_inset
11519
11520
11521 \begin_inset Quotes erd
11522 \end_inset
11523
11524 ] The heading used for the list of floats.
11525 \end_layout
11526
11527 \begin_layout Description
11528 \begin_inset Flex CharStyle:Code
11529 status collapsed
11530
11531 \begin_layout Plain Layout
11532 NumberWithin
11533 \end_layout
11534
11535 \end_inset
11536
11537  [
11538 \begin_inset Flex CharStyle:Code
11539 status collapsed
11540
11541 \begin_layout Plain Layout
11542 string
11543 \end_layout
11544
11545 \end_inset
11546
11547 =
11548 \begin_inset Quotes erd
11549 \end_inset
11550
11551
11552 \begin_inset Quotes erd
11553 \end_inset
11554
11555 ] This (optional) argument determines whether floats of this class will
11556  be numbered within some sectional unit of the document.
11557  For example, if within is equal to
11558 \begin_inset Flex CharStyle:Code
11559 status collapsed
11560
11561 \begin_layout Plain Layout
11562 chapter
11563 \end_layout
11564
11565 \end_inset
11566
11567 , the floats will be numbered within chapters.
11568
11569 \end_layout
11570
11571 \begin_layout Description
11572 \begin_inset Flex CharStyle:Code
11573 status collapsed
11574
11575 \begin_layout Plain Layout
11576 Placement
11577 \end_layout
11578
11579 \end_inset
11580
11581  [
11582 \begin_inset Flex CharStyle:Code
11583 status collapsed
11584
11585 \begin_layout Plain Layout
11586 string
11587 \end_layout
11588
11589 \end_inset
11590
11591 =
11592 \begin_inset Quotes erd
11593 \end_inset
11594
11595
11596 \begin_inset Quotes erd
11597 \end_inset
11598
11599 ] The default placement for the given class of floats.
11600  The string should be as in standard LaTeX:
11601 \begin_inset Flex CharStyle:Code
11602 status collapsed
11603
11604 \begin_layout Plain Layout
11605 t
11606 \end_layout
11607
11608 \end_inset
11609
11610 ,
11611 \begin_inset Flex CharStyle:Code
11612 status collapsed
11613
11614 \begin_layout Plain Layout
11615 b
11616 \end_layout
11617
11618 \end_inset
11619
11620 ,
11621 \begin_inset Flex CharStyle:Code
11622 status collapsed
11623
11624 \begin_layout Plain Layout
11625 p
11626 \end_layout
11627
11628 \end_inset
11629
11630  and
11631 \begin_inset Flex CharStyle:Code
11632 status collapsed
11633
11634 \begin_layout Plain Layout
11635 h
11636 \end_layout
11637
11638 \end_inset
11639
11640  for top, bottom, page, and here, respectively.
11641 \begin_inset Foot
11642 status collapsed
11643
11644 \begin_layout Plain Layout
11645 Note that the order of these letters in the string is irrelevant, like in
11646  LaTeX.
11647 \end_layout
11648
11649 \end_inset
11650
11651  On top of that there is a new type,
11652 \begin_inset Flex CharStyle:Code
11653 status collapsed
11654
11655 \begin_layout Plain Layout
11656 H
11657 \end_layout
11658
11659 \end_inset
11660
11661 , which does not really correspond to a float, since it means: put it
11662 \begin_inset Quotes eld
11663 \end_inset
11664
11665 here
11666 \begin_inset Quotes erd
11667 \end_inset
11668
11669  and nowhere else.
11670  Note however that the
11671 \begin_inset Flex CharStyle:Code
11672 status collapsed
11673
11674 \begin_layout Plain Layout
11675 H
11676 \end_layout
11677
11678 \end_inset
11679
11680  specifier is special and, because of implementation details, cannot be
11681  used in non-built in float types.
11682  If you do not understand what this means, just use
11683 \begin_inset Quotes eld
11684 \end_inset
11685
11686
11687 \begin_inset Flex CharStyle:Code
11688 status collapsed
11689
11690 \begin_layout Plain Layout
11691 tbp
11692 \end_layout
11693
11694 \end_inset
11695
11696
11697 \begin_inset Quotes erd
11698 \end_inset
11699
11700 .
11701 \end_layout
11702
11703 \begin_layout Description
11704 \begin_inset Flex CharStyle:Code
11705 status collapsed
11706
11707 \begin_layout Plain Layout
11708 Style
11709 \end_layout
11710
11711 \end_inset
11712
11713  [
11714 \begin_inset Flex CharStyle:Code
11715 status collapsed
11716
11717 \begin_layout Plain Layout
11718 string
11719 \end_layout
11720
11721 \end_inset
11722
11723 =
11724 \begin_inset Quotes erd
11725 \end_inset
11726
11727
11728 \begin_inset Quotes erd
11729 \end_inset
11730
11731 ] The style used when defining the float using
11732 \begin_inset Flex CharStyle:Code
11733 status collapsed
11734
11735 \begin_layout Plain Layout
11736
11737 \backslash
11738 newfloat
11739 \end_layout
11740
11741 \end_inset
11742
11743 .
11744 \end_layout
11745
11746 \begin_layout Description
11747 \begin_inset Flex CharStyle:Code
11748 status collapsed
11749
11750 \begin_layout Plain Layout
11751 Type
11752 \end_layout
11753
11754 \end_inset
11755
11756  [
11757 \begin_inset Flex CharStyle:Code
11758 status collapsed
11759
11760 \begin_layout Plain Layout
11761 string
11762 \end_layout
11763
11764 \end_inset
11765
11766 =
11767 \begin_inset Quotes erd
11768 \end_inset
11769
11770
11771 \begin_inset Quotes erd
11772 \end_inset
11773
11774 ] The
11775 \begin_inset Quotes eld
11776 \end_inset
11777
11778 type
11779 \begin_inset Quotes erd
11780 \end_inset
11781
11782  of the new class of floats, like program or algorithm.
11783  After the appropriate
11784 \begin_inset Flex CharStyle:Code
11785 status collapsed
11786
11787 \begin_layout Plain Layout
11788
11789 \backslash
11790 newfloat
11791 \end_layout
11792
11793 \end_inset
11794
11795 , commands such as
11796 \begin_inset Flex CharStyle:Code
11797 status collapsed
11798
11799 \begin_layout Plain Layout
11800
11801 \backslash
11802 begin{program}
11803 \end_layout
11804
11805 \end_inset
11806
11807  or
11808 \begin_inset Flex CharStyle:Code
11809 status collapsed
11810
11811 \begin_layout Plain Layout
11812
11813 \backslash
11814 end{algorithm*}
11815 \end_layout
11816
11817 \end_inset
11818
11819  will be available.
11820 \end_layout
11821
11822 \begin_layout Standard
11823 Note that defining a float with type
11824 \begin_inset Flex CharStyle:Code
11825 status collapsed
11826
11827 \begin_layout Plain Layout
11828
11829 \emph on
11830 type
11831 \end_layout
11832
11833 \end_inset
11834
11835  automatically defines the corresponding counter with name
11836 \begin_inset Flex CharStyle:Code
11837 status collapsed
11838
11839 \begin_layout Plain Layout
11840
11841 \emph on
11842 type
11843 \end_layout
11844
11845 \end_inset
11846
11847 .
11848 \end_layout
11849
11850 \begin_layout Subsection
11851 Flex insets and InsetLayout
11852 \end_layout
11853
11854 \begin_layout Standard
11855 \begin_inset CommandInset label
11856 LatexCommand label
11857 name "sec:charstyle"
11858
11859 \end_inset
11860
11861 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
11862  these are called Flex insets.
11863
11864 \end_layout
11865
11866 \begin_layout Standard
11867 Flex insets come in three different kinds:
11868 \end_layout
11869
11870 \begin_layout Itemize
11871 character style (
11872 \begin_inset Flex CharStyle:Code
11873 status collapsed
11874
11875 \begin_layout Plain Layout
11876 CharStyle
11877 \end_layout
11878
11879 \end_inset
11880
11881 ): These define semantic markup corresponding to such LaTeX commands as
11882
11883 \begin_inset Flex CharStyle:Code
11884 status collapsed
11885
11886 \begin_layout Plain Layout
11887
11888 \backslash
11889 noun
11890 \end_layout
11891
11892 \end_inset
11893
11894  and
11895 \begin_inset Flex CharStyle:Code
11896 status collapsed
11897
11898 \begin_layout Plain Layout
11899
11900 \backslash
11901 code
11902 \end_layout
11903
11904 \end_inset
11905
11906 .
11907 \end_layout
11908
11909 \begin_layout Itemize
11910 user custom (
11911 \begin_inset Flex CharStyle:Code
11912 status collapsed
11913
11914 \begin_layout Plain Layout
11915 Custom
11916 \end_layout
11917
11918 \end_inset
11919
11920 ): These can be used to define custom collapsible insets, similar to TeX
11921  code, footnote, and the like.
11922  An obvious example is an endnote inset, which is defined in the
11923 \begin_inset Flex CharStyle:Code
11924 status collapsed
11925
11926 \begin_layout Plain Layout
11927 endnote
11928 \end_layout
11929
11930 \end_inset
11931
11932  module.
11933 \end_layout
11934
11935 \begin_layout Itemize
11936 XML elements (
11937 \begin_inset Flex CharStyle:Code
11938 status collapsed
11939
11940 \begin_layout Plain Layout
11941 Element
11942 \end_layout
11943
11944 \end_inset
11945
11946 ): For use with DocBook classes.
11947 \end_layout
11948
11949 \begin_layout Standard
11950 Flex insets are defined using the
11951 \begin_inset Flex CharStyle:Code
11952 status collapsed
11953
11954 \begin_layout Plain Layout
11955 InsetLayout
11956 \end_layout
11957
11958 \end_inset
11959
11960  tag, which shall be explained in a moment.
11961 \end_layout
11962
11963 \begin_layout Standard
11964 The
11965 \begin_inset Flex CharStyle:Code
11966 status collapsed
11967
11968 \begin_layout Plain Layout
11969 InsetLayout
11970 \end_layout
11971
11972 \end_inset
11973
11974  tag also serves another function: It can be used to customize the general
11975  layout of many different types of insets.
11976  Currently,
11977 \begin_inset Flex CharStyle:Code
11978 status collapsed
11979
11980 \begin_layout Plain Layout
11981 InsetLayout
11982 \end_layout
11983
11984 \end_inset
11985
11986  can be used to customize the layout parameters for footnotes, marginal
11987  notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
11988  boxes, tables, algorithms, URLs, and optional arguments, as well as to
11989  define Flex insets.
11990 \end_layout
11991
11992 \begin_layout Standard
11993 The
11994 \begin_inset Flex CharStyle:Code
11995 status collapsed
11996
11997 \begin_layout Plain Layout
11998 InsetLayout
11999 \end_layout
12000
12001 \end_inset
12002
12003  definition must begin with a line of the form:
12004 \end_layout
12005
12006 \begin_layout LyX-Code
12007 InsetLayout <Type>
12008 \end_layout
12009
12010 \begin_layout Standard
12011 Here
12012 \begin_inset Flex CharStyle:Code
12013 status collapsed
12014
12015 \begin_layout Plain Layout
12016 <Type>
12017 \end_layout
12018
12019 \end_inset
12020
12021  indicates the inset whose layout is being defined, and here there are two
12022  cases.
12023 \end_layout
12024
12025 \begin_layout Enumerate
12026 The layout for a pre-existing inset is being modified.
12027  In this case, can be
12028 \begin_inset Flex CharStyle:Code
12029 status collapsed
12030
12031 \begin_layout Plain Layout
12032 <Type>
12033 \end_layout
12034
12035 \end_inset
12036
12037  any one of the following:
12038 \begin_inset Flex CharStyle:Code
12039 status collapsed
12040
12041 \begin_layout Plain Layout
12042 Algorithm
12043 \end_layout
12044
12045 \end_inset
12046
12047 ,
12048 \begin_inset Flex CharStyle:Code
12049 status collapsed
12050
12051 \begin_layout Plain Layout
12052 Branch
12053 \end_layout
12054
12055 \end_inset
12056
12057 ,
12058 \begin_inset Flex CharStyle:Code
12059 status collapsed
12060
12061 \begin_layout Plain Layout
12062 Box
12063 \end_layout
12064
12065 \end_inset
12066
12067 ,
12068 \begin_inset Flex CharStyle:Code
12069 status collapsed
12070
12071 \begin_layout Plain Layout
12072 Box:shaded
12073 \end_layout
12074
12075 \end_inset
12076
12077 ,
12078 \begin_inset Flex CharStyle:Code
12079 status collapsed
12080
12081 \begin_layout Plain Layout
12082 ERT
12083 \end_layout
12084
12085 \end_inset
12086
12087 ,
12088 \begin_inset Flex CharStyle:Code
12089 status collapsed
12090
12091 \begin_layout Plain Layout
12092 Figure
12093 \end_layout
12094
12095 \end_inset
12096
12097 ,
12098 \begin_inset Flex CharStyle:Code
12099 status collapsed
12100
12101 \begin_layout Plain Layout
12102 Foot
12103 \end_layout
12104
12105 \end_inset
12106
12107 ,
12108 \begin_inset Flex CharStyle:Code
12109 status collapsed
12110
12111 \begin_layout Plain Layout
12112 Index
12113 \end_layout
12114
12115 \end_inset
12116
12117 ,
12118 \begin_inset Flex CharStyle:Code
12119 status collapsed
12120
12121 \begin_layout Plain Layout
12122 Info
12123 \end_layout
12124
12125 \end_inset
12126
12127 ,
12128 \begin_inset Flex CharStyle:Code
12129 status collapsed
12130
12131 \begin_layout Plain Layout
12132 Info:menu
12133 \end_layout
12134
12135 \end_inset
12136
12137 ,
12138 \begin_inset Flex CharStyle:Code
12139 status collapsed
12140
12141 \begin_layout Plain Layout
12142 Info:shortcut
12143 \end_layout
12144
12145 \end_inset
12146
12147 ,
12148 \begin_inset Flex CharStyle:Code
12149 status collapsed
12150
12151 \begin_layout Plain Layout
12152 Info:shortcuts
12153 \end_layout
12154
12155 \end_inset
12156
12157 ,
12158 \begin_inset Flex CharStyle:Code
12159 status collapsed
12160
12161 \begin_layout Plain Layout
12162 Listings
12163 \end_layout
12164
12165 \end_inset
12166
12167 ,
12168 \begin_inset Flex CharStyle:Code
12169 status collapsed
12170
12171 \begin_layout Plain Layout
12172 Marginal
12173 \end_layout
12174
12175 \end_inset
12176
12177 ,
12178 \begin_inset Flex CharStyle:Code
12179 status collapsed
12180
12181 \begin_layout Plain Layout
12182 Note:Comment
12183 \end_layout
12184
12185 \end_inset
12186
12187 ,
12188 \begin_inset Flex CharStyle:Code
12189 status collapsed
12190
12191 \begin_layout Plain Layout
12192 Note:Note
12193 \end_layout
12194
12195 \end_inset
12196
12197 ,
12198 \begin_inset Flex CharStyle:Code
12199 status collapsed
12200
12201 \begin_layout Plain Layout
12202 Note:GreyedOut
12203 \end_layout
12204
12205 \end_inset
12206
12207 ,
12208 \begin_inset Flex CharStyle:Code
12209 status collapsed
12210
12211 \begin_layout Plain Layout
12212 OptArg
12213 \end_layout
12214
12215 \end_inset
12216
12217 ,
12218 \begin_inset Flex CharStyle:Code
12219 status collapsed
12220
12221 \begin_layout Plain Layout
12222 Table
12223 \end_layout
12224
12225 \end_inset
12226
12227 , or
12228 \begin_inset Flex CharStyle:Code
12229 status collapsed
12230
12231 \begin_layout Plain Layout
12232 URL
12233 \end_layout
12234
12235 \end_inset
12236
12237 .
12238
12239 \end_layout
12240
12241 \begin_layout Enumerate
12242 The layout for a Flex inset is being defined.
12243  In this case,
12244 \begin_inset Flex CharStyle:Code
12245 status collapsed
12246
12247 \begin_layout Plain Layout
12248 <Type>
12249 \end_layout
12250
12251 \end_inset
12252
12253  can be any valid identifier not used by a pre-existing inset.
12254  Note that the definition of a flex inset must
12255 \emph on
12256  als
12257 \emph default
12258 o include a
12259 \begin_inset Flex CharStyle:Code
12260 status collapsed
12261
12262 \begin_layout Plain Layout
12263 LyXType
12264 \end_layout
12265
12266 \end_inset
12267
12268  entry.
12269 \end_layout
12270
12271 \begin_layout Standard
12272 The
12273 \begin_inset Flex CharStyle:Code
12274 status collapsed
12275
12276 \begin_layout Plain Layout
12277 InsetLayout
12278 \end_layout
12279
12280 \end_inset
12281
12282  definition can contain the following entries:
12283 \end_layout
12284
12285 \begin_layout Description
12286 \begin_inset Flex CharStyle:Code
12287 status collapsed
12288
12289 \begin_layout Plain Layout
12290 BgColor
12291 \end_layout
12292
12293 \end_inset
12294
12295  The color for the inset's background.
12296  The valid colors are defined in
12297 \begin_inset Flex CharStyle:Code
12298 status collapsed
12299
12300 \begin_layout Plain Layout
12301 src/ColorCode.h
12302 \end_layout
12303
12304 \end_inset
12305
12306 .
12307 \end_layout
12308
12309 \begin_layout Description
12310 \begin_inset Flex CharStyle:Code
12311 status collapsed
12312
12313 \begin_layout Plain Layout
12314 CopyStyle
12315 \end_layout
12316
12317 \end_inset
12318
12319  As with paragraph styles (see page
12320 \begin_inset CommandInset ref
12321 LatexCommand ref
12322 reference "des:CopyStyle"
12323
12324 \end_inset
12325
12326 ).
12327 \end_layout
12328
12329 \begin_layout Description
12330 \begin_inset Flex CharStyle:Code
12331 status collapsed
12332
12333 \begin_layout Plain Layout
12334 CustomPars
12335 \end_layout
12336
12337 \end_inset
12338
12339  [
12340 \begin_inset Flex CharStyle:Code
12341 status collapsed
12342
12343 \begin_layout Plain Layout
12344
12345 \emph on
12346 0
12347 \end_layout
12348
12349 \end_inset
12350
12351 ,
12352 \begin_inset Flex CharStyle:Code
12353 status collapsed
12354
12355 \begin_layout Plain Layout
12356 1
12357 \end_layout
12358
12359 \end_inset
12360
12361 ] Indicates whether the user may employ the Paragraph Settings dialog to
12362  customize the paragraph.
12363 \end_layout
12364
12365 \begin_layout Description
12366 \begin_inset Flex CharStyle:Code
12367 status collapsed
12368
12369 \begin_layout Plain Layout
12370 Decoration
12371 \end_layout
12372
12373 \end_inset
12374
12375  can be
12376 \begin_inset Flex CharStyle:Code
12377 status collapsed
12378
12379 \begin_layout Plain Layout
12380 Classic
12381 \end_layout
12382
12383 \end_inset
12384
12385 ,
12386 \begin_inset Flex CharStyle:Code
12387 status collapsed
12388
12389 \begin_layout Plain Layout
12390 Minimalistic
12391 \end_layout
12392
12393 \end_inset
12394
12395 , or
12396 \begin_inset Flex CharStyle:Code
12397 status collapsed
12398
12399 \begin_layout Plain Layout
12400 Conglomerate
12401 \end_layout
12402
12403 \end_inset
12404
12405 , describing the rendering style used for the inset's frame and buttons.
12406  Footnotes generally use
12407 \begin_inset Flex CharStyle:Code
12408 status collapsed
12409
12410 \begin_layout Plain Layout
12411 Classic
12412 \end_layout
12413
12414 \end_inset
12415
12416 , ERT insets generally
12417 \begin_inset Flex CharStyle:Code
12418 status collapsed
12419
12420 \begin_layout Plain Layout
12421 Minimalistic
12422 \end_layout
12423
12424 \end_inset
12425
12426 , and character styles
12427 \begin_inset Flex CharStyle:Code
12428 status collapsed
12429
12430 \begin_layout Plain Layout
12431 Conglomerate
12432 \end_layout
12433
12434 \end_inset
12435
12436 .
12437 \end_layout
12438
12439 \begin_layout Description
12440 \begin_inset Flex CharStyle:Code
12441 status collapsed
12442
12443 \begin_layout Plain Layout
12444 End
12445 \end_layout
12446
12447 \end_inset
12448
12449  Required at the end of the InsetLayout declarations.
12450 \end_layout
12451
12452 \begin_layout Description
12453 \begin_inset Flex CharStyle:Code
12454 status collapsed
12455
12456 \begin_layout Plain Layout
12457 Font
12458 \end_layout
12459
12460 \end_inset
12461
12462  The font used for both the text body
12463 \emph on
12464 and
12465 \emph default
12466  the label.
12467  See section
12468 \begin_inset space ~
12469 \end_inset
12470
12471
12472 \begin_inset CommandInset ref
12473 LatexCommand ref
12474 reference "sec:fonts"
12475
12476 \end_inset
12477
12478 .
12479  Note that defining this font automatically defines the
12480 \begin_inset Flex CharStyle:Code
12481 status collapsed
12482
12483 \begin_layout Plain Layout
12484 LabelFont
12485 \end_layout
12486
12487 \end_inset
12488
12489  to the same value, so define this first and define
12490 \begin_inset Flex CharStyle:Code
12491 status collapsed
12492
12493 \begin_layout Plain Layout
12494 LabelFont
12495 \end_layout
12496
12497 \end_inset
12498
12499  later if you want them to be different.
12500 \end_layout
12501
12502 \begin_layout Description
12503 \begin_inset Flex CharStyle:Code
12504 status collapsed
12505
12506 \begin_layout Plain Layout
12507 ForceLTR
12508 \end_layout
12509
12510 \end_inset
12511
12512  Force the
12513 \begin_inset Quotes eld
12514 \end_inset
12515
12516 latex
12517 \begin_inset Quotes erd
12518 \end_inset
12519
12520  language, leading to Left-to-Right (latin) output, e.
12521 \begin_inset space \thinspace{}
12522 \end_inset
12523
12524 g.
12525 \begin_inset space \space{}
12526 \end_inset
12527
12528 in TeX code or URL.
12529  A kludge.
12530 \end_layout
12531
12532 \begin_layout Description
12533 \begin_inset Flex CharStyle:Code
12534 status collapsed
12535
12536 \begin_layout Plain Layout
12537 ForcePlain
12538 \end_layout
12539
12540 \end_inset
12541
12542  [
12543 \begin_inset Flex CharStyle:Code
12544 status collapsed
12545
12546 \begin_layout Plain Layout
12547
12548 \emph on
12549 0
12550 \end_layout
12551
12552 \end_inset
12553
12554 ,
12555 \begin_inset Flex CharStyle:Code
12556 status collapsed
12557
12558 \begin_layout Plain Layout
12559 1
12560 \end_layout
12561
12562 \end_inset
12563
12564 ] Indicates whether the PlainLayout should be used or, instead, the user
12565  can change the paragraph style used in the inset.
12566 \end_layout
12567
12568 \begin_layout Description
12569 \begin_inset Flex CharStyle:Code
12570 status collapsed
12571
12572 \begin_layout Plain Layout
12573 FreeSpacing
12574 \end_layout
12575
12576 \end_inset
12577
12578  As with paragraph styles (see page
12579 \begin_inset CommandInset ref
12580 LatexCommand pageref
12581 reference "des:FreeSpacing"
12582
12583 \end_inset
12584
12585 ).
12586 \end_layout
12587
12588 \begin_layout Description
12589 \begin_inset Flex CharStyle:Code
12590 status collapsed
12591
12592 \begin_layout Plain Layout
12593 InToc
12594 \end_layout
12595
12596 \end_inset
12597
12598  [
12599 \begin_inset Flex CharStyle:Code
12600 status collapsed
12601
12602 \begin_layout Plain Layout
12603
12604 \emph on
12605 0
12606 \end_layout
12607
12608 \end_inset
12609
12610 ,
12611 \begin_inset Flex CharStyle:Code
12612 status collapsed
12613
12614 \begin_layout Plain Layout
12615 1
12616 \end_layout
12617
12618 \end_inset
12619
12620 ] Whether to include the contents of this inset in the strings generated
12621  for the `Outline' pane.
12622  One would not, for example, want the content of a footnote in a section
12623  header to be included in the TOC displayed in the outline, but one would
12624  normally want the content of a character style displayed.
12625  Default is false: not to include.
12626 \end_layout
12627
12628 \begin_layout Description
12629 \begin_inset Flex CharStyle:Code
12630 status collapsed
12631
12632 \begin_layout Plain Layout
12633 KeepEmpty
12634 \end_layout
12635
12636 \end_inset
12637
12638  As with paragraph styles (see page
12639 \begin_inset CommandInset ref
12640 LatexCommand pageref
12641 reference "des:KeepEmpty"
12642
12643 \end_inset
12644
12645 ).
12646 \end_layout
12647
12648 \begin_layout Description
12649 \begin_inset Flex CharStyle:Code
12650 status collapsed
12651
12652 \begin_layout Plain Layout
12653 LabelFont
12654 \end_layout
12655
12656 \end_inset
12657
12658  The font used for the label.
12659  See section
12660 \begin_inset space ~
12661 \end_inset
12662
12663
12664 \begin_inset CommandInset ref
12665 LatexCommand ref
12666 reference "sec:fonts"
12667
12668 \end_inset
12669
12670 .
12671  Note that this definition can never appear before
12672 \begin_inset Flex CharStyle:Code
12673 status collapsed
12674
12675 \begin_layout Plain Layout
12676 Font
12677 \end_layout
12678
12679 \end_inset
12680
12681 , lest it be ineffective.
12682 \end_layout
12683
12684 \begin_layout Description
12685 \begin_inset Flex CharStyle:Code
12686 status collapsed
12687
12688 \begin_layout Plain Layout
12689 LabelString
12690 \end_layout
12691
12692 \end_inset
12693
12694  What will be displayed on the button or elsewhere as the inset label.
12695  Some inset types (TeX code and Branch) modify this label on the fly.
12696 \end_layout
12697
12698 \begin_layout Description
12699 \begin_inset Flex CharStyle:Code
12700 status collapsed
12701
12702 \begin_layout Plain Layout
12703 LatexName
12704 \end_layout
12705
12706 \end_inset
12707
12708  The name of the corresponding LaTeX stuff.
12709  Either the environment or command name.
12710 \end_layout
12711
12712 \begin_layout Description
12713 \begin_inset Flex CharStyle:Code
12714 status collapsed
12715
12716 \begin_layout Plain Layout
12717 LatexParam
12718 \end_layout
12719
12720 \end_inset
12721
12722  The optional parameter for the corresponding
12723 \begin_inset Flex CharStyle:Code
12724 status collapsed
12725
12726 \begin_layout Plain Layout
12727 LatexName
12728 \end_layout
12729
12730 \end_inset
12731
12732  stuff, including possible bracket pairs like
12733 \begin_inset Flex CharStyle:Code
12734 status collapsed
12735
12736 \begin_layout Plain Layout
12737 []
12738 \end_layout
12739
12740 \end_inset
12741
12742 .
12743  This parameter cannot be changed from within LyX.
12744 \end_layout
12745
12746 \begin_layout Description
12747 \begin_inset Flex CharStyle:Code
12748 status collapsed
12749
12750 \begin_layout Plain Layout
12751 LatexType
12752 \end_layout
12753
12754 \end_inset
12755
12756  As with paragraph styles (see page
12757 \begin_inset CommandInset ref
12758 LatexCommand pageref
12759 reference "des:LatexType"
12760
12761 \end_inset
12762
12763 ).
12764 \end_layout
12765
12766 \begin_layout Description
12767 \begin_inset Flex CharStyle:Code
12768 status collapsed
12769
12770 \begin_layout Plain Layout
12771 LyxType
12772 \end_layout
12773
12774 \end_inset
12775
12776  Can be
12777 \begin_inset Flex CharStyle:Code
12778 status collapsed
12779
12780 \begin_layout Plain Layout
12781 charstyle
12782 \end_layout
12783
12784 \end_inset
12785
12786 ,
12787 \begin_inset Flex CharStyle:Code
12788 status collapsed
12789
12790 \begin_layout Plain Layout
12791 custom
12792 \end_layout
12793
12794 \end_inset
12795
12796 ,
12797 \begin_inset Flex CharStyle:Code
12798 status collapsed
12799
12800 \begin_layout Plain Layout
12801 element
12802 \end_layout
12803
12804 \end_inset
12805
12806 , or
12807 \begin_inset Flex CharStyle:Code
12808 status collapsed
12809
12810 \begin_layout Plain Layout
12811 end
12812 \end_layout
12813
12814 \end_inset
12815
12816  (indicating a dummy definition ending definitions of charstyles, etc).
12817  This entry is required in and is only meaningful for Flex insets.
12818  Among other things, it determines on which menu this inset will appear.
12819 \end_layout
12820
12821 \begin_layout Description
12822 \begin_inset Flex CharStyle:Code
12823 status collapsed
12824
12825 \begin_layout Plain Layout
12826 MultiPar
12827 \end_layout
12828
12829 \end_inset
12830
12831  [
12832 \begin_inset Flex CharStyle:Code
12833 status collapsed
12834
12835 \begin_layout Plain Layout
12836
12837 \emph on
12838 0
12839 \end_layout
12840
12841 \end_inset
12842
12843 ,
12844 \begin_inset Flex CharStyle:Code
12845 status collapsed
12846
12847 \begin_layout Plain Layout
12848 1
12849 \end_layout
12850
12851 \end_inset
12852
12853 ] Whether multiple paragraphs are permitted in this inset.
12854  This will also set CustomPars to the same value and ForcePlain to the opposite
12855  value.
12856  These can be reset to other values, if they are used
12857 \emph on
12858 after
12859 \emph default
12860  MultiPar.
12861 \end_layout
12862
12863 \begin_layout Description
12864 \begin_inset Flex CharStyle:Code
12865 status collapsed
12866
12867 \begin_layout Plain Layout
12868 NeedProtect
12869 \end_layout
12870
12871 \end_inset
12872
12873  [
12874 \begin_inset Flex CharStyle:Code
12875 status collapsed
12876
12877 \begin_layout Plain Layout
12878
12879 \emph on
12880 0
12881 \end_layout
12882
12883 \end_inset
12884
12885 ,
12886 \begin_inset Flex CharStyle:Code
12887 status collapsed
12888
12889 \begin_layout Plain Layout
12890 1
12891 \end_layout
12892
12893 \end_inset
12894
12895 ] Whether fragile commands in this layout should be
12896 \begin_inset Flex CharStyle:Code
12897 status collapsed
12898
12899 \begin_layout Plain Layout
12900
12901 \backslash
12902 protect
12903 \end_layout
12904
12905 \end_inset
12906
12907 'ed.
12908  (Note: This is
12909 \emph on
12910 not
12911 \emph default
12912  whether the command should itself be protected.)
12913 \end_layout
12914
12915 \begin_layout Description
12916 \begin_inset Flex CharStyle:Code
12917 status collapsed
12918
12919 \begin_layout Plain Layout
12920 PassThru
12921 \end_layout
12922
12923 \end_inset
12924
12925  [
12926 \begin_inset Flex CharStyle:Code
12927 status collapsed
12928
12929 \begin_layout Plain Layout
12930
12931 \emph on
12932 0
12933 \end_layout
12934
12935 \end_inset
12936
12937 ,
12938 \begin_inset Flex CharStyle:Code
12939 status collapsed
12940
12941 \begin_layout Plain Layout
12942 1
12943 \end_layout
12944
12945 \end_inset
12946
12947 ] As with paragraph styles (see page
12948 \begin_inset CommandInset ref
12949 LatexCommand ref
12950 reference "des:PathThru"
12951
12952 \end_inset
12953
12954 ).
12955 \end_layout
12956
12957 \begin_layout Description
12958 \begin_inset Flex CharStyle:Code
12959 status collapsed
12960
12961 \begin_layout Plain Layout
12962 Preamble
12963 \end_layout
12964
12965 \end_inset
12966
12967  As with paragraph styles (see page
12968 \begin_inset CommandInset ref
12969 LatexCommand pageref
12970 reference "des:Preamble"
12971
12972 \end_inset
12973
12974 ).
12975 \end_layout
12976
12977 \begin_layout Description
12978 \begin_inset Flex CharStyle:Code
12979 status collapsed
12980
12981 \begin_layout Plain Layout
12982 Requires
12983 \end_layout
12984
12985 \end_inset
12986
12987  [
12988 \begin_inset Flex CharStyle:Code
12989 status collapsed
12990
12991 \begin_layout Plain Layout
12992 string
12993 \end_layout
12994
12995 \end_inset
12996
12997 ] As with paragraph styles (see page
12998 \begin_inset CommandInset ref
12999 LatexCommand pageref
13000 reference "des:Requires"
13001
13002 \end_inset
13003
13004 ).
13005 \end_layout
13006
13007 \begin_layout Subsection
13008 Counters
13009 \end_layout
13010
13011 \begin_layout Standard
13012 \begin_inset CommandInset label
13013 LatexCommand label
13014 name "sec:counter"
13015
13016 \end_inset
13017
13018 Since version 1.3.0 of LyX, it is both possible and necessary to define the
13019  counters (
13020 \begin_inset Flex CharStyle:MenuItem
13021 status collapsed
13022
13023 \begin_layout Plain Layout
13024 chapter
13025 \end_layout
13026
13027 \end_inset
13028
13029 ,
13030 \begin_inset Flex CharStyle:MenuItem
13031 status collapsed
13032
13033 \begin_layout Plain Layout
13034 figure
13035 \end_layout
13036
13037 \end_inset
13038
13039 , \SpecialChar \ldots{}
13040 ) in the text class itself.
13041  The standard counters are defined in the file
13042 \begin_inset Flex CharStyle:Code
13043 status collapsed
13044
13045 \begin_layout Plain Layout
13046 stdcounters.inc
13047 \end_layout
13048
13049 \end_inset
13050
13051 , so you may have to do no more than add
13052 \end_layout
13053
13054 \begin_layout LyX-Code
13055 Input stdcounters.inc
13056 \end_layout
13057
13058 \begin_layout Standard
13059 to your layout file to get them to work.
13060  But if you want to define custom counters, then you can do so.
13061  The counter declaration must begin with:
13062 \end_layout
13063
13064 \begin_layout LyX-Code
13065 Counter name
13066 \end_layout
13067
13068 \begin_layout Standard
13069 where of course `name' is replaced by the name of the counter.
13070  And it must end with
13071 \begin_inset Quotes eld
13072 \end_inset
13073
13074
13075 \begin_inset Flex CharStyle:Code
13076 status collapsed
13077
13078 \begin_layout Plain Layout
13079 End
13080 \end_layout
13081
13082 \end_inset
13083
13084
13085 \begin_inset Quotes erd
13086 \end_inset
13087
13088 .
13089  The following parameters can also be used:
13090 \end_layout
13091
13092 \begin_layout Description
13093 \begin_inset Flex CharStyle:Code
13094 status collapsed
13095
13096 \begin_layout Plain Layout
13097 LabelString [string=""]
13098 \end_layout
13099
13100 \end_inset
13101
13102  when this is defined, this string defines how the counter is displayed.
13103  Setting this value sets
13104 \begin_inset Flex CharStyle:Code
13105 status collapsed
13106
13107 \begin_layout Plain Layout
13108 LabelStringAppendix
13109 \end_layout
13110
13111 \end_inset
13112
13113  to the same value.
13114  The following special constructs can be used in the string:
13115 \end_layout
13116
13117 \begin_deeper
13118 \begin_layout Itemize
13119 \begin_inset Flex CharStyle:Code
13120 status collapsed
13121
13122 \begin_layout Plain Layout
13123
13124 \backslash
13125 thecounter
13126 \end_layout
13127
13128 \end_inset
13129
13130  will be replaced by the expansion of the
13131 \begin_inset Flex CharStyle:Code
13132 status collapsed
13133
13134 \begin_layout Plain Layout
13135 LabelString
13136 \end_layout
13137
13138 \end_inset
13139
13140  (or
13141 \begin_inset Flex CharStyle:Code
13142 status collapsed
13143
13144 \begin_layout Plain Layout
13145 LabelStringAppendix
13146 \end_layout
13147
13148 \end_inset
13149
13150 ) of the counter
13151 \begin_inset Flex CharStyle:Code
13152 status collapsed
13153
13154 \begin_layout Plain Layout
13155 counter
13156 \end_layout
13157
13158 \end_inset
13159
13160 .
13161
13162 \end_layout
13163
13164 \begin_layout Itemize
13165 counter values can be expressed using LaTeX-like macros
13166 \begin_inset Flex CharStyle:Code
13167 status collapsed
13168
13169 \begin_layout Plain Layout
13170
13171 \backslash
13172
13173 \emph on
13174 numbertype
13175 \emph default
13176 {
13177 \emph on
13178 counter
13179 \emph default
13180 }
13181 \end_layout
13182
13183 \end_inset
13184
13185 , where
13186 \begin_inset Flex CharStyle:Code
13187 status collapsed
13188
13189 \begin_layout Plain Layout
13190
13191 \emph on
13192 numbertype
13193 \end_layout
13194
13195 \end_inset
13196
13197  can be:
13198 \begin_inset Foot
13199 status collapsed
13200
13201 \begin_layout Plain Layout
13202
13203 \family roman
13204 \series medium
13205 \shape up
13206 \size normal
13207 \emph off
13208 \bar no
13209 \noun off
13210 \color none
13211 Actually, the situation is a bit more complicated: any
13212 \family default
13213 \series default
13214 \shape default
13215 \emph default
13216 \bar default
13217
13218 \size default
13219 \emph on
13220 \noun default
13221 \color inherit
13222 numbertype
13223 \family roman
13224 \series medium
13225 \shape up
13226 \size normal
13227 \emph off
13228 \bar no
13229 \noun off
13230  other than those described below will produce arabic numerals.
13231  It would not be surprising to see this change in the future.
13232 \end_layout
13233
13234 \end_inset
13235
13236
13237 \begin_inset Flex CharStyle:Code
13238 status collapsed
13239
13240 \begin_layout Plain Layout
13241 arabic
13242 \end_layout
13243
13244 \end_inset
13245
13246 : 1, 2, 3,\SpecialChar \ldots{}
13247 ;
13248 \begin_inset Flex CharStyle:Code
13249 status collapsed
13250
13251 \begin_layout Plain Layout
13252 alph
13253 \end_layout
13254
13255 \end_inset
13256
13257  for lower-case letters: a, b, c, \SpecialChar \ldots{}
13258 ;
13259 \begin_inset Flex CharStyle:Code
13260 status collapsed
13261
13262 \begin_layout Plain Layout
13263 Alph
13264 \end_layout
13265
13266 \end_inset
13267
13268  for upper-case letters: A, B, C, \SpecialChar \ldots{}
13269 ;
13270 \begin_inset Flex CharStyle:Code
13271 status collapsed
13272
13273 \begin_layout Plain Layout
13274 roman
13275 \end_layout
13276
13277 \end_inset
13278
13279  for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
13280 ;
13281 \begin_inset Flex CharStyle:Code
13282 status collapsed
13283
13284 \begin_layout Plain Layout
13285 Roman
13286 \end_layout
13287
13288 \end_inset
13289
13290  for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
13291 ;
13292 \begin_inset Flex CharStyle:Code
13293 status collapsed
13294
13295 \begin_layout Plain Layout
13296 hebrew
13297 \end_layout
13298
13299 \end_inset
13300
13301  for hebrew numerals.
13302 \end_layout
13303
13304 \end_deeper
13305 \begin_layout Standard
13306 If LabelString is not defined, a default value is constructed as follows:
13307  if the counter has a master counter
13308 \begin_inset Flex CharStyle:Code
13309 status collapsed
13310
13311 \begin_layout Plain Layout
13312 master
13313 \end_layout
13314
13315 \end_inset
13316
13317  (defined via
13318 \begin_inset Flex CharStyle:Code
13319 status collapsed
13320
13321 \begin_layout Plain Layout
13322 Within
13323 \end_layout
13324
13325 \end_inset
13326
13327 ), the string
13328 \begin_inset Flex CharStyle:Code
13329 status collapsed
13330
13331 \begin_layout Plain Layout
13332
13333 \backslash
13334 themaster.
13335 \backslash
13336 arabic{counter}
13337 \end_layout
13338
13339 \end_inset
13340
13341  is used; otherwise the string
13342 \begin_inset Flex CharStyle:Code
13343 status collapsed
13344
13345 \begin_layout Plain Layout
13346
13347 \backslash
13348 arabic{counter}
13349 \end_layout
13350
13351 \end_inset
13352
13353  is used.
13354 \end_layout
13355
13356 \begin_layout Description
13357 \begin_inset Flex CharStyle:Code
13358 status collapsed
13359
13360 \begin_layout Plain Layout
13361 LabelStringAppendix [string=""]
13362 \end_layout
13363
13364 \end_inset
13365
13366  Same as
13367 \begin_inset Flex CharStyle:Code
13368 status collapsed
13369
13370 \begin_layout Plain Layout
13371 LabelString
13372 \end_layout
13373
13374 \end_inset
13375
13376 , but for use in the Appendix.
13377 \end_layout
13378
13379 \begin_layout Description
13380 \begin_inset Flex CharStyle:Code
13381 status collapsed
13382
13383 \begin_layout Plain Layout
13384 Within
13385 \end_layout
13386
13387 \end_inset
13388
13389  [
13390 \begin_inset Flex CharStyle:Code
13391 status collapsed
13392
13393 \begin_layout Plain Layout
13394 string
13395 \end_layout
13396
13397 \end_inset
13398
13399 =
13400 \begin_inset Quotes erd
13401 \end_inset
13402
13403
13404 \begin_inset Quotes erd
13405 \end_inset
13406
13407 ] If this is set to the name of another counter, the present counter will
13408  be reset every time the other one is increased.
13409  For example,
13410 \begin_inset Flex CharStyle:Code
13411 status collapsed
13412
13413 \begin_layout Plain Layout
13414 subsection
13415 \end_layout
13416
13417 \end_inset
13418
13419  is numbered inside
13420 \begin_inset Flex CharStyle:Code
13421 status collapsed
13422
13423 \begin_layout Plain Layout
13424 section
13425 \end_layout
13426
13427 \end_inset
13428
13429 .
13430 \end_layout
13431
13432 \begin_layout Subsection
13433 Font description
13434 \end_layout
13435
13436 \begin_layout Standard
13437 \begin_inset CommandInset label
13438 LatexCommand label
13439 name "sec:fonts"
13440
13441 \end_inset
13442
13443 A font description looks like this:
13444 \end_layout
13445
13446 \begin_layout LyX-Code
13447 Font
13448 \family roman
13449 \emph on
13450 or
13451 \family default
13452 \emph default
13453  LabelFont
13454 \end_layout
13455
13456 \begin_layout LyX-Code
13457  ...
13458 \end_layout
13459
13460 \begin_layout LyX-Code
13461 EndFont
13462 \end_layout
13463
13464 \begin_layout Standard
13465 The following commands are available:
13466 \end_layout
13467
13468 \begin_layout Description
13469 \begin_inset Flex CharStyle:Code
13470 status collapsed
13471
13472 \begin_layout Plain Layout
13473 Color
13474 \end_layout
13475
13476 \end_inset
13477
13478  [
13479 \begin_inset Flex CharStyle:Code
13480 status collapsed
13481
13482 \begin_layout Plain Layout
13483
13484 \emph on
13485 none
13486 \end_layout
13487
13488 \end_inset
13489
13490 ,
13491 \begin_inset Flex CharStyle:Code
13492 status collapsed
13493
13494 \begin_layout Plain Layout
13495 black
13496 \end_layout
13497
13498 \end_inset
13499
13500 ,
13501 \begin_inset Flex CharStyle:Code
13502 status collapsed
13503
13504 \begin_layout Plain Layout
13505 white
13506 \end_layout
13507
13508 \end_inset
13509
13510 ,
13511 \begin_inset Flex CharStyle:Code
13512 status collapsed
13513
13514 \begin_layout Plain Layout
13515 red
13516 \end_layout
13517
13518 \end_inset
13519
13520 ,
13521 \begin_inset Flex CharStyle:Code
13522 status collapsed
13523
13524 \begin_layout Plain Layout
13525 green
13526 \end_layout
13527
13528 \end_inset
13529
13530 ,
13531 \begin_inset Flex CharStyle:Code
13532 status collapsed
13533
13534 \begin_layout Plain Layout
13535 blue
13536 \end_layout
13537
13538 \end_inset
13539
13540 ,
13541 \begin_inset Flex CharStyle:Code
13542 status collapsed
13543
13544 \begin_layout Plain Layout
13545 cyan
13546 \end_layout
13547
13548 \end_inset
13549
13550 ,
13551 \begin_inset Flex CharStyle:Code
13552 status collapsed
13553
13554 \begin_layout Plain Layout
13555 magenta
13556 \end_layout
13557
13558 \end_inset
13559
13560 ,
13561 \begin_inset Flex CharStyle:Code
13562 status collapsed
13563
13564 \begin_layout Plain Layout
13565 yellow
13566 \end_layout
13567
13568 \end_inset
13569
13570 ]
13571 \end_layout
13572
13573 \begin_layout Description
13574 \begin_inset Flex CharStyle:Code
13575 status collapsed
13576
13577 \begin_layout Plain Layout
13578 Family
13579 \end_layout
13580
13581 \end_inset
13582
13583  [
13584 \emph on
13585
13586 \begin_inset Flex CharStyle:Code
13587 status collapsed
13588
13589 \begin_layout Plain Layout
13590
13591 \emph on
13592 Roman
13593 \end_layout
13594
13595 \end_inset
13596
13597
13598 \emph default
13599 ,
13600 \begin_inset Flex CharStyle:Code
13601 status collapsed
13602
13603 \begin_layout Plain Layout
13604 Sans
13605 \end_layout
13606
13607 \end_inset
13608
13609 ,
13610 \begin_inset Flex CharStyle:Code
13611 status collapsed
13612
13613 \begin_layout Plain Layout
13614 Typewriter
13615 \end_layout
13616
13617 \end_inset
13618
13619 ]
13620 \end_layout
13621
13622 \begin_layout Description
13623 \begin_inset Flex CharStyle:Code
13624 status collapsed
13625
13626 \begin_layout Plain Layout
13627 Misc
13628 \end_layout
13629
13630 \end_inset
13631
13632  [
13633 \begin_inset Flex CharStyle:Code
13634 status collapsed
13635
13636 \begin_layout Plain Layout
13637 string
13638 \end_layout
13639
13640 \end_inset
13641
13642 ] Valid argument are:
13643 \begin_inset Flex CharStyle:Code
13644 status collapsed
13645
13646 \begin_layout Plain Layout
13647 emph
13648 \end_layout
13649
13650 \end_inset
13651
13652 ,
13653 \begin_inset Flex CharStyle:Code
13654 status collapsed
13655
13656 \begin_layout Plain Layout
13657 noun
13658 \end_layout
13659
13660 \end_inset
13661
13662 ,
13663 \begin_inset Flex CharStyle:Code
13664 status collapsed
13665
13666 \begin_layout Plain Layout
13667 underbar
13668 \end_layout
13669
13670 \end_inset
13671
13672 ,
13673 \begin_inset Flex CharStyle:Code
13674 status collapsed
13675
13676 \begin_layout Plain Layout
13677 no_emph
13678 \end_layout
13679
13680 \end_inset
13681
13682 ,
13683 \begin_inset Flex CharStyle:Code
13684 status collapsed
13685
13686 \begin_layout Plain Layout
13687 no_noun
13688 \end_layout
13689
13690 \end_inset
13691
13692  and
13693 \begin_inset Flex CharStyle:Code
13694 status collapsed
13695
13696 \begin_layout Plain Layout
13697 no_bar
13698 \end_layout
13699
13700 \end_inset
13701
13702 .
13703  Each of these turns on or off the corresponding attribute.
13704 \end_layout
13705
13706 \begin_layout Description
13707 \begin_inset Flex CharStyle:Code
13708 status collapsed
13709
13710 \begin_layout Plain Layout
13711 Series
13712 \end_layout
13713
13714 \end_inset
13715
13716  [
13717 \emph on
13718
13719 \begin_inset Flex CharStyle:Code
13720 status collapsed
13721
13722 \begin_layout Plain Layout
13723
13724 \emph on
13725 Medium
13726 \end_layout
13727
13728 \end_inset
13729
13730
13731 \emph default
13732 ,
13733 \begin_inset Flex CharStyle:Code
13734 status collapsed
13735
13736 \begin_layout Plain Layout
13737 Bold
13738 \end_layout
13739
13740 \end_inset
13741
13742 ]
13743 \end_layout
13744
13745 \begin_layout Description
13746 \begin_inset Flex CharStyle:Code
13747 status collapsed
13748
13749 \begin_layout Plain Layout
13750 Shape
13751 \end_layout
13752
13753 \end_inset
13754
13755  [
13756 \emph on
13757
13758 \begin_inset Flex CharStyle:Code
13759 status collapsed
13760
13761 \begin_layout Plain Layout
13762
13763 \emph on
13764 Up
13765 \end_layout
13766
13767 \end_inset
13768
13769
13770 \emph default
13771 ,
13772 \begin_inset Flex CharStyle:Code
13773 status collapsed
13774
13775 \begin_layout Plain Layout
13776 Italic
13777 \end_layout
13778
13779 \end_inset
13780
13781 ,
13782 \begin_inset Flex CharStyle:Code
13783 status collapsed
13784
13785 \begin_layout Plain Layout
13786 SmallCaps
13787 \end_layout
13788
13789 \end_inset
13790
13791 ,
13792 \begin_inset Flex CharStyle:Code
13793 status collapsed
13794
13795 \begin_layout Plain Layout
13796 Slanted
13797 \end_layout
13798
13799 \end_inset
13800
13801 ]
13802 \end_layout
13803
13804 \begin_layout Description
13805 \begin_inset Flex CharStyle:Code
13806 status collapsed
13807
13808 \begin_layout Plain Layout
13809 Size
13810 \end_layout
13811
13812 \end_inset
13813
13814  [
13815 \begin_inset Flex CharStyle:Code
13816 status collapsed
13817
13818 \begin_layout Plain Layout
13819 tiny
13820 \end_layout
13821
13822 \end_inset
13823
13824 ,
13825 \begin_inset Flex CharStyle:Code
13826 status collapsed
13827
13828 \begin_layout Plain Layout
13829 small
13830 \end_layout
13831
13832 \end_inset
13833
13834 ,
13835 \begin_inset Flex CharStyle:Code
13836 status collapsed
13837
13838 \begin_layout Plain Layout
13839
13840 \emph on
13841 normal
13842 \end_layout
13843
13844 \end_inset
13845
13846 ,
13847 \begin_inset Flex CharStyle:Code
13848 status collapsed
13849
13850 \begin_layout Plain Layout
13851 large
13852 \end_layout
13853
13854 \end_inset
13855
13856 ,
13857 \begin_inset Flex CharStyle:Code
13858 status collapsed
13859
13860 \begin_layout Plain Layout
13861 larger
13862 \end_layout
13863
13864 \end_inset
13865
13866 ,
13867 \begin_inset Flex CharStyle:Code
13868 status collapsed
13869
13870 \begin_layout Plain Layout
13871 largest
13872 \end_layout
13873
13874 \end_inset
13875
13876 ,
13877 \begin_inset Flex CharStyle:Code
13878 status collapsed
13879
13880 \begin_layout Plain Layout
13881 huge
13882 \end_layout
13883
13884 \end_inset
13885
13886 ,
13887 \begin_inset Flex CharStyle:Code
13888 status collapsed
13889
13890 \begin_layout Plain Layout
13891 giant
13892 \end_layout
13893
13894 \end_inset
13895
13896 ]
13897 \end_layout
13898
13899 \begin_layout Subsection
13900 Upgrading old layout files
13901 \end_layout
13902
13903 \begin_layout Standard
13904 The file format of layout files changes from time to time, so old layout
13905  files need to be converted.
13906  This process has been automated since LyX 1.4.0: If LyX reads an old format
13907  layout file it will call the conversion tool
13908 \begin_inset Flex CharStyle:Code
13909 status collapsed
13910
13911 \begin_layout Plain Layout
13912 LyXDir/scripts/layout2layout.py
13913 \end_layout
13914
13915 \end_inset
13916
13917  and convert it to a temporary file in current format.
13918  The original file is left untouched.
13919  If you want to convert the layout file permanently, just call the converter
13920  by hand:
13921 \end_layout
13922
13923 \begin_layout LyX-Code
13924 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13925 \end_layout
13926
13927 \begin_layout Standard
13928 (You need to replace
13929 \begin_inset Flex CharStyle:Code
13930 status collapsed
13931
13932 \begin_layout Plain Layout
13933 $LyXDir
13934 \end_layout
13935
13936 \end_inset
13937
13938  with the name of your LyX system directory, unless you happen to have defined
13939  such an environment variable.) Then copy
13940 \begin_inset Flex CharStyle:Code
13941 status collapsed
13942
13943 \begin_layout Plain Layout
13944 myclassnew.layout
13945 \end_layout
13946
13947 \end_inset
13948
13949  to
13950 \begin_inset Flex CharStyle:Code
13951 status collapsed
13952
13953 \begin_layout Plain Layout
13954 UserDir/layouts/
13955 \end_layout
13956
13957 \end_inset
13958
13959 .
13960 \end_layout
13961
13962 \begin_layout Standard
13963 The automatic conversion only handles syntax changes.
13964  It cannot handle the case where the contents of included files was changed,
13965  so these will have to be converted separately.
13966 \end_layout
13967
13968 \begin_layout Section
13969 Creating Templates
13970 \begin_inset CommandInset label
13971 LatexCommand label
13972 name "sec:templates"
13973
13974 \end_inset
13975
13976
13977 \end_layout
13978
13979 \begin_layout Standard
13980 Templates are created just like usual documents.
13981  The only difference is that usual documents contain all possible settings,
13982  including the font scheme and the paper size.
13983  Usually a user doesn't want a template to overwrite his defaults in these
13984  cases.
13985  For that reason, the designer of a template should remove the corresponding
13986  commands like
13987 \begin_inset Flex CharStyle:Code
13988 status collapsed
13989
13990 \begin_layout Plain Layout
13991
13992 \backslash
13993 fontscheme
13994 \end_layout
13995
13996 \end_inset
13997
13998  or
13999 \begin_inset Flex CharStyle:Code
14000 status collapsed
14001
14002 \begin_layout Plain Layout
14003
14004 \backslash
14005 papersize
14006 \end_layout
14007
14008 \end_inset
14009
14010  from the template LyX file.
14011  This can be done with any simple text-editor, for example
14012 \begin_inset Flex CharStyle:Code
14013 status collapsed
14014
14015 \begin_layout Plain Layout
14016 vi
14017 \end_layout
14018
14019 \end_inset
14020
14021  or
14022 \begin_inset Flex CharStyle:Code
14023 status collapsed
14024
14025 \begin_layout Plain Layout
14026 xedit
14027 \end_layout
14028
14029 \end_inset
14030
14031 .
14032
14033 \end_layout
14034
14035 \begin_layout Standard
14036 Put the edited template files you create in
14037 \begin_inset Flex CharStyle:Code
14038 status collapsed
14039
14040 \begin_layout Plain Layout
14041 UserDir/templates/
14042 \end_layout
14043
14044 \end_inset
14045
14046 , copy the ones you use from the global template directory in
14047 \begin_inset Flex CharStyle:Code
14048 status collapsed
14049
14050 \begin_layout Plain Layout
14051 LyXDir/templates/
14052 \end_layout
14053
14054 \end_inset
14055
14056  to the same place, and redefine the template path in the
14057 \begin_inset Flex CharStyle:MenuItem
14058 status collapsed
14059
14060 \begin_layout Plain Layout
14061 Tools\SpecialChar \menuseparator
14062 Preferences\SpecialChar \menuseparator
14063 Paths
14064 \end_layout
14065
14066 \end_inset
14067
14068  dialog.
14069 \end_layout
14070
14071 \begin_layout Standard
14072 Note that there is a template which has a particular meaning:
14073 \begin_inset Flex CharStyle:Code
14074 status collapsed
14075
14076 \begin_layout Plain Layout
14077 defaults.lyx
14078 \end_layout
14079
14080 \end_inset
14081
14082 .
14083  This template is loaded every time you create a new document with
14084 \begin_inset Flex CharStyle:MenuItem
14085 status collapsed
14086
14087 \begin_layout Plain Layout
14088 File\SpecialChar \menuseparator
14089 New
14090 \end_layout
14091
14092 \end_inset
14093
14094  in order to provide useful defaults.
14095  To create this template from inside LyX, all you have to do is to open
14096  a document with the correct settings, and use the
14097 \begin_inset Flex CharStyle:MenuItem
14098 status collapsed
14099
14100 \begin_layout Plain Layout
14101 Save as Document Defaults
14102 \end_layout
14103
14104 \end_inset
14105
14106  button.
14107 \end_layout
14108
14109 \begin_layout Chapter
14110 Including External Material
14111 \end_layout
14112
14113 \begin_layout Standard
14114 \begin_inset Box Shadowbox
14115 position "t"
14116 hor_pos "c"
14117 has_inner_box 1
14118 inner_pos "t"
14119 use_parbox 0
14120 width "100col%"
14121 special "none"
14122 height "1in"
14123 height_special "totalheight"
14124 status open
14125
14126 \begin_layout Plain Layout
14127 WARNING: This portion of the documentation has not been updated for some
14128  time.
14129  We certainly hope that it is still accurate, but there are no guarantees.
14130 \end_layout
14131
14132 \end_inset
14133
14134
14135 \end_layout
14136
14137 \begin_layout Standard
14138 The use of material from sources external to LyX is covered in detail in
14139  the
14140 \emph on
14141 Embedded Objects
14142 \emph default
14143  manual.
14144  This part of the manual covers what needs to happen behind the scenes for
14145  new sorts of material to be included.
14146 \end_layout
14147
14148 \begin_layout Section
14149 How does it work?
14150 \end_layout
14151
14152 \begin_layout Standard
14153 The external material feature is based on the concept of a
14154 \emph on
14155 template
14156 \emph default
14157 .
14158  A template is a specification of how LyX should interface with a certain
14159  kind of material.
14160  As bundled, LyX comes with predefined templates for Xfig figures, various
14161  raster format images, chess diagrams, and LilyPond music notation.
14162  You can check the actual list by using the menu
14163 \begin_inset Flex CharStyle:MenuItem
14164 status collapsed
14165
14166 \begin_layout Plain Layout
14167 Insert\SpecialChar \menuseparator
14168 File\SpecialChar \menuseparator
14169 External Material
14170 \end_layout
14171
14172 \end_inset
14173
14174 .
14175  Furthermore, it is possible to roll your own template to support a specific
14176  kind of material.
14177  Later we'll describe in more detail what is involved, and hopefully you
14178  will submit all the templates you create so we can include them in a later
14179  LyX version.
14180 \end_layout
14181
14182 \begin_layout Standard
14183 Another basic idea of the external material feature is to distinguish between
14184  the original file that serves as a base for final material and the produced
14185  file that is included in your exported or printed document.
14186  For example, consider the case of a figure produced with
14187 \begin_inset Flex CharStyle:Code
14188 status collapsed
14189
14190 \begin_layout Plain Layout
14191 Xfig
14192 \end_layout
14193
14194 \end_inset
14195
14196 .
14197  The Xfig application itself works on an original file with the
14198 \begin_inset Flex CharStyle:Code
14199 status collapsed
14200
14201 \begin_layout Plain Layout
14202 .fig
14203 \end_layout
14204
14205 \end_inset
14206
14207  extension.
14208  Within Xfig, you create and change your figure, and when you are done,
14209  you save the
14210 \begin_inset Flex CharStyle:Code
14211 status collapsed
14212
14213 \begin_layout Plain Layout
14214 fig
14215 \end_layout
14216
14217 \end_inset
14218
14219 -file.
14220  When you want to include the figure in your document, you invoke
14221 \begin_inset Flex CharStyle:Code
14222 status collapsed
14223
14224 \begin_layout Plain Layout
14225 transfig
14226 \end_layout
14227
14228 \end_inset
14229
14230  in order to create a PostScript file that can readily be included in your
14231  LaTeX file.
14232  In this case, the
14233 \begin_inset Flex CharStyle:Code
14234 status collapsed
14235
14236 \begin_layout Plain Layout
14237 .fig
14238 \end_layout
14239
14240 \end_inset
14241
14242  file is the original file, and the PostScript file is the produced file.
14243 \end_layout
14244
14245 \begin_layout Standard
14246 This distinction is important in order to allow updating of the material
14247  while you are in the process of writing the document.
14248  Furthermore, it provides us with the flexibility that is needed to support
14249  multiple export formats.
14250  For instance, in the case of a plain text file, it is not exactly an award-winn
14251 ing idea to include the figure as raw PostScript.
14252  Instead, you'd either prefer to just include a reference to the figure
14253  or try to invoke some graphics to ASCII converter to make the final result
14254  look similar to the real graphics.
14255  The external material management allows you to do this, because it is parametri
14256 zed on the different export formats that LyX supports.
14257 \end_layout
14258
14259 \begin_layout Standard
14260 Besides supporting the production of different products according to the
14261  exported format, it supports tight integration with editing and viewing
14262  applications.
14263  In the case of an Xfig figure, you are able to invoke Xfig on the original
14264  file with a single click from within the external material dialog in LyX,
14265  and also preview the produced PostScript file with Ghostview with another
14266  click.
14267  No more fiddling around with the command line and/or file browsers to locate
14268  and manipulate the original or produced files.
14269  In this way, you are finally able to take full advantage of the many different
14270  applications that are relevant to use when you write your documents, and
14271  ultimately be more productive.
14272 \end_layout
14273
14274 \begin_layout Section
14275 The external template configuration file
14276 \end_layout
14277
14278 \begin_layout Standard
14279 It is relatively easy to add custom external template definitions to LyX.
14280  However, be aware that doing this in an careless manner most probably
14281 \emph on
14282 will
14283 \emph default
14284  introduce an easily exploitable security hole.
14285  So before you do this, please read the discussion about security in section
14286
14287 \begin_inset CommandInset ref
14288 LatexCommand ref
14289 reference "sec:Security-discussion"
14290
14291 \end_inset
14292
14293 .
14294 \end_layout
14295
14296 \begin_layout Standard
14297 Having said that, we encourage you to submit any interesting templates that
14298  you create.
14299
14300 \end_layout
14301
14302 \begin_layout Standard
14303 The external templates are defined in the
14304 \begin_inset Flex CharStyle:Code
14305 status collapsed
14306
14307 \begin_layout Plain Layout
14308 LyXDir/lib/external_templates
14309 \end_layout
14310
14311 \end_inset
14312
14313  file.
14314  You can place your own version in
14315 \begin_inset Flex CharStyle:Code
14316 status collapsed
14317
14318 \begin_layout Plain Layout
14319 UserDir/external_templates
14320 \end_layout
14321
14322 \end_inset
14323
14324 .
14325 \end_layout
14326
14327 \begin_layout Standard
14328 A typical template looks like this:
14329 \end_layout
14330
14331 \begin_layout LyX-Code
14332 Template XFig
14333 \end_layout
14334
14335 \begin_layout LyX-Code
14336 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14337 \end_layout
14338
14339 \begin_layout LyX-Code
14340 HelpText
14341 \end_layout
14342
14343 \begin_layout LyX-Code
14344 An XFig figure.
14345 \end_layout
14346
14347 \begin_layout LyX-Code
14348 HelpTextEnd
14349 \end_layout
14350
14351 \begin_layout LyX-Code
14352 InputFormat fig
14353 \end_layout
14354
14355 \begin_layout LyX-Code
14356 FileFilter "*.fig"
14357 \end_layout
14358
14359 \begin_layout LyX-Code
14360 AutomaticProduction true
14361 \end_layout
14362
14363 \begin_layout LyX-Code
14364 Transform Rotate
14365 \end_layout
14366
14367 \begin_layout LyX-Code
14368 Transform Resize
14369 \end_layout
14370
14371 \begin_layout LyX-Code
14372 Format LaTeX
14373 \end_layout
14374
14375 \begin_layout LyX-Code
14376 TransformCommand Rotate RotationLatexCommand
14377 \end_layout
14378
14379 \begin_layout LyX-Code
14380 TransformCommand Resize ResizeLatexCommand
14381 \end_layout
14382
14383 \begin_layout LyX-Code
14384 Product "$$RotateFront$$ResizeFront
14385 \end_layout
14386
14387 \begin_layout LyX-Code
14388
14389 \backslash
14390
14391 \backslash
14392 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14393 \end_layout
14394
14395 \begin_layout LyX-Code
14396          $$ResizeBack$$RotateBack"
14397 \end_layout
14398
14399 \begin_layout LyX-Code
14400 UpdateFormat pstex
14401 \end_layout
14402
14403 \begin_layout LyX-Code
14404 UpdateResult "$$AbsPath$$Basename.pstex_t"
14405 \end_layout
14406
14407 \begin_layout LyX-Code
14408 Requirement "graphicx"
14409 \end_layout
14410
14411 \begin_layout LyX-Code
14412 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14413 \end_layout
14414
14415 \begin_layout LyX-Code
14416 ReferencedFile latex "$$AbsPath$$Basename.eps"
14417 \end_layout
14418
14419 \begin_layout LyX-Code
14420 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14421 \end_layout
14422
14423 \begin_layout LyX-Code
14424 FormatEnd
14425 \end_layout
14426
14427 \begin_layout LyX-Code
14428 Format PDFLaTeX
14429 \end_layout
14430
14431 \begin_layout LyX-Code
14432 TransformCommand Rotate RotationLatexCommand
14433 \end_layout
14434
14435 \begin_layout LyX-Code
14436 TransformCommand Resize ResizeLatexCommand
14437 \end_layout
14438
14439 \begin_layout LyX-Code
14440 Product "$$RotateFront$$ResizeFront
14441 \end_layout
14442
14443 \begin_layout LyX-Code
14444
14445 \backslash
14446
14447 \backslash
14448 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14449 \end_layout
14450
14451 \begin_layout LyX-Code
14452          $$ResizeBack$$RotateBack"
14453 \end_layout
14454
14455 \begin_layout LyX-Code
14456 UpdateFormat pdftex
14457 \end_layout
14458
14459 \begin_layout LyX-Code
14460 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14461 \end_layout
14462
14463 \begin_layout LyX-Code
14464 Requirement "graphicx"
14465 \end_layout
14466
14467 \begin_layout LyX-Code
14468 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14469 \end_layout
14470
14471 \begin_layout LyX-Code
14472 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14473 \end_layout
14474
14475 \begin_layout LyX-Code
14476 FormatEnd
14477 \end_layout
14478
14479 \begin_layout LyX-Code
14480 Format Ascii
14481 \end_layout
14482
14483 \begin_layout LyX-Code
14484 Product "$$Contents(
14485 \backslash
14486 "$$AbsPath$$Basename.asc
14487 \backslash
14488 ")"
14489 \end_layout
14490
14491 \begin_layout LyX-Code
14492 UpdateFormat asciixfig
14493 \end_layout
14494
14495 \begin_layout LyX-Code
14496 UpdateResult "$$AbsPath$$Basename.asc"
14497 \end_layout
14498
14499 \begin_layout LyX-Code
14500 FormatEnd
14501 \end_layout
14502
14503 \begin_layout LyX-Code
14504 Format DocBook
14505 \end_layout
14506
14507 \begin_layout LyX-Code
14508 Product "<graphic fileref=
14509 \backslash
14510 "$$AbsOrRelPathMaster$$Basename.eps
14511 \backslash
14512 ">
14513 \end_layout
14514
14515 \begin_layout LyX-Code
14516          </graphic>"
14517 \end_layout
14518
14519 \begin_layout LyX-Code
14520 UpdateFormat eps
14521 \end_layout
14522
14523 \begin_layout LyX-Code
14524 UpdateResult "$$AbsPath$$Basename.eps"
14525 \end_layout
14526
14527 \begin_layout LyX-Code
14528 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14529 \end_layout
14530
14531 \begin_layout LyX-Code
14532 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14533 \end_layout
14534
14535 \begin_layout LyX-Code
14536 FormatEnd
14537 \end_layout
14538
14539 \begin_layout LyX-Code
14540 Product "[XFig: $$FName]"
14541 \end_layout
14542
14543 \begin_layout LyX-Code
14544 FormatEnd
14545 \end_layout
14546
14547 \begin_layout LyX-Code
14548 TemplateEnd
14549 \end_layout
14550
14551 \begin_layout Standard
14552 As you can see, the template is enclosed in
14553 \begin_inset Flex CharStyle:Code
14554 status collapsed
14555
14556 \begin_layout Plain Layout
14557 Template
14558 \end_layout
14559
14560 \end_inset
14561
14562  \SpecialChar \ldots{}
14563
14564 \begin_inset Flex CharStyle:Code
14565 status collapsed
14566
14567 \begin_layout Plain Layout
14568 TemplateEnd
14569 \end_layout
14570
14571 \end_inset
14572
14573 .
14574  It contains a header specifying some general settings and, for each supported
14575  primary document file format, a section
14576 \begin_inset Flex CharStyle:Code
14577 status collapsed
14578
14579 \begin_layout Plain Layout
14580 Format
14581 \end_layout
14582
14583 \end_inset
14584
14585  \SpecialChar \ldots{}
14586
14587 \begin_inset Flex CharStyle:Code
14588 status collapsed
14589
14590 \begin_layout Plain Layout
14591 FormatEnd
14592 \end_layout
14593
14594 \end_inset
14595
14596 .
14597 \end_layout
14598
14599 \begin_layout Subsection
14600 The template header
14601 \end_layout
14602
14603 \begin_layout Description
14604 \begin_inset Flex CharStyle:Code
14605 status collapsed
14606
14607 \begin_layout Plain Layout
14608 AutomaticProduction
14609 \begin_inset space ~
14610 \end_inset
14611
14612 true|false
14613 \end_layout
14614
14615 \end_inset
14616
14617  Whether the file represented by the template must be generated by LyX.
14618  This command must occur exactly once.
14619 \end_layout
14620
14621 \begin_layout Description
14622 \begin_inset Flex CharStyle:Code
14623 status collapsed
14624
14625 \begin_layout Plain Layout
14626 FileFilter
14627 \begin_inset space ~
14628 \end_inset
14629
14630 <pattern>
14631 \end_layout
14632
14633 \end_inset
14634
14635  A glob pattern that is used in the file dialog to filter out the desired
14636  files.
14637  If there is more than one possible file extension (e.
14638 \begin_inset space \thinspace{}
14639 \end_inset
14640
14641 g.
14642 \begin_inset space \space{}
14643 \end_inset
14644
14645 tgif has
14646 \begin_inset Flex CharStyle:Code
14647 status collapsed
14648
14649 \begin_layout Plain Layout
14650 .obj
14651 \end_layout
14652
14653 \end_inset
14654
14655  and
14656 \begin_inset Flex CharStyle:Code
14657 status collapsed
14658
14659 \begin_layout Plain Layout
14660 .tgo
14661 \end_layout
14662
14663 \end_inset
14664
14665 ), use something like
14666 \begin_inset Flex CharStyle:Code
14667 status collapsed
14668
14669 \begin_layout Plain Layout
14670 "*.{obj,tgo}"
14671 \end_layout
14672
14673 \end_inset
14674
14675 .
14676  This command must occur exactly once.
14677 \end_layout
14678
14679 \begin_layout Description
14680 \begin_inset Flex CharStyle:Code
14681 status collapsed
14682
14683 \begin_layout Plain Layout
14684 GuiName
14685 \begin_inset space ~
14686 \end_inset
14687
14688 <guiname>
14689 \end_layout
14690
14691 \end_inset
14692
14693  The text that is displayed on the button.
14694  This command must occur exactly once.
14695 \end_layout
14696
14697 \begin_layout Description
14698 \begin_inset Flex CharStyle:Code
14699 status collapsed
14700
14701 \begin_layout Plain Layout
14702 HelpText
14703 \begin_inset space ~
14704 \end_inset
14705
14706 <text>
14707 \begin_inset space ~
14708 \end_inset
14709
14710 HelpTextEnd
14711 \end_layout
14712
14713 \end_inset
14714
14715  The help text that is used in the External dialog.
14716  Provide enough information to explain to the user just what the template
14717  can provide him with.
14718  This command must occur exactly once.
14719 \end_layout
14720
14721 \begin_layout Description
14722 \begin_inset Flex CharStyle:Code
14723 status collapsed
14724
14725 \begin_layout Plain Layout
14726 InputFormat
14727 \begin_inset space ~
14728 \end_inset
14729
14730 <format>
14731 \end_layout
14732
14733 \end_inset
14734
14735  The file format of the original file.
14736  This must be the name of a format that is known to LyX (see section
14737 \begin_inset CommandInset ref
14738 LatexCommand ref
14739 reference "sub:Formats"
14740
14741 \end_inset
14742
14743 ).
14744  Use
14745 \begin_inset Quotes eld
14746 \end_inset
14747
14748
14749 \begin_inset Flex CharStyle:Code
14750 status collapsed
14751
14752 \begin_layout Plain Layout
14753 *
14754 \end_layout
14755
14756 \end_inset
14757
14758
14759 \begin_inset Quotes erd
14760 \end_inset
14761
14762  if the template can handle original files of more than one format.
14763  LyX will attempt to interrogate the file itself in order to deduce its
14764  format in this case.
14765  This command must occur exactly once.
14766 \end_layout
14767
14768 \begin_layout Description
14769 \begin_inset Flex CharStyle:Code
14770 status collapsed
14771
14772 \begin_layout Plain Layout
14773 Template
14774 \begin_inset space ~
14775 \end_inset
14776
14777 <id>
14778 \end_layout
14779
14780 \end_inset
14781
14782  A unique name for the template.
14783  It must not contain substitution macros (see below).
14784 \end_layout
14785
14786 \begin_layout Description
14787 \begin_inset Flex CharStyle:Code
14788 status collapsed
14789
14790 \begin_layout Plain Layout
14791 Transform
14792 \begin_inset space ~
14793 \end_inset
14794
14795 Rotate|Resize|Clip|Extra
14796 \end_layout
14797
14798 \end_inset
14799
14800  This command specifies which transformations are supported by this template.
14801  It may occur zero or more times.
14802  This command enables the corresponding tabs in the external dialog.
14803  Each
14804 \begin_inset Flex CharStyle:Code
14805 status collapsed
14806
14807 \begin_layout Plain Layout
14808 Transform
14809 \end_layout
14810
14811 \end_inset
14812
14813  command must have either a corresponding
14814 \begin_inset Flex CharStyle:Code
14815 status collapsed
14816
14817 \begin_layout Plain Layout
14818 TransformCommand
14819 \end_layout
14820
14821 \end_inset
14822
14823  or a
14824 \begin_inset Flex CharStyle:Code
14825 status collapsed
14826
14827 \begin_layout Plain Layout
14828 TransformOption
14829 \end_layout
14830
14831 \end_inset
14832
14833  command in the
14834 \begin_inset Flex CharStyle:Code
14835 status collapsed
14836
14837 \begin_layout Plain Layout
14838 Format
14839 \end_layout
14840
14841 \end_inset
14842
14843  section.
14844  Otherwise the transformation will not be supported by that format.
14845 \end_layout
14846
14847 \begin_layout Subsection
14848 The Format section
14849 \end_layout
14850
14851 \begin_layout Description
14852 \begin_inset Flex CharStyle:Code
14853 status collapsed
14854
14855 \begin_layout Plain Layout
14856 Format
14857 \begin_inset space ~
14858 \end_inset
14859
14860 LaTeX|PDFLaTeX|PlainText|DocBook
14861 \end_layout
14862
14863 \end_inset
14864
14865  The primary document file format that this format definition is for.
14866  Not every template has a sensible representation in all document file formats.
14867  Please define nevertheless a
14868 \begin_inset Flex CharStyle:Code
14869 status collapsed
14870
14871 \begin_layout Plain Layout
14872 Format
14873 \end_layout
14874
14875 \end_inset
14876
14877  section for all formats.
14878  Use a dummy text when no representation is available.
14879  Then you can at least see a reference to the external material in the exported
14880  document.
14881 \end_layout
14882
14883 \begin_layout Description
14884 \begin_inset Flex CharStyle:Code
14885 status collapsed
14886
14887 \begin_layout Plain Layout
14888 Option
14889 \begin_inset space ~
14890 \end_inset
14891
14892 <name>
14893 \begin_inset space ~
14894 \end_inset
14895
14896 <value>
14897 \end_layout
14898
14899 \end_inset
14900
14901  This command defines an additional macro
14902 \begin_inset Flex CharStyle:Code
14903 status collapsed
14904
14905 \begin_layout Plain Layout
14906 $$<name>
14907 \end_layout
14908
14909 \end_inset
14910
14911  for substitution in
14912 \begin_inset Flex CharStyle:Code
14913 status collapsed
14914
14915 \begin_layout Plain Layout
14916 Product
14917 \end_layout
14918
14919 \end_inset
14920
14921 .
14922
14923 \begin_inset Flex CharStyle:Code
14924 status collapsed
14925
14926 \begin_layout Plain Layout
14927 <value>
14928 \end_layout
14929
14930 \end_inset
14931
14932  itself may contain substitution macros.
14933  The advantage over using
14934 \begin_inset Flex CharStyle:Code
14935 status collapsed
14936
14937 \begin_layout Plain Layout
14938 <value>
14939 \end_layout
14940
14941 \end_inset
14942
14943  directly in
14944 \begin_inset Flex CharStyle:Code
14945 status collapsed
14946
14947 \begin_layout Plain Layout
14948 Product
14949 \end_layout
14950
14951 \end_inset
14952
14953  is that the substituted value of
14954 \begin_inset Flex CharStyle:Code
14955 status collapsed
14956
14957 \begin_layout Plain Layout
14958 $$<name>
14959 \end_layout
14960
14961 \end_inset
14962
14963  is sanitized so that it is a valid optional argument in the document format.
14964  This command may occur zero or more times.
14965 \end_layout
14966
14967 \begin_layout Description
14968 \begin_inset Flex CharStyle:Code
14969 status collapsed
14970
14971 \begin_layout Plain Layout
14972 Product
14973 \begin_inset space ~
14974 \end_inset
14975
14976 <text>
14977 \end_layout
14978
14979 \end_inset
14980
14981  The text that is inserted in the exported document.
14982  This is actually the most important command and can be quite complex.
14983  This command must occur exactly once.
14984 \end_layout
14985
14986 \begin_layout Description
14987 \begin_inset Flex CharStyle:Code
14988 status collapsed
14989
14990 \begin_layout Plain Layout
14991 Preamble
14992 \begin_inset space ~
14993 \end_inset
14994
14995 <name>
14996 \end_layout
14997
14998 \end_inset
14999
15000  This command specifies a preamble snippet that will be included in the
15001  LaTeX preamble.
15002  It has to be defined using
15003 \begin_inset Flex CharStyle:Code
15004 status collapsed
15005
15006 \begin_layout Plain Layout
15007 PreambleDef
15008 \end_layout
15009
15010 \end_inset
15011
15012  \SpecialChar \ldots{}
15013
15014 \begin_inset Flex CharStyle:Code
15015 status collapsed
15016
15017 \begin_layout Plain Layout
15018 PreambleDefEnd
15019 \end_layout
15020
15021 \end_inset
15022
15023 .
15024  This command may occur zero or more times.
15025 \end_layout
15026
15027 \begin_layout Description
15028 \begin_inset Flex CharStyle:Code
15029 status collapsed
15030
15031 \begin_layout Plain Layout
15032 ReferencedFile
15033 \begin_inset space ~
15034 \end_inset
15035
15036 <format>
15037 \begin_inset space ~
15038 \end_inset
15039
15040 <filename>
15041 \end_layout
15042
15043 \end_inset
15044
15045  This command denotes files that are created by the conversion process and
15046  are needed for a particular export format.
15047  If the filename is relative, it is interpreted relative to the master document.
15048  This command may be given zero or more times.
15049 \end_layout
15050
15051 \begin_layout Description
15052 \begin_inset Flex CharStyle:Code
15053 status collapsed
15054
15055 \begin_layout Plain Layout
15056 Requirement
15057 \begin_inset space ~
15058 \end_inset
15059
15060 <package>
15061 \end_layout
15062
15063 \end_inset
15064
15065  The name of a required LaTeX package.
15066  The package is included via
15067 \begin_inset Flex CharStyle:Code
15068 status collapsed
15069
15070 \begin_layout Plain Layout
15071
15072 \backslash
15073 usepackage{}
15074 \end_layout
15075
15076 \end_inset
15077
15078  in the LaTeX preamble.
15079  This command may occur zero or more times.
15080 \end_layout
15081
15082 \begin_layout Description
15083 \begin_inset Flex CharStyle:Code
15084 status collapsed
15085
15086 \begin_layout Plain Layout
15087 TransformCommand
15088 \begin_inset space ~
15089 \end_inset
15090
15091 Rotate
15092 \begin_inset space ~
15093 \end_inset
15094
15095 RotationLatexCommand
15096 \end_layout
15097
15098 \end_inset
15099
15100  This command specifies that the built in LaTeX command should be used for
15101  rotation.
15102  This command may occur once or not at all.
15103 \end_layout
15104
15105 \begin_layout Description
15106 \begin_inset Flex CharStyle:Code
15107 status collapsed
15108
15109 \begin_layout Plain Layout
15110 TransformCommand
15111 \begin_inset space ~
15112 \end_inset
15113
15114 Resize
15115 \begin_inset space ~
15116 \end_inset
15117
15118 ResizeLatexCommand
15119 \end_layout
15120
15121 \end_inset
15122
15123  This command specifies that the built in LaTeX command should be used for
15124  resizing.
15125  This command may occur once or not at all.
15126 \end_layout
15127
15128 \begin_layout Description
15129 \begin_inset Flex CharStyle:Code
15130 status collapsed
15131
15132 \begin_layout Plain Layout
15133 TransformOption
15134 \begin_inset space ~
15135 \end_inset
15136
15137 Rotate
15138 \begin_inset space ~
15139 \end_inset
15140
15141 RotationLatexOption
15142 \end_layout
15143
15144 \end_inset
15145
15146  This command specifies that rotation is done via an optional argument.
15147  This command may occur once or not at all.
15148 \end_layout
15149
15150 \begin_layout Description
15151 \begin_inset Flex CharStyle:Code
15152 status collapsed
15153
15154 \begin_layout Plain Layout
15155 TransformOption
15156 \begin_inset space ~
15157 \end_inset
15158
15159 Resize
15160 \begin_inset space ~
15161 \end_inset
15162
15163 ResizeLatexOption
15164 \end_layout
15165
15166 \end_inset
15167
15168  This command specifies that resizing is done via an optional argument.
15169  This command may occur once or not at all.
15170 \end_layout
15171
15172 \begin_layout Description
15173 \begin_inset Flex CharStyle:Code
15174 status collapsed
15175
15176 \begin_layout Plain Layout
15177 TransformOption
15178 \begin_inset space ~
15179 \end_inset
15180
15181 Clip
15182 \begin_inset space ~
15183 \end_inset
15184
15185 ClipLatexOption
15186 \end_layout
15187
15188 \end_inset
15189
15190  This command specifies that clipping is done via an optional argument.
15191  This command may occur once or not at all.
15192 \end_layout
15193
15194 \begin_layout Description
15195 \begin_inset Flex CharStyle:Code
15196 status collapsed
15197
15198 \begin_layout Plain Layout
15199 TransformOption
15200 \begin_inset space ~
15201 \end_inset
15202
15203 Extra
15204 \begin_inset space ~
15205 \end_inset
15206
15207 ExtraLatexOption
15208 \end_layout
15209
15210 \end_inset
15211
15212  This command specifies that an extra optional argument is used.
15213  This command may occur once or not at all.
15214 \end_layout
15215
15216 \begin_layout Description
15217 \begin_inset Flex CharStyle:Code
15218 status collapsed
15219
15220 \begin_layout Plain Layout
15221 UpdateFormat
15222 \begin_inset space ~
15223 \end_inset
15224
15225 <format>
15226 \end_layout
15227
15228 \end_inset
15229
15230  The file format of the converted file.
15231  This must be the name of a format that is known to LyX (see the
15232 \begin_inset Flex CharStyle:MenuItem
15233 status collapsed
15234
15235 \begin_layout Plain Layout
15236
15237 \bar under
15238 T
15239 \bar default
15240 ools\SpecialChar \menuseparator
15241
15242 \bar under
15243 P
15244 \bar default
15245 references:Conversion
15246 \end_layout
15247
15248 \end_inset
15249
15250  dialog).
15251  This command must occur exactly once.
15252 \end_layout
15253
15254 \begin_layout Description
15255 \begin_inset Flex CharStyle:Code
15256 status collapsed
15257
15258 \begin_layout Plain Layout
15259 UpdateResult
15260 \begin_inset space ~
15261 \end_inset
15262
15263 <filename>
15264 \end_layout
15265
15266 \end_inset
15267
15268  The file name of the converted file.
15269  The file name must be absolute.
15270  This command must occur exactly once.
15271 \end_layout
15272
15273 \begin_layout Subsection
15274 Preamble definitions
15275 \end_layout
15276
15277 \begin_layout Standard
15278 The external template configuration file may contain additional preamble
15279  definitions enclosed by
15280 \begin_inset Flex CharStyle:Code
15281 status collapsed
15282
15283 \begin_layout Plain Layout
15284 PreambleDef
15285 \end_layout
15286
15287 \end_inset
15288
15289  \SpecialChar \ldots{}
15290
15291 \begin_inset Flex CharStyle:Code
15292 status collapsed
15293
15294 \begin_layout Plain Layout
15295 PreambleDefEnd
15296 \end_layout
15297
15298 \end_inset
15299
15300 .
15301  They can be used by the templates in the
15302 \begin_inset Flex CharStyle:Code
15303 status collapsed
15304
15305 \begin_layout Plain Layout
15306 Format
15307 \end_layout
15308
15309 \end_inset
15310
15311  section.
15312 \end_layout
15313
15314 \begin_layout Section
15315 The substitution mechanism
15316 \end_layout
15317
15318 \begin_layout Standard
15319 When the external material facility invokes an external program, it is done
15320  on the basis of a command defined in the template configuration file.
15321  These commands can contain various macros that are expanded before execution.
15322  Execution always take place in the directory of the containing document.
15323 \end_layout
15324
15325 \begin_layout Standard
15326 Also, whenever external material is to be displayed, the name will be produced
15327  by the substitution mechanism, and most other commands in the template
15328  definition support substitution as well.
15329 \end_layout
15330
15331 \begin_layout Standard
15332 The available macros are the following:
15333 \end_layout
15334
15335 \begin_layout Description
15336 \begin_inset Flex CharStyle:Code
15337 status collapsed
15338
15339 \begin_layout Plain Layout
15340 $$AbsOrRelPathMaster
15341 \end_layout
15342
15343 \end_inset
15344
15345  The file path, absolute or relative to the master LyX document.
15346 \end_layout
15347
15348 \begin_layout Description
15349 \begin_inset Flex CharStyle:Code
15350 status collapsed
15351
15352 \begin_layout Plain Layout
15353 $$AbsOrRelPathParent
15354 \end_layout
15355
15356 \end_inset
15357
15358  The file path, absolute or relative to the LyX document.
15359 \end_layout
15360
15361 \begin_layout Description
15362 \begin_inset Flex CharStyle:Code
15363 status collapsed
15364
15365 \begin_layout Plain Layout
15366 $$AbsPath
15367 \end_layout
15368
15369 \end_inset
15370
15371  The absolute file path.
15372 \end_layout
15373
15374 \begin_layout Description
15375 \begin_inset Flex CharStyle:Code
15376 status collapsed
15377
15378 \begin_layout Plain Layout
15379 $$Basename
15380 \end_layout
15381
15382 \end_inset
15383
15384  The filename without path and without the extension.
15385 \end_layout
15386
15387 \begin_layout Description
15388 \begin_inset Flex CharStyle:Code
15389 status collapsed
15390
15391 \begin_layout Plain Layout
15392 $$Contents(
15393 \begin_inset Quotes eld
15394 \end_inset
15395
15396 filename.ext
15397 \begin_inset Quotes erd
15398 \end_inset
15399
15400 )
15401 \end_layout
15402
15403 \end_inset
15404
15405  This macro will expand to the contents of the file with the name
15406 \begin_inset Flex CharStyle:Code
15407 status collapsed
15408
15409 \begin_layout Plain Layout
15410 filename.ext
15411 \end_layout
15412
15413 \end_inset
15414
15415 .
15416 \end_layout
15417
15418 \begin_layout Description
15419 \begin_inset Flex CharStyle:Code
15420 status collapsed
15421
15422 \begin_layout Plain Layout
15423 $$Extension
15424 \end_layout
15425
15426 \end_inset
15427
15428  The file extension (including the dot).
15429 \end_layout
15430
15431 \begin_layout Description
15432 \begin_inset Flex CharStyle:Code
15433 status collapsed
15434
15435 \begin_layout Plain Layout
15436 $$FName
15437 \end_layout
15438
15439 \end_inset
15440
15441  The filename of the file specified in the external material dialog.
15442  This is either an absolute name, or it is relative to the LyX document.
15443 \end_layout
15444
15445 \begin_layout Description
15446 \begin_inset Flex CharStyle:Code
15447 status collapsed
15448
15449 \begin_layout Plain Layout
15450 $$FPath
15451 \end_layout
15452
15453 \end_inset
15454
15455  The path part of
15456 \begin_inset Flex CharStyle:Code
15457 status collapsed
15458
15459 \begin_layout Plain Layout
15460 $$FName
15461 \end_layout
15462
15463 \end_inset
15464
15465  (absolute name or relative to the LyX document).
15466 \end_layout
15467
15468 \begin_layout Description
15469 \begin_inset Flex CharStyle:Code
15470 status collapsed
15471
15472 \begin_layout Plain Layout
15473 $$RelPathMaster
15474 \end_layout
15475
15476 \end_inset
15477
15478  The file path, relative to the master LyX document.
15479 \end_layout
15480
15481 \begin_layout Description
15482 \begin_inset Flex CharStyle:Code
15483 status collapsed
15484
15485 \begin_layout Plain Layout
15486 $$RelPathParent
15487 \end_layout
15488
15489 \end_inset
15490
15491  The file path, relative to the LyX document.
15492 \end_layout
15493
15494 \begin_layout Description
15495 \begin_inset Flex CharStyle:Code
15496 status collapsed
15497
15498 \begin_layout Plain Layout
15499 $$Sysdir
15500 \end_layout
15501
15502 \end_inset
15503
15504  This macro will expand to the absolute path of the system directory.
15505  This is typically used to point to the various helper scripts that are
15506  bundled with LyX.
15507 \end_layout
15508
15509 \begin_layout Description
15510 \begin_inset Flex CharStyle:Code
15511 status collapsed
15512
15513 \begin_layout Plain Layout
15514 $$Tempname
15515 \end_layout
15516
15517 \end_inset
15518
15519  A name and full path to a temporary file which will be automatically deleted
15520  whenever the containing document is closed, or the external material insertion
15521  deleted.
15522 \end_layout
15523
15524 \begin_layout Standard
15525 All path macros contain a trailing directory separator, so you can construct
15526  e.
15527 \begin_inset space \thinspace{}
15528 \end_inset
15529
15530 g.
15531 \begin_inset space \space{}
15532 \end_inset
15533
15534 the absolute filename with
15535 \begin_inset Flex CharStyle:Code
15536 status collapsed
15537
15538 \begin_layout Plain Layout
15539 $$AbsPath$$Basename$$Extension
15540 \end_layout
15541
15542 \end_inset
15543
15544 .
15545 \end_layout
15546
15547 \begin_layout Standard
15548 The macros above are substituted in all commands unless otherwise noted.
15549  The command
15550 \begin_inset Flex CharStyle:Code
15551 status collapsed
15552
15553 \begin_layout Plain Layout
15554 Product
15555 \end_layout
15556
15557 \end_inset
15558
15559  supports additionally the following substitutions if they are enabled by
15560  the
15561 \begin_inset Flex CharStyle:Code
15562 status collapsed
15563
15564 \begin_layout Plain Layout
15565 Transform
15566 \end_layout
15567
15568 \end_inset
15569
15570  and
15571 \begin_inset Flex CharStyle:Code
15572 status collapsed
15573
15574 \begin_layout Plain Layout
15575 TransformCommand
15576 \end_layout
15577
15578 \end_inset
15579
15580  commands:
15581 \end_layout
15582
15583 \begin_layout Description
15584 \begin_inset Flex CharStyle:Code
15585 status collapsed
15586
15587 \begin_layout Plain Layout
15588 $$ResizeFront
15589 \end_layout
15590
15591 \end_inset
15592
15593  The front part of the resize command.
15594 \end_layout
15595
15596 \begin_layout Description
15597 \begin_inset Flex CharStyle:Code
15598 status collapsed
15599
15600 \begin_layout Plain Layout
15601 $$ResizeBack
15602 \end_layout
15603
15604 \end_inset
15605
15606  The back part of the resize command.
15607 \end_layout
15608
15609 \begin_layout Description
15610 \begin_inset Flex CharStyle:Code
15611 status collapsed
15612
15613 \begin_layout Plain Layout
15614 $$RotateFront
15615 \end_layout
15616
15617 \end_inset
15618
15619  The front part of the rotation command.
15620 \end_layout
15621
15622 \begin_layout Description
15623 \begin_inset Flex CharStyle:Code
15624 status collapsed
15625
15626 \begin_layout Plain Layout
15627 $$RotateBack
15628 \end_layout
15629
15630 \end_inset
15631
15632  The back part of the rotation command.
15633 \end_layout
15634
15635 \begin_layout Standard
15636 The value string of the
15637 \begin_inset Flex CharStyle:Code
15638 status collapsed
15639
15640 \begin_layout Plain Layout
15641 Option
15642 \end_layout
15643
15644 \end_inset
15645
15646  command supports additionally the following substitutions if they are enabled
15647  by the
15648 \begin_inset Flex CharStyle:Code
15649 status collapsed
15650
15651 \begin_layout Plain Layout
15652 Transform
15653 \end_layout
15654
15655 \end_inset
15656
15657  and
15658 \begin_inset Flex CharStyle:Code
15659 status collapsed
15660
15661 \begin_layout Plain Layout
15662 TransformOption
15663 \end_layout
15664
15665 \end_inset
15666
15667  commands:
15668 \end_layout
15669
15670 \begin_layout Description
15671 \begin_inset Flex CharStyle:Code
15672 status collapsed
15673
15674 \begin_layout Plain Layout
15675 $$Clip
15676 \end_layout
15677
15678 \end_inset
15679
15680  The clip option.
15681 \end_layout
15682
15683 \begin_layout Description
15684 \begin_inset Flex CharStyle:Code
15685 status collapsed
15686
15687 \begin_layout Plain Layout
15688 $$Extra
15689 \end_layout
15690
15691 \end_inset
15692
15693  The extra option.
15694 \end_layout
15695
15696 \begin_layout Description
15697 \begin_inset Flex CharStyle:Code
15698 status collapsed
15699
15700 \begin_layout Plain Layout
15701 $$Resize
15702 \end_layout
15703
15704 \end_inset
15705
15706  The resize option.
15707 \end_layout
15708
15709 \begin_layout Description
15710 \begin_inset Flex CharStyle:Code
15711 status collapsed
15712
15713 \begin_layout Plain Layout
15714 $$Rotate
15715 \end_layout
15716
15717 \end_inset
15718
15719  The rotation option.
15720 \end_layout
15721
15722 \begin_layout Standard
15723 You may ask why there are so many path macros.
15724  There are mainly two reasons:
15725 \end_layout
15726
15727 \begin_layout Enumerate
15728 Relative and absolute file names should remain relative or absolute, respectivel
15729 y.
15730  Users may have reasons to prefer either form.
15731  Relative names are useful for portable documents that should work on different
15732  machines, for example.
15733  Absolute names may be required by some programs.
15734 \end_layout
15735
15736 \begin_layout Enumerate
15737 LaTeX treats relative file names differently than LyX and other programs
15738  in nested included files.
15739  For LyX, a relative file name is always relative to the document that contains
15740  the file name.
15741  For LaTeX, it is always relative to the master document.
15742  These two definitions are identical if you have only one document, but
15743  differ if you have a master document that includes part documents.
15744  That means that relative filenames must be transformed when presented to
15745  LaTeX.
15746  Fortunately LyX does this automatically for you if you choose the right
15747  macros.
15748 \end_layout
15749
15750 \begin_layout Standard
15751 So which path macro should be used in new template definitions? The rule
15752  is not difficult:
15753 \end_layout
15754
15755 \begin_layout Itemize
15756 Use
15757 \begin_inset Flex CharStyle:Code
15758 status collapsed
15759
15760 \begin_layout Plain Layout
15761 $$AbsPath
15762 \end_layout
15763
15764 \end_inset
15765
15766  if an absolute path is required.
15767 \end_layout
15768
15769 \begin_layout Itemize
15770 Use
15771 \begin_inset Flex CharStyle:Code
15772 status collapsed
15773
15774 \begin_layout Plain Layout
15775 $$AbsOrRelPathMaster
15776 \end_layout
15777
15778 \end_inset
15779
15780  if the substituted string is some kind of LaTeX input.
15781 \end_layout
15782
15783 \begin_layout Itemize
15784 Else use
15785 \begin_inset Flex CharStyle:Code
15786 status collapsed
15787
15788 \begin_layout Plain Layout
15789 $$AbsOrRelPathParent
15790 \end_layout
15791
15792 \end_inset
15793
15794  in order to preserve the user's choice.
15795 \end_layout
15796
15797 \begin_layout Standard
15798 There are special cases where this rule does not work and e.
15799 \begin_inset space \thinspace{}
15800 \end_inset
15801
15802 g.
15803 \begin_inset space \space{}
15804 \end_inset
15805
15806 relative names are needed, but normally it will work just fine.
15807  One example for such a case is the command
15808 \begin_inset Flex CharStyle:Code
15809 status collapsed
15810
15811 \begin_layout Plain Layout
15812 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15813 \end_layout
15814
15815 \end_inset
15816
15817  in the XFig template above: We can't use the absolute name because the
15818  copier for
15819 \begin_inset Flex CharStyle:Code
15820 status collapsed
15821
15822 \begin_layout Plain Layout
15823 .pstex_t
15824 \end_layout
15825
15826 \end_inset
15827
15828  files needs the relative name in order to rewrite the file content.
15829 \end_layout
15830
15831 \begin_layout Section
15832 \begin_inset CommandInset label
15833 LatexCommand label
15834 name "sec:Security-discussion"
15835
15836 \end_inset
15837
15838 Security discussion
15839 \end_layout
15840
15841 \begin_layout Standard
15842 \begin_inset Box Shadowbox
15843 position "t"
15844 hor_pos "c"
15845 has_inner_box 1
15846 inner_pos "t"
15847 use_parbox 0
15848 width "100col%"
15849 special "none"
15850 height "1in"
15851 height_special "totalheight"
15852 status open
15853
15854 \begin_layout Plain Layout
15855 WARNING: This section is definitely outdated.
15856 \end_layout
15857
15858 \end_inset
15859
15860
15861 \end_layout
15862
15863 \begin_layout Standard
15864 The external material feature interfaces with a lot of external programs
15865  and does so automatically, so we have to consider the security implications
15866  of this.
15867  In particular, since you have the option of including your own filenames
15868  and/or parameter strings and those are expanded into a command, it seems
15869  that it would be possible to create a malicious document which executes
15870  arbitrary commands when a user views or prints the document.
15871  This is something we definitely want to avoid.
15872 \end_layout
15873
15874 \begin_layout Standard
15875 However, since the external program commands are specified in the template
15876  configuration file only, there are no security issues if LyX is properly
15877  configured with safe templates only.
15878  This is so because the external programs are invoked with the
15879 \begin_inset Flex CharStyle:Code
15880 status collapsed
15881
15882 \begin_layout Plain Layout
15883 execvp
15884 \end_layout
15885
15886 \end_inset
15887
15888 -system call rather than the
15889 \begin_inset Flex CharStyle:Code
15890 status collapsed
15891
15892 \begin_layout Plain Layout
15893 system
15894 \end_layout
15895
15896 \end_inset
15897
15898  system-call, so it's not possible to execute arbitrary commands from the
15899  filename or parameter section via the shell.
15900 \end_layout
15901
15902 \begin_layout Standard
15903 This also implies that you are restricted in what command strings you can
15904  use in the external material templates.
15905  In particular, pipes and redirection are not readily available.
15906  This has to be so if LyX should remain safe.
15907  If you want to use some of the shell features, you should write a safe
15908  script to do this in a controlled manner, and then invoke the script from
15909  the command string.
15910  In the
15911 \begin_inset Flex CharStyle:Code
15912 status collapsed
15913
15914 \begin_layout Plain Layout
15915 lib/scripts
15916 \end_layout
15917
15918 \end_inset
15919
15920  directory of the LyX installation, you can find a safe wrapper script
15921 \begin_inset Flex CharStyle:Code
15922 status collapsed
15923
15924 \begin_layout Plain Layout
15925 general_command_wrapper.py
15926 \end_layout
15927
15928 \end_inset
15929
15930  that supports redirection of input and output.
15931  That can serve as an example for how to write safe template scripts.
15932  For a more advanced example that uses
15933 \begin_inset Flex CharStyle:Code
15934 status collapsed
15935
15936 \begin_layout Plain Layout
15937 fork
15938 \end_layout
15939
15940 \end_inset
15941
15942  and friends, take a look at the
15943 \begin_inset Flex CharStyle:Code
15944 status collapsed
15945
15946 \begin_layout Plain Layout
15947 pic2ascii.py
15948 \end_layout
15949
15950 \end_inset
15951
15952  converter script.
15953 \end_layout
15954
15955 \begin_layout Standard
15956 It is possible to design a template that interacts directly with the shell,
15957  but since this would allow a malicious user to execute arbitrary commands
15958  by writing clever filenames and/or parameters, we generally recommend that
15959  you only use safe scripts that work with the
15960 \begin_inset Flex CharStyle:Code
15961 status collapsed
15962
15963 \begin_layout Plain Layout
15964 execvp
15965 \end_layout
15966
15967 \end_inset
15968
15969  system call in a controlled manner.
15970  Of course, for use in a controlled environment, it can be tempting to just
15971  fall back to use ordinary shell scripts.
15972  If you do so, be aware that you
15973 \emph on
15974 will
15975 \emph default
15976  provide an easily exploitable security hole in your system.
15977  Of course it stands to reason that such unsafe templates will never be
15978  included in the standard LyX distribution, although we do encourage people
15979  to submit new templates in the open source tradition.
15980  But LyX as shipped from the official distribution channels will never have
15981  unsafe templates.
15982 \end_layout
15983
15984 \begin_layout Standard
15985 Including external material provides a lot of power, and you have to be
15986  careful not to introduce security hazards with this power.
15987  A subtle error in a single line in an innocent looking script can open
15988  the door to huge security problems.
15989  So if you do not fully understand the issues, we recommend that you consult
15990  a knowledgeable security professional or the LyX development team if you
15991  have any questions about whether a given template is safe or not.
15992  And do this before you use it in an uncontrolled environment.
15993 \end_layout
15994
15995 \end_body
15996 \end_document