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