lib/doc/Customization.lyx

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