lib/doc/Customization.lyx

   1 #LyX 1.6.0rc3 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 340
   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 \begin_modules
  45 logicalmkup
  46 \end_modules
  47 \begin_local_layout
  48 Format 7
  49 InsetLayout CharStyle:MenuItem
  50 LyxType               charstyle
  51 LabelString           menu
  52 LatexType             command
  53 LatexName             menuitem
  54 Font
  55 Family              Sans
  56 EndFont
  57 Preamble
  58 \newcommand*{\menuitem}[1]{{\sffamily #1}}
  59 EndPreamble
  60 End
  61 \end_local_layout
  62 \language english
  63 \inputencoding auto
  64 \font_roman default
  65 \font_sans default
  66 \font_typewriter default
  67 \font_default_family default
  68 \font_sc false
  69 \font_osf false
  70 \font_sf_scale 100
  71 \font_tt_scale 100
  72
  73 \graphics default
  74 \paperfontsize 12
  75 \spacing single
  76 \use_hyperref true
  77 \pdf_title "LyX Configuration Manual"
  78 \pdf_author "LyX Team"
  79 \pdf_subject "LyX-documentation Customization"
  80 \pdf_keywords "LyX, documentation, customization"
  81 \pdf_bookmarks true
  82 \pdf_bookmarksnumbered true
  83 \pdf_bookmarksopen true
  84 \pdf_bookmarksopenlevel 1
  85 \pdf_breaklinks false
  86 \pdf_pdfborder false
  87 \pdf_colorlinks true
  88 \pdf_backref false
  89 \pdf_pagebackref 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 is to be given in a form suitable for inclusion in a LaTeX's
1880
1881 \series bold
1882
1883 \backslash
1884 include
1885 \series default
1886  command and 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 open
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.devel.lyx.org"
3106 target "http://www.devel.lyx.org"
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 \family default
4389 \shape default
4390 \emph default
4391
4392 \family roman
4393 \shape up
4394  is produced.
4395  If such a declaration does not exist in
4396 \family default
4397 \shape default
4398
4399 \shape up
4400 the
4401 \shape default
4402
4403 \begin_inset Flex CharStyle:Code
4404 status collapsed
4405
4406 \begin_layout Plain Layout
4407
4408 \shape up
4409 .kmap
4410 \end_layout
4411
4412 \end_inset
4413
4414  file and yo
4415 \family roman
4416 u enter
4417 \family default
4418
4419 \family roman
4420 \emph on
4421 accent  char
4422 \emph default
4423 , you get
4424 \family default
4425
4426 \family roman
4427 \emph on
4428 accent_key char
4429 \family default
4430 \emph default
4431
4432 \family roman
4433  where
4434 \family default
4435
4436 \family roman
4437 \emph on
4438 accent_key
4439 \family default
4440 \emph default
4441
4442 \family roman
4443  is the first arg
4444 \family default
4445 ument of the
4446 \begin_inset Flex CharStyle:Code
4447 status collapsed
4448
4449 \begin_layout Plain Layout
4450
4451 \shape up
4452
4453 \backslash
4454 kmod
4455 \end_layout
4456
4457 \end_inset
4458
4459  declaration.
4460
4461 \end_layout
4462
4463 \begin_layout Standard
4464 The following command produces causes äi to be produced when you enter acute-i
4465  ('i):
4466 \end_layout
4467
4468 \begin_layout LyX-Code
4469
4470 \backslash
4471 kxmod acute i "
4472 \backslash
4473
4474 \backslash
4475 '{
4476 \backslash
4477
4478 \backslash
4479 i}"
4480 \end_layout
4481
4482 \begin_layout Labeling
4483 \labelwidthstring 00.00.0000
4484 \begin_inset Flex CharStyle:Code
4485 status collapsed
4486
4487 \begin_layout Plain Layout
4488 kcomb
4489 \end_layout
4490
4491 \end_inset
4492
4493  Combine two accent characters
4494 \end_layout
4495
4496 \begin_layout LyX-Code
4497
4498 \backslash
4499 kcomb
4500 \family roman
4501 \emph on
4502 accent1 accent2 allowed
4503 \end_layout
4504
4505 \begin_layout Standard
4506 This one is getting pretty esoteric.
4507  It allows you to combine the effect
4508 \family roman
4509 of
4510 \family default
4511
4512 \family roman
4513 \emph on
4514 accent1
4515 \family default
4516 \emph default
4517
4518 \family roman
4519 and
4520 \family default
4521
4522 \family roman
4523 \emph on
4524 accent2
4525 \family default
4526 \emph default
4527
4528 \family roman
4529 (in that order!) on
4530 \family default
4531
4532 \family roman
4533 \emph on
4534 allowed
4535 \family default
4536 \emph default
4537
4538 \family roman
4539 chars.
4540  The keystrokes for
4541 \family default
4542
4543 \family roman
4544 \emph on
4545 accent1
4546 \family default
4547 \emph default
4548
4549 \family roman
4550 and
4551 \family default
4552
4553 \family roman
4554 \emph on
4555 accent2
4556 \family default
4557 \emph default
4558
4559 \family roman
4560 must have be
4561 \family default
4562 en set with a
4563 \begin_inset Flex CharStyle:Code
4564 status collapsed
4565
4566 \begin_layout Plain Layout
4567
4568 \shape up
4569
4570 \backslash
4571 kmod
4572 \end_layout
4573
4574 \end_inset
4575
4576  command at
4577 \family roman
4578 a
4579 \family default
4580
4581 \family roman
4582 \emph on
4583 previous
4584 \family default
4585 \emph default
4586
4587 \family roman
4588 point in the
4589 \family default
4590  file.
4591
4592 \end_layout
4593
4594 \begin_layout Standard
4595 Consider this example from the
4596 \begin_inset Flex CharStyle:Code
4597 status collapsed
4598
4599 \begin_layout Plain Layout
4600
4601 \shape up
4602 greek.kmap
4603 \end_layout
4604
4605 \end_inset
4606
4607  file:
4608 \end_layout
4609
4610 \begin_layout LyX-Code
4611
4612 \backslash
4613 kmod ; acute aeioyvhAEIOYVH
4614 \backslash
4615 kmod : umlaut iyIY
4616 \backslash
4617 kcomb acute umlaut iyIY
4618 \end_layout
4619
4620 \begin_layout Standard
4621 This allows you to press
4622 \begin_inset Flex CharStyle:MenuItem
4623 status collapsed
4624
4625 \begin_layout Plain Layout
4626
4627 \shape up
4628 ;:i
4629 \end_layout
4630
4631 \end_inset
4632
4633  and get the effect of
4634 \begin_inset Flex CharStyle:Code
4635 status collapsed
4636
4637 \begin_layout Plain Layout
4638
4639 \shape up
4640
4641 \backslash
4642 '{
4643 \backslash
4644 "{i}}
4645 \end_layout
4646
4647 \end_inset
4648
4649 .
4650
4651 \family roman
4652 \shape up
4653 A backspace
4654 \family default
4655 \shape default
4656  in this case cancels the last dead key, so if you press
4657 \begin_inset Flex CharStyle:MenuItem
4658 status collapsed
4659
4660 \begin_layout Plain Layout
4661
4662 \shape up
4663 ;: Backspace i
4664 \end_layout
4665
4666 \end_inset
4667
4668  you get
4669 \begin_inset Flex CharStyle:Code
4670 status collapsed
4671
4672 \begin_layout Plain Layout
4673
4674 \shape up
4675
4676 \backslash
4677 '{i}
4678 \end_layout
4679
4680 \end_inset
4681
4682 .
4683 \end_layout
4684
4685 \begin_layout Subsection
4686 The .cdef File
4687 \end_layout
4688
4689 \begin_layout Standard
4690 After the
4691 \begin_inset Flex CharStyle:Code
4692 status collapsed
4693
4694 \begin_layout Plain Layout
4695
4696 \shape up
4697 .kmap
4698 \end_layout
4699
4700 \end_inset
4701
4702  mapping is performed, a
4703 \begin_inset Flex CharStyle:Code
4704 status collapsed
4705
4706 \begin_layout Plain Layout
4707
4708 \shape up
4709 .cde
4710 \shape default
4711 f
4712 \end_layout
4713
4714 \end_inset
4715
4716  file maps the strings that the symbols generate to characters in the current
4717  font.
4718  The LyX distribution currently includes at least the
4719 \begin_inset Flex CharStyle:Code
4720 status collapsed
4721
4722 \begin_layout Plain Layout
4723
4724 \shape up
4725 iso8859-1.cdef
4726 \end_layout
4727
4728 \end_inset
4729
4730  and
4731 \begin_inset Flex CharStyle:Code
4732 status collapsed
4733
4734 \begin_layout Plain Layout
4735
4736 \shape up
4737 iso8859-2.cdef
4738 \end_layout
4739
4740 \end_inset
4741
4742  files.
4743 \end_layout
4744
4745 \begin_layout Standard
4746 In general the
4747 \begin_inset Flex CharStyle:Code
4748 status collapsed
4749
4750 \begin_layout Plain Layout
4751
4752 \shape up
4753 .cdef
4754 \end_layout
4755
4756 \end_inset
4757
4758  file is a sequence of declarations of the form
4759 \end_layout
4760
4761 \begin_layout LyX-Code
4762
4763 \family roman
4764 \emph on
4765 char_index_in_set
4766 \family default
4767 \emph default
4768
4769 \family roman
4770 \emph on
4771  string
4772 \end_layout
4773
4774 \begin_layout Standard
4775 For example, in order to map
4776 \begin_inset Flex CharStyle:MenuItem
4777 status collapsed
4778
4779 \begin_layout Plain Layout
4780
4781 \shape up
4782
4783 \backslash
4784 '{e}
4785 \end_layout
4786
4787 \end_inset
4788
4789  to the corresponding character in the iso-8859-1 set (233), the following
4790  declaration is used
4791 \end_layout
4792
4793 \begin_layout LyX-Code
4794 233 "
4795 \backslash
4796
4797 \backslash
4798 '{e}"
4799 \end_layout
4800
4801 \begin_layout Standard
4802 with
4803 \begin_inset Flex CharStyle:Code
4804 status collapsed
4805
4806 \begin_layout Plain Layout
4807
4808 \backslash
4809
4810 \end_layout
4811
4812 \end_inset
4813
4814  and
4815 \begin_inset Flex CharStyle:Code
4816 status collapsed
4817
4818 \begin_layout Plain Layout
4819 "
4820 \end_layout
4821
4822 \end_inset
4823
4824  being escap
4825 \family roman
4826 ed in
4827 \family default
4828
4829 \family roman
4830 \emph on
4831 string
4832 \emph default
4833 .
4834  Note that
4835 \family default
4836  the same character can apply to more than one string.
4837  In the
4838 \begin_inset Flex CharStyle:Code
4839 status collapsed
4840
4841 \begin_layout Plain Layout
4842 i
4843 \shape up
4844 so-8859-7.cdef
4845 \end_layout
4846
4847 \end_inset
4848
4849  file you have
4850 \end_layout
4851
4852 \begin_layout LyX-Code
4853 192 "
4854 \backslash
4855
4856 \backslash
4857 '{
4858 \backslash
4859
4860 \backslash
4861
4862 \backslash
4863 "{i}}"
4864 \begin_inset Newline newline
4865 \end_inset
4866
4867 192 "
4868 \backslash
4869
4870 \backslash
4871
4872 \backslash
4873 "{
4874 \backslash
4875
4876 \backslash
4877 '{i}}"
4878 \end_layout
4879
4880 \begin_layout Standard
4881 If LyX cannot find a mapping for the string produced by the keystroke or
4882  a deadkey sequence, it will check if it looks like an accented char and
4883  try to draw an accent over the character on screen.
4884 \end_layout
4885
4886 \begin_layout Subsection
4887 Dead Keys
4888 \end_layout
4889
4890 \begin_layout Standard
4891 There is a second way to add support for international characters through
4892  so-called dead-keys.
4893  A dead-key works in combination with a letter to produce an accented character.
4894  Here, we'll explain how to create a really simple dead-key to illustrate
4895  how they work.
4896 \end_layout
4897
4898 \begin_layout Standard
4899 Suppose you happen to need the circumflex character,
4900 \begin_inset Quotes eld
4901 \end_inset
4902
4903  ̂
4904 \begin_inset Quotes erd
4905 \end_inset
4906
4907 .
4908  You could bind the
4909 \begin_inset Flex CharStyle:MenuItem
4910 status collapsed
4911
4912 \begin_layout Plain Layout
4913 ^
4914 \end_layout
4915
4916 \end_inset
4917
4918 -key [a.k.a.
4919 \begin_inset space ~
4920 \end_inset
4921
4922
4923 \begin_inset Flex CharStyle:MenuItem
4924 status collapsed
4925
4926 \begin_layout Plain Layout
4927 Shift-6
4928 \end_layout
4929
4930 \end_inset
4931
4932 ] to the LyX command
4933 \begin_inset Flex CharStyle:Code
4934 status collapsed
4935
4936 \begin_layout Plain Layout
4937 accent-circumflex
4938 \end_layout
4939
4940 \end_inset
4941
4942  in your
4943 \begin_inset Flex CharStyle:Code
4944 status collapsed
4945
4946 \begin_layout Plain Layout
4947 lyxrc
4948 \end_layout
4949
4950 \end_inset
4951
4952  file.
4953  Now, whenever you type the
4954 \begin_inset Flex CharStyle:MenuItem
4955 status collapsed
4956
4957 \begin_layout Plain Layout
4958 ^
4959 \end_layout
4960
4961 \end_inset
4962
4963 -key followed by a letter, that letter will have a circumflex accent on
4964  it.
4965  For example, the sequence
4966 \begin_inset Quotes eld
4967 \end_inset
4968
4969
4970 \begin_inset Flex CharStyle:MenuItem
4971 status collapsed
4972
4973 \begin_layout Plain Layout
4974 ^e
4975 \end_layout
4976
4977 \end_inset
4978
4979
4980 \begin_inset Quotes erd
4981 \end_inset
4982
4983  produces the letter:
4984 \begin_inset Quotes eld
4985 \end_inset
4986
4987 ê
4988 \begin_inset Quotes erd
4989 \end_inset
4990
4991 .
4992  If you tried to type
4993 \begin_inset Quotes eld
4994 \end_inset
4995
4996
4997 \begin_inset Flex CharStyle:MenuItem
4998 status collapsed
4999
5000 \begin_layout Plain Layout
5001 ^t
5002 \end_layout
5003
5004 \end_inset
5005
5006
5007 \begin_inset Quotes erd
5008 \end_inset
5009
5010 , however, LyX will complain with a beep, since a
5011 \begin_inset Quotes eld
5012 \end_inset
5013
5014
5015 \begin_inset Flex CharStyle:MenuItem
5016 status collapsed
5017
5018 \begin_layout Plain Layout
5019 t
5020 \end_layout
5021
5022 \end_inset
5023
5024
5025 \begin_inset Quotes erd
5026 \end_inset
5027
5028  never takes a circumflex accent.
5029  Hitting
5030 \begin_inset Flex CharStyle:MenuItem
5031 status collapsed
5032
5033 \begin_layout Plain Layout
5034 Space
5035 \end_layout
5036
5037 \end_inset
5038
5039  after a dead-key produces the bare-accent.
5040  Please note this last point! If you bind a key to a dead-key, you'll need
5041  to rebind the character on that key to yet another key.
5042  Binding the
5043 \begin_inset Flex CharStyle:MenuItem
5044 status collapsed
5045
5046 \begin_layout Plain Layout
5047 ,-key
5048 \end_layout
5049
5050 \end_inset
5051
5052  to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5053 \end_layout
5054
5055 \begin_layout Standard
5056 One common way to bind dead-keys is to use
5057 \begin_inset Flex CharStyle:MenuItem
5058 status collapsed
5059
5060 \begin_layout Plain Layout
5061 Meta-
5062 \end_layout
5063
5064 \end_inset
5065
5066 ,
5067 \begin_inset Flex CharStyle:MenuItem
5068 status collapsed
5069
5070 \begin_layout Plain Layout
5071 Ctrl-
5072 \end_layout
5073
5074 \end_inset
5075
5076 , and
5077 \begin_inset Flex CharStyle:MenuItem
5078 status collapsed
5079
5080 \begin_layout Plain Layout
5081 Shift-
5082 \end_layout
5083
5084 \end_inset
5085
5086  in combination with an accent, like
5087 \begin_inset Quotes eld
5088 \end_inset
5089
5090
5091 \begin_inset Flex CharStyle:MenuItem
5092 status collapsed
5093
5094 \begin_layout Plain Layout
5095 ~
5096 \end_layout
5097
5098 \end_inset
5099
5100
5101 \begin_inset Quotes erd
5102 \end_inset
5103
5104  or
5105 \begin_inset Quotes eld
5106 \end_inset
5107
5108
5109 \begin_inset Flex CharStyle:MenuItem
5110 status collapsed
5111
5112 \begin_layout Plain Layout
5113 ,
5114 \end_layout
5115
5116 \end_inset
5117
5118
5119 \begin_inset Quotes erd
5120 \end_inset
5121
5122  or
5123 \begin_inset Quotes eld
5124 \end_inset
5125
5126
5127 \begin_inset Flex CharStyle:MenuItem
5128 status collapsed
5129
5130 \begin_layout Plain Layout
5131 ^
5132 \end_layout
5133
5134 \end_inset
5135
5136
5137 \begin_inset Quotes erd
5138 \end_inset
5139
5140 .
5141  Another way involves using
5142 \begin_inset Flex CharStyle:Code
5143 status collapsed
5144
5145 \begin_layout Plain Layout
5146 xmodmap
5147 \end_layout
5148
5149 \end_inset
5150
5151  and
5152 \begin_inset Flex CharStyle:Code
5153 status collapsed
5154
5155 \begin_layout Plain Layout
5156 xkeycaps
5157 \end_layout
5158
5159 \end_inset
5160
5161   to set up the special
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  key.
5172  The
5173 \begin_inset Flex CharStyle:Code
5174 status collapsed
5175
5176 \begin_layout Plain Layout
5177 Mode_Switch
5178 \end_layout
5179
5180 \end_inset
5181
5182  acts in some ways just like
5183 \begin_inset Flex CharStyle:MenuItem
5184 status collapsed
5185
5186 \begin_layout Plain Layout
5187 Shift
5188 \end_layout
5189
5190 \end_inset
5191
5192  and permits you to bind keys to accented characters.
5193  You can also turn keys into dead-keys by binding them to something like
5194
5195 \begin_inset Flex CharStyle:Code
5196 status collapsed
5197
5198 \begin_layout Plain Layout
5199 usldead_cedilla
5200 \end_layout
5201
5202 \end_inset
5203
5204  and then binding this symbolic key to the corresponding LyX command.
5205 \begin_inset Foot
5206 status collapsed
5207
5208 \begin_layout Plain Layout
5209 Note from
5210 \noun on
5211 John Weiss
5212 \noun default
5213 : This is exactly what I do in my
5214 \begin_inset Flex CharStyle:Code
5215 status collapsed
5216
5217 \begin_layout Plain Layout
5218 ~/.lyx/lyxrc
5219 \end_layout
5220
5221 \end_inset
5222
5223  and my
5224 \begin_inset Flex CharStyle:Code
5225 status collapsed
5226
5227 \begin_layout Plain Layout
5228 ~/.xmodmap
5229 \end_layout
5230
5231 \end_inset
5232
5233  files.
5234  I have my
5235 \begin_inset Flex CharStyle:MenuItem
5236 status collapsed
5237
5238 \begin_layout Plain Layout
5239 Scroll
5240 \begin_inset space ~
5241 \end_inset
5242
5243 Lock
5244 \end_layout
5245
5246 \end_inset
5247
5248  key set up as
5249 \begin_inset Flex CharStyle:Code
5250 status collapsed
5251
5252 \begin_layout Plain Layout
5253 Mode_Shift
5254 \end_layout
5255
5256 \end_inset
5257
5258  and a bunch of these
5259 \begin_inset Quotes eld
5260 \end_inset
5261
5262
5263 \begin_inset Flex CharStyle:Code
5264 status collapsed
5265
5266 \begin_layout Plain Layout
5267 usldead_*
5268 \end_layout
5269
5270 \end_inset
5271
5272
5273 \begin_inset Quotes erd
5274 \end_inset
5275
5276  symbolic keys bound such things as
5277 \begin_inset Flex CharStyle:MenuItem
5278 status collapsed
5279
5280 \begin_layout Plain Layout
5281 Scroll
5282 \begin_inset space ~
5283 \end_inset
5284
5285 Lock-^
5286 \end_layout
5287
5288 \end_inset
5289
5290  and
5291 \begin_inset Flex CharStyle:MenuItem
5292 status collapsed
5293
5294 \begin_layout Plain Layout
5295 Scroll
5296 \begin_inset space ~
5297 \end_inset
5298
5299 Lock-~
5300 \end_layout
5301
5302 \end_inset
5303
5304 .
5305  This is how I produce my accented characters.
5306 \end_layout
5307
5308 \end_inset
5309
5310  You can make just about anything into the
5311 \begin_inset Flex CharStyle:Code
5312 status collapsed
5313
5314 \begin_layout Plain Layout
5315 Mode_Switch
5316 \end_layout
5317
5318 \end_inset
5319
5320  key: One of the
5321 \begin_inset Flex CharStyle:MenuItem
5322 status collapsed
5323
5324 \begin_layout Plain Layout
5325 Ctrl-
5326 \end_layout
5327
5328 \end_inset
5329
5330  keys, a spare function key, etc.
5331  As for the LyX commands that produce accents, check the entry for
5332 \begin_inset Flex CharStyle:Code
5333 status collapsed
5334
5335 \begin_layout Plain Layout
5336 accent-acute
5337 \end_layout
5338
5339 \end_inset
5340
5341  in the
5342 \emph on
5343 Reference Manual
5344 \emph default
5345 .
5346  You'll find the complete list there.
5347 \end_layout
5348
5349 \begin_layout Subsection
5350 Saving your Language Configuration
5351 \end_layout
5352
5353 \begin_layout Standard
5354 You can edit your preferences so that your desired language environment
5355  is automatically configured when LyX starts up, via the
5356 \begin_inset Flex CharStyle:MenuItem
5357 status collapsed
5358
5359 \begin_layout Plain Layout
5360
5361 \bar under
5362 E
5363 \bar default
5364 dit\SpecialChar \menuseparator
5365
5366 \bar under
5367 P
5368 \bar default
5369 references
5370 \end_layout
5371
5372 \end_inset
5373
5374  dialog.
5375 \end_layout
5376
5377 \begin_layout Chapter
5378 Installing New Document Classes, Layouts, and Templates
5379 \begin_inset CommandInset label
5380 LatexCommand label
5381 name "chap:textclass"
5382
5383 \end_inset
5384
5385
5386 \begin_inset OptArg
5387 status collapsed
5388
5389 \begin_layout Plain Layout
5390 Installing New Document Classes
5391 \end_layout
5392
5393 \end_inset
5394
5395
5396 \end_layout
5397
5398 \begin_layout Standard
5399 In this chapter, we describe the procedures for creating and installing
5400  new LyX layout and template files, as well as offer a refresher on correctly
5401  installing new LaTeX document classes.
5402  Some definitions: a document class is a LaTeX file (usually ending in
5403 \begin_inset Flex CharStyle:Code
5404 status collapsed
5405
5406 \begin_layout Plain Layout
5407 .cls
5408 \end_layout
5409
5410 \end_inset
5411
5412  or
5413 \begin_inset Flex CharStyle:Code
5414 status collapsed
5415
5416 \begin_layout Plain Layout
5417 .sty
5418 \end_layout
5419
5420 \end_inset
5421
5422 ) that describes the format of a document such as an article, report, journal
5423  preprint, etc, and all the commands needed to realize that format.
5424  A layout file is a LyX file that corresponds to a LaTeX document class
5425  and that tells LyX how to
5426 \begin_inset Quotes eld
5427 \end_inset
5428
5429 draw
5430 \begin_inset Quotes erd
5431 \end_inset
5432
5433  things on the screen to make the display look something like the final
5434  printed page.
5435  More precisely, a layout file describes a
5436 \begin_inset Quotes eld
5437 \end_inset
5438
5439 text class
5440 \begin_inset Quotes erd
5441 \end_inset
5442
5443  which is the internal construct LyX uses to render the screen display.
5444
5445 \begin_inset Quotes eld
5446 \end_inset
5447
5448 Layout
5449 \begin_inset Quotes erd
5450 \end_inset
5451
5452  and
5453 \begin_inset Quotes eld
5454 \end_inset
5455
5456 text class
5457 \begin_inset Quotes erd
5458 \end_inset
5459
5460  can be used somewhat interchangeably, but it is better to refer to the
5461  file as the layout, and the thing living in LyX's memory as the text class.
5462  A template file is simply a LyX document that contains a set of predefined
5463  entries for a given document class---entries that are generally required
5464  for that class.
5465  Templates are especially useful for things like journal manuscripts that
5466  are to be submitted electronically.
5467 \end_layout
5468
5469 \begin_layout Section
5470 Installing a new LaTeX package
5471 \end_layout
5472
5473 \begin_layout Standard
5474 Some installations may not include a LaTeX package that you would like to
5475  use within LyX.
5476  For example, you might need FoilTeX, a package for preparing slides or
5477  viewgraphs for overhead projectors.
5478  Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5479  a user interface for that.
5480  For example on MiKTeX you start its program
5481 \begin_inset Quotes eld
5482 \end_inset
5483
5484 Browse Packages
5485 \begin_inset Quotes erd
5486 \end_inset
5487
5488  to get a list of available packages.
5489  To install one, right click on it or use the installing toolbar button.
5490  When the package you want to install is not in the list, but you have it
5491  in form of a
5492 \begin_inset Flex CharStyle:Code
5493 status collapsed
5494
5495 \begin_layout Plain Layout
5496 .cls
5497 \end_layout
5498
5499 \end_inset
5500
5501  or
5502 \begin_inset Flex CharStyle:Code
5503 status collapsed
5504
5505 \begin_layout Plain Layout
5506 .sty
5507 \end_layout
5508
5509 \end_inset
5510
5511 -file, then copy these files to a subfolder of your LaTeX distribution,
5512  for example to the folder
5513 \family sans
5514 ~
5515 \backslash
5516 tex
5517 \backslash
5518 latex
5519 \family default
5520 .
5521  Then update the file name database of your LaTeX-distribution.
5522  For example on MiKTeX this is done by pressing the button
5523 \family sans
5524 Refresh
5525 \begin_inset space ~
5526 \end_inset
5527
5528 FNDB
5529 \family default
5530  that you find in MiKTeX's
5531 \begin_inset Quotes eld
5532 \end_inset
5533
5534 Settings
5535 \begin_inset Quotes erd
5536 \end_inset
5537
5538  program.
5539  In both cases you need afterwards to reconfigure LyX using the menu
5540 \begin_inset Flex CharStyle:MenuItem
5541 status collapsed
5542
5543 \begin_layout Plain Layout
5544 Tools\SpecialChar \menuseparator
5545 Reconfigure
5546 \end_layout
5547
5548 \end_inset
5549
5550  and then to restart LyX.
5551 \end_layout
5552
5553 \begin_layout Standard
5554 If your LaTeX distribution doesn't provide a user interface, then you can
5555  follow these steps by using a UNIX/Linux console.
5556 \end_layout
5557
5558 \begin_layout Enumerate
5559 Get the package from
5560 \begin_inset CommandInset href
5561 LatexCommand href
5562 name "CTAN"
5563 target "http://www.ctan.org/"
5564
5565 \end_inset
5566
5567  or wherever.
5568 \end_layout
5569
5570 \begin_layout Enumerate
5571 You can install this package in several different places.
5572  If you want it to be available for all users on your system, then you should
5573  install it in your `local' TeX tree; if you want (or need) it to be available
5574  just for you, then you can install it in your own `user' TeX tree.
5575  Where these should be created, if they do not already exist, depends upon
5576  the details of your system.
5577  To find out, look in the file
5578 \begin_inset Flex CharStyle:Code
5579 status collapsed
5580
5581 \begin_layout Plain Layout
5582 texmf.cnf
5583 \end_layout
5584
5585 \end_inset
5586
5587 .
5588 \begin_inset Foot
5589 status collapsed
5590
5591 \begin_layout Plain Layout
5592 This usually lives in the directory
5593 \begin_inset Flex CharStyle:Code
5594 status collapsed
5595
5596 \begin_layout Plain Layout
5597 $TEXMF/web2c
5598 \end_layout
5599
5600 \end_inset
5601
5602 , though you can run
5603 \begin_inset Flex CharStyle:Code
5604 status collapsed
5605
5606 \begin_layout Plain Layout
5607 kpsewhich texmf.cnf
5608 \end_layout
5609
5610 \end_inset
5611
5612  to locate it.
5613 \end_layout
5614
5615 \end_inset
5616
5617  The location of the `local' TeX tree is defined by
5618 \begin_inset Flex CharStyle:Code
5619 status collapsed
5620
5621 \begin_layout Plain Layout
5622 TEXMFLOCAL
5623 \end_layout
5624
5625 \end_inset
5626
5627 ; this is usually somewhere like
5628 \begin_inset Flex CharStyle:Code
5629 status collapsed
5630
5631 \begin_layout Plain Layout
5632 /usr/local/share/texmf/
5633 \end_layout
5634
5635 \end_inset
5636
5637 .
5638  The `user' TeX tree is defined by
5639 \begin_inset Flex CharStyle:Code
5640 status collapsed
5641
5642 \begin_layout Plain Layout
5643 TEXMFHOME
5644 \end_layout
5645
5646 \end_inset
5647
5648  and is commonly at
5649 \begin_inset Flex CharStyle:Code
5650 status collapsed
5651
5652 \begin_layout Plain Layout
5653 $HOME/texmf/
5654 \end_layout
5655
5656 \end_inset
5657
5658 .
5659  (If these variables are not predefined, you can define them.) You'll probably
5660  need root permissions to create or modify the `local' tree; but your `user'
5661  tree shouldn't have such limitations.
5662 \end_layout
5663
5664 \begin_layout Enumerate
5665 Make sure
5666 \begin_inset Flex CharStyle:Code
5667 status collapsed
5668
5669 \begin_layout Plain Layout
5670 TEXMF
5671 \end_layout
5672
5673 \end_inset
5674
5675  includes the
5676 \begin_inset Flex CharStyle:Code
5677 status collapsed
5678
5679 \begin_layout Plain Layout
5680 TEXMFLOCAL
5681 \end_layout
5682
5683 \end_inset
5684
5685  and
5686 \begin_inset Flex CharStyle:Code
5687 status collapsed
5688
5689 \begin_layout Plain Layout
5690 TEXMFHOME
5691 \end_layout
5692
5693 \end_inset
5694
5695  variables; e.g.
5696 \begin_inset Newline newline
5697 \end_inset
5698
5699
5700 \begin_inset Flex CharStyle:Code
5701 status collapsed
5702
5703 \begin_layout Plain Layout
5704 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5705 \end_layout
5706
5707 \end_inset
5708
5709
5710 \begin_inset Newline newline
5711 \end_inset
5712
5713 But, again, most of this will
5714 \begin_inset Quotes eld
5715 \end_inset
5716
5717 just work
5718 \begin_inset Quotes erd
5719 \end_inset
5720
5721 .
5722 \end_layout
5723
5724 \begin_layout Enumerate
5725 Create your local
5726 \begin_inset Foot
5727 status collapsed
5728
5729 \begin_layout Plain Layout
5730 We'll assume henceforth that you're defining `local' TeX tree.
5731  If you're defining a user tree, just adjust as necessary.
5732 \end_layout
5733
5734 \end_inset
5735
5736  TeX tree.
5737  You must follow the directory structure of your existing
5738 \begin_inset Flex CharStyle:Code
5739 status collapsed
5740
5741 \begin_layout Plain Layout
5742 texmf
5743 \end_layout
5744
5745 \end_inset
5746
5747  directory, which will be found at
5748 \begin_inset Flex CharStyle:Code
5749 status collapsed
5750
5751 \begin_layout Plain Layout
5752 TEXMFMAIN
5753 \end_layout
5754
5755 \end_inset
5756
5757 .
5758  For example, latex packages should go under
5759 \begin_inset Flex CharStyle:Code
5760 status collapsed
5761
5762 \begin_layout Plain Layout
5763 $TEXMFLOCAL/tex/latex/
5764 \end_layout
5765
5766 \end_inset
5767
5768 .
5769 \end_layout
5770
5771 \begin_layout Enumerate
5772 Install the package.
5773  For example, you would unpack the FoilTeX tarball and copy it to
5774 \begin_inset Flex CharStyle:Code
5775 status collapsed
5776
5777 \begin_layout Plain Layout
5778 $TEXMFLOCAL/tex/latex/foiltex
5779 \end_layout
5780
5781 \end_inset
5782
5783 .
5784  The
5785 \begin_inset Flex CharStyle:Code
5786 status collapsed
5787
5788 \begin_layout Plain Layout
5789 foiltex
5790 \end_layout
5791
5792 \end_inset
5793
5794  directory contains various files.
5795 \end_layout
5796
5797 \begin_layout Enumerate
5798 Run:
5799 \begin_inset Flex CharStyle:Code
5800 status collapsed
5801
5802 \begin_layout Plain Layout
5803 texhash
5804 \end_layout
5805
5806 \end_inset
5807
5808 .
5809  This should create
5810 \begin_inset Flex CharStyle:Code
5811 status collapsed
5812
5813 \begin_layout Plain Layout
5814 $TEXMFLOCAL/ls-R
5815 \end_layout
5816
5817 \end_inset
5818
5819  amongst others.
5820 \end_layout
5821
5822 \begin_layout Standard
5823 Your package is now installed and available to LaTeX.
5824  To make it available to LyX, you need to create a Layout file, if one is
5825  not already available.
5826  (See the next section.) Once you have a layout file, you need only reconfigure
5827  (
5828 \begin_inset Flex CharStyle:MenuItem
5829 status collapsed
5830
5831 \begin_layout Plain Layout
5832 Tools\SpecialChar \menuseparator
5833 Reconfigure
5834 \end_layout
5835
5836 \end_inset
5837
5838 ) and then restart LyX.
5839  You should then see your new package---for example
5840 \begin_inset Flex CharStyle:MenuItem
5841 status collapsed
5842
5843 \begin_layout Plain Layout
5844 slides (FoilTeX)
5845 \end_layout
5846
5847 \end_inset
5848
5849 ---under
5850 \begin_inset Flex CharStyle:MenuItem
5851 status collapsed
5852
5853 \begin_layout Plain Layout
5854 Document\SpecialChar \menuseparator
5855 Settings
5856 \end_layout
5857
5858 \end_inset
5859
5860  in the
5861 \begin_inset Flex CharStyle:MenuItem
5862 status collapsed
5863
5864 \begin_layout Plain Layout
5865 Document Class
5866 \end_layout
5867
5868 \end_inset
5869
5870  drop box.
5871
5872 \end_layout
5873
5874 \begin_layout Section
5875 Layouts
5876 \end_layout
5877
5878 \begin_layout Standard
5879 This section describes how to write and install your own LyX layout files
5880  and walks through the
5881 \begin_inset Flex CharStyle:Code
5882 status collapsed
5883
5884 \begin_layout Plain Layout
5885 article
5886 \end_layout
5887
5888 \end_inset
5889
5890  text class format as an example.
5891  The
5892 \begin_inset Flex CharStyle:Code
5893 status collapsed
5894
5895 \begin_layout Plain Layout
5896 .layout
5897 \end_layout
5898
5899 \end_inset
5900
5901  files describe what paragraph and character styles are available for a
5902  given document class and how LyX should display them.
5903  We try to provide a thorough description of the process here; however,
5904  there are so many different types of documents supported by LaTeX classes
5905  that we can't hope to cover every different possibility or problem you
5906  might encounter.
5907  (The LyX users' list is frequented by people with lots of experience with
5908  layout design who are willing to share what they've learned.)
5909 \end_layout
5910
5911 \begin_layout Standard
5912 As you prepare to write a new layout, it is extremely helpful to look at
5913  the example layouts distributed with LyX.
5914  If you use a nice LaTeX document class that might be of interest for others,
5915  too, and have a nice corresponding LyX layout, feel free to contribute
5916  the stuff to us, so we may put it into the distribution.
5917  There is also a
5918 \begin_inset CommandInset href
5919 LatexCommand href
5920 name "section on the LyX wiki"
5921 target "http://wiki.lyx.org/Layouts/Layouts"
5922
5923 \end_inset
5924
5925  for this kind of material.
5926 \end_layout
5927
5928 \begin_layout Standard
5929 All the tags described in this chapter are case-insensitive; this means
5930  that
5931 \begin_inset Flex CharStyle:Code
5932 status collapsed
5933
5934 \begin_layout Plain Layout
5935 Style
5936 \end_layout
5937
5938 \end_inset
5939
5940 ,
5941 \begin_inset Flex CharStyle:Code
5942 status collapsed
5943
5944 \begin_layout Plain Layout
5945 style
5946 \end_layout
5947
5948 \end_inset
5949
5950  and
5951 \begin_inset Flex CharStyle:Code
5952 status collapsed
5953
5954 \begin_layout Plain Layout
5955 StYlE
5956 \end_layout
5957
5958 \end_inset
5959
5960  are really the same command.
5961  The possible values are printed in brackets after the feature's name.
5962  The default value if a feature isn't specified inside a text class-description
5963  is typeset
5964 \begin_inset Flex CharStyle:Code
5965 status collapsed
5966
5967 \begin_layout Plain Layout
5968
5969 \emph on
5970 emphasized
5971 \end_layout
5972
5973 \end_inset
5974
5975 .
5976  If the argument has a datatype like
5977 \begin_inset Quotes eld
5978 \end_inset
5979
5980 string
5981 \begin_inset Quotes erd
5982 \end_inset
5983
5984  or
5985 \begin_inset Quotes eld
5986 \end_inset
5987
5988 float
5989 \begin_inset Quotes erd
5990 \end_inset
5991
5992 , the default is shown like this:
5993 \begin_inset Flex CharStyle:Code
5994 status collapsed
5995
5996 \begin_layout Plain Layout
5997 float=
5998 \emph on
5999 default
6000 \end_layout
6001
6002 \end_inset
6003
6004 .
6005 \end_layout
6006
6007 \begin_layout Subsection
6008 Layout modules
6009 \end_layout
6010
6011 \begin_layout Standard
6012 Similar to layout files, and new with LyX 1.6, are layout
6013 \emph on
6014 modules
6015 \emph default
6016 .
6017  Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6018  some modules---such as the Endnotes module---provide support for just such
6019  a package.
6020  In a sense, layout modules are similar to included files---files like
6021 \begin_inset Flex CharStyle:Code
6022 status collapsed
6023
6024 \begin_layout Plain Layout
6025 stdsections.inc
6026 \end_layout
6027
6028 \end_inset
6029
6030 ---in that modules are not specific to a given document layout but may be
6031  used with many different layouts.
6032  The difference is that using a layout module does not require editing the
6033  layout file.
6034  Rather, modules are selected in the
6035 \begin_inset Flex CharStyle:MenuItem
6036 status collapsed
6037
6038 \begin_layout Plain Layout
6039 Document\SpecialChar \menuseparator
6040 Settings
6041 \end_layout
6042
6043 \end_inset
6044
6045  dialog.
6046 \end_layout
6047
6048 \begin_layout Standard
6049 Building modules is the easiest way to get started with layout editing,
6050  since it can be as simple as adding a single new paragraph or flex inset.
6051  But modules may, in principle, contain anything a layout file can contain.
6052 \end_layout
6053
6054 \begin_layout Standard
6055 A module must begin with a line like the following:
6056 \end_layout
6057
6058 \begin_layout LyX-Code
6059 #
6060 \backslash
6061 DeclareLyXModule[endnotes.sty]{Endnotes}
6062 \end_layout
6063
6064 \begin_layout Standard
6065 The argument in square brackets is optional: It declares any LaTeX packages
6066  on which the module depends.
6067  The mandatory argument, in curly brackets, is the name of the module, as
6068  it should appear in
6069 \begin_inset Flex CharStyle:MenuItem
6070 status collapsed
6071
6072 \begin_layout Plain Layout
6073 Document\SpecialChar \menuseparator
6074 Settings
6075 \end_layout
6076
6077 \end_inset
6078
6079 .
6080
6081 \end_layout
6082
6083 \begin_layout Standard
6084 The module declaration should then be followed by lines like the following:
6085 \end_layout
6086
6087 \begin_layout LyX-Code
6088 #DescriptionBegin
6089 \end_layout
6090
6091 \begin_layout LyX-Code
6092 #Adds an endnote command, in addition to footnotes.
6093
6094 \end_layout
6095
6096 \begin_layout LyX-Code
6097 #You will need to add
6098 \backslash
6099 theendnotes in ERT where you
6100 \end_layout
6101
6102 \begin_layout LyX-Code
6103 #want the endnotes to appear.
6104
6105 \end_layout
6106
6107 \begin_layout LyX-Code
6108 #DescriptionEnd
6109 \end_layout
6110
6111 \begin_layout LyX-Code
6112 #Requires: somemodule | othermodule
6113 \end_layout
6114
6115 \begin_layout LyX-Code
6116 #Excludes: badmodule
6117 \end_layout
6118
6119 \begin_layout Standard
6120 The description is used in
6121 \begin_inset Flex CharStyle:MenuItem
6122 status collapsed
6123
6124 \begin_layout Plain Layout
6125 Document\SpecialChar \menuseparator
6126 Settings
6127 \end_layout
6128
6129 \end_inset
6130
6131  to provide the user with information about what the module does.
6132  The
6133 \begin_inset Flex CharStyle:Code
6134 status collapsed
6135
6136 \begin_layout Plain Layout
6137 Requires
6138 \end_layout
6139
6140 \end_inset
6141
6142  line is used to identify other modules with which this one must be used;
6143  the
6144 \begin_inset Flex CharStyle:Code
6145 status collapsed
6146
6147 \begin_layout Plain Layout
6148 Excludes
6149 \end_layout
6150
6151 \end_inset
6152
6153  line is used to identify modules with which this one may not be used.
6154  Both are optional, and, as shown, multiple modules should be separated
6155  with the pipe symbol: |.
6156  Note that the required modules are treated disjunctively:
6157 \emph on
6158 at least one
6159 \emph default
6160  of the required modules must be used.
6161  Similarly,
6162 \emph on
6163 no
6164 \emph default
6165  excluded module may be used.
6166  Note that modules are identified here by their
6167 \emph on
6168 filenames
6169 \emph default
6170  without the .module extension.
6171  So
6172 \begin_inset Flex CharStyle:Code
6173 status collapsed
6174
6175 \begin_layout Plain Layout
6176 somemodule
6177 \end_layout
6178
6179 \end_inset
6180
6181  is really
6182 \begin_inset Flex CharStyle:Code
6183 status collapsed
6184
6185 \begin_layout Plain Layout
6186 somemodule.module
6187 \end_layout
6188
6189 \end_inset
6190
6191 .
6192 \end_layout
6193
6194 \begin_layout Standard
6195 After creating a new module, you will need to reconfigure and then restart
6196  LyX for the module to appear in the menu.
6197  However, changes you make to the module will be seen immediately, if you
6198  open
6199 \begin_inset Flex CharStyle:MenuItem
6200 status collapsed
6201
6202 \begin_layout Plain Layout
6203 Document\SpecialChar \menuseparator
6204 Settings
6205 \end_layout
6206
6207 \end_inset
6208
6209 , highlight something, and then hit
6210 \begin_inset Quotes eld
6211 \end_inset
6212
6213 OK
6214 \begin_inset Quotes erd
6215 \end_inset
6216
6217 .
6218
6219 \emph on
6220 It is strongly recommended that you save your work before doing so
6221 \emph default
6222 .
6223  In fact,
6224 \emph on
6225 it is strongly recommended that you not attempt to edit modules while simultaneo
6226 usly working on documents
6227 \emph default
6228 .
6229  Though of course the developers strive to keep LyX stable in such situations,
6230  syntax errors and the like in your module file could cause strange behavior.
6231 \end_layout
6232
6233 \begin_layout Subsection
6234 Supporting new document classes
6235 \end_layout
6236
6237 \begin_layout Standard
6238 There are two situations you are likely to encounter when wanting to support
6239  a new LaTeX document class, involving LaTeX2e class (
6240 \begin_inset Flex CharStyle:Code
6241 status collapsed
6242
6243 \begin_layout Plain Layout
6244 .cls
6245 \end_layout
6246
6247 \end_inset
6248
6249 ) and style (
6250 \begin_inset Flex CharStyle:Code
6251 status collapsed
6252
6253 \begin_layout Plain Layout
6254 .sty
6255 \end_layout
6256
6257 \end_inset
6258
6259 ) files.
6260  Supporting a style file is usually fairly easy.
6261  Supporting a new document class is a bit harder.
6262 \end_layout
6263
6264 \begin_layout Subsection
6265 A layout for a
6266 \begin_inset Flex CharStyle:MenuItem
6267 status collapsed
6268
6269 \begin_layout Plain Layout
6270 sty
6271 \end_layout
6272
6273 \end_inset
6274
6275  file
6276 \end_layout
6277
6278 \begin_layout Standard
6279 If your new document class is provided as a style file that is used in conjuncti
6280 on with an existing, supported document class---for the sake of the example,
6281  we'll assume that the style file is called
6282 \begin_inset Flex CharStyle:MenuItem
6283 status collapsed
6284
6285 \begin_layout Plain Layout
6286 myclass.sty
6287 \end_layout
6288
6289 \end_inset
6290
6291  and it is meant to be used with
6292 \begin_inset Flex CharStyle:MenuItem
6293 status collapsed
6294
6295 \begin_layout Plain Layout
6296 report.cls
6297 \end_layout
6298
6299 \end_inset
6300
6301 , which is a standard class---start by copying the existing class's layout
6302  file into your local directory:
6303 \end_layout
6304
6305 \begin_layout LyX-Code
6306 cp report.layout ~/.lyx/layouts/myclass.layout
6307 \end_layout
6308
6309 \begin_layout Standard
6310 Then edit
6311 \begin_inset Flex CharStyle:Code
6312 status collapsed
6313
6314 \begin_layout Plain Layout
6315 myclass.layout
6316 \end_layout
6317
6318 \end_inset
6319
6320  and change the line:
6321 \end_layout
6322
6323 \begin_layout LyX-Code
6324
6325 \backslash
6326 DeclareLaTeXClass{report}
6327 \end_layout
6328
6329 \begin_layout Standard
6330 to read
6331 \end_layout
6332
6333 \begin_layout LyX-Code
6334
6335 \backslash
6336 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6337 \end_layout
6338
6339 \begin_layout Standard
6340 Then add:
6341 \end_layout
6342
6343 \begin_layout LyX-Code
6344 Preamble
6345 \begin_inset Newline newline
6346 \end_inset
6347
6348
6349 \backslash
6350 usepackage{myclass}
6351 \begin_inset Newline newline
6352 \end_inset
6353
6354 EndPreamble
6355 \end_layout
6356
6357 \begin_layout Standard
6358 near the top of the file.
6359 \end_layout
6360
6361 \begin_layout Standard
6362 Start LyX and select
6363 \begin_inset Flex CharStyle:MenuItem
6364 status collapsed
6365
6366 \begin_layout Plain Layout
6367
6368 \bar under
6369 T
6370 \bar default
6371 ools\SpecialChar \menuseparator
6372
6373 \bar under
6374 R
6375 \bar default
6376 econfigure
6377 \end_layout
6378
6379 \end_inset
6380
6381 .
6382  Then restart LyX and try creating a new document.
6383  You should see "
6384 \begin_inset Flex CharStyle:MenuItem
6385 status collapsed
6386
6387 \begin_layout Plain Layout
6388 report (myclass)
6389 \end_layout
6390
6391 \end_inset
6392
6393 " as a document class option in the
6394 \begin_inset Flex CharStyle:MenuItem
6395 status collapsed
6396
6397 \begin_layout Plain Layout
6398
6399 \bar under
6400 D
6401 \bar default
6402 ocument\SpecialChar \menuseparator
6403
6404 \bar under
6405 S
6406 \bar default
6407 ettings
6408 \end_layout
6409
6410 \end_inset
6411
6412  dialog.
6413  It is likely that some of the sectioning commands and such in your new
6414  class will work differently from how they worked in the base class---
6415 \begin_inset Flex CharStyle:Code
6416 status collapsed
6417
6418 \begin_layout Plain Layout
6419 report
6420 \end_layout
6421
6422 \end_inset
6423
6424  in this example---so you can fiddle around with the settings for the different
6425  sections if you wish.
6426 \end_layout
6427
6428 \begin_layout Subsection
6429 Layout for a
6430 \begin_inset Flex CharStyle:MenuItem
6431 status collapsed
6432
6433 \begin_layout Plain Layout
6434 cls
6435 \end_layout
6436
6437 \end_inset
6438
6439  file
6440 \end_layout
6441
6442 \begin_layout Standard
6443 There are two possibilities here.
6444  One is that the class file is itself based upon an existing document class.
6445  For example, many thesis classes are based upon
6446 \begin_inset Flex CharStyle:MenuItem
6447 status collapsed
6448
6449 \begin_layout Plain Layout
6450 book.cls
6451 \end_layout
6452
6453 \end_inset
6454
6455 .
6456  To see whether yours is, look for a line like
6457 \end_layout
6458
6459 \begin_layout LyX-Code
6460
6461 \backslash
6462 LoadClass{book}
6463 \end_layout
6464
6465 \begin_layout Standard
6466 in the file.
6467  If so, then you may proceed largely as in the previous section, though
6468  the DeclareLaTeXClass line will be different.
6469  If your new class is thesis, and it is based upon book, then the line should
6470  read:
6471 \begin_inset Foot
6472 status collapsed
6473
6474 \begin_layout Plain Layout
6475 And it will be easiest if you save the file to
6476 \begin_inset Flex CharStyle:Code
6477 status collapsed
6478
6479 \begin_layout Plain Layout
6480 thesis.layout
6481 \end_layout
6482
6483 \end_inset
6484
6485 : LyX assumes that the document class has the same name as the layout file.
6486
6487 \end_layout
6488
6489 \end_inset
6490
6491
6492 \end_layout
6493
6494 \begin_layout LyX-Code
6495
6496 \backslash
6497 DeclareLaTeXClass[thesis,book]{thesis}
6498 \end_layout
6499
6500 \begin_layout Standard
6501 If, on the other hand, the new class is not based upon an existing class,
6502  you will probably have to
6503 \begin_inset Quotes eld
6504 \end_inset
6505
6506 roll your own
6507 \begin_inset Quotes erd
6508 \end_inset
6509
6510  layout.
6511  We strongly suggest copying an existing layout file which uses a similar
6512  LaTeX class and then modifying it, if you can do so.
6513  At least use an existing file as a starting point so you can find out what
6514  items you need to worry about.
6515  Again, the specifics are covered below.
6516 \end_layout
6517
6518 \begin_layout Section
6519 Declaring a new text class
6520 \end_layout
6521
6522 \begin_layout Standard
6523 When it's finally time to get your hands dirty and create or edit your own
6524  layout file, the following sections describe what you're up against.
6525  Our advice is to go slowly, save and test often, listen to soothing music,
6526  and enjoy one or two of your favorite adult beverages; more if you are
6527  getting particularly stuck.
6528  It's really not that hard, except that the multitude of options can become
6529  overwhelming if you try to do to much in one sitting.
6530  Go have another adult beverage, just for good measure.
6531 \end_layout
6532
6533 \begin_layout Standard
6534 Here we go!
6535 \end_layout
6536
6537 \begin_layout Standard
6538 Lines in a layout file which begin with a
6539 \begin_inset Flex CharStyle:Code
6540 status collapsed
6541
6542 \begin_layout Plain Layout
6543 #
6544 \end_layout
6545
6546 \end_inset
6547
6548  are comments.
6549  There is one exception to this rule: all layouts should begin with lines
6550  like:
6551 \end_layout
6552
6553 \begin_layout LyX-Code
6554
6555 \size small
6556 #% Do not delete the line below; configure depends on this
6557 \end_layout
6558
6559 \begin_layout LyX-Code
6560
6561 \size small
6562 #
6563 \backslash
6564 DeclareLaTeXClass{article}
6565 \end_layout
6566
6567 \begin_layout Standard
6568 The second line is used when you configure LyX.
6569  The layout file is read by the LaTeX script
6570 \begin_inset Flex CharStyle:Code
6571 status collapsed
6572
6573 \begin_layout Plain Layout
6574 chkconfig.ltx
6575 \end_layout
6576
6577 \end_inset
6578
6579 , in a special mode where
6580 \begin_inset Flex CharStyle:Code
6581 status collapsed
6582
6583 \begin_layout Plain Layout
6584 #
6585 \end_layout
6586
6587 \end_inset
6588
6589  is ignored.
6590  The first line is just a LaTeX comment, and the second one contains the
6591  declaration of the text class.
6592  If these lines appear in a file named
6593 \begin_inset Flex CharStyle:Code
6594 status collapsed
6595
6596 \begin_layout Plain Layout
6597 article.layout
6598 \end_layout
6599
6600 \end_inset
6601
6602 , then they define a text class of name
6603 \begin_inset Flex CharStyle:Code
6604 status collapsed
6605
6606 \begin_layout Plain Layout
6607 article
6608 \end_layout
6609
6610 \end_inset
6611
6612  (the name of the layout file) which uses the LaTeX document class
6613 \begin_inset Flex CharStyle:Code
6614 status collapsed
6615
6616 \begin_layout Plain Layout
6617 article.cls
6618 \end_layout
6619
6620 \end_inset
6621
6622  (the default is to use the same name as the layout).
6623  The string
6624 \begin_inset Quotes eld
6625 \end_inset
6626
6627 article
6628 \begin_inset Quotes erd
6629 \end_inset
6630
6631  that appears above is used as a description of the text class in the
6632 \begin_inset Flex CharStyle:MenuItem
6633 status collapsed
6634
6635 \begin_layout Plain Layout
6636
6637 \bar under
6638 D
6639 \bar default
6640 ocument\SpecialChar \menuseparator
6641
6642 \bar under
6643 S
6644 \bar default
6645 ettings
6646 \end_layout
6647
6648 \end_inset
6649
6650  dialog.
6651 \end_layout
6652
6653 \begin_layout Standard
6654 Let's assume that you wrote your own text class that uses the
6655 \begin_inset Flex CharStyle:Code
6656 status collapsed
6657
6658 \begin_layout Plain Layout
6659 article.cls
6660 \end_layout
6661
6662 \end_inset
6663
6664  document class, but where you changed the appearance of the section headings.
6665  If you put it in a file
6666 \begin_inset Flex CharStyle:Code
6667 status collapsed
6668
6669 \begin_layout Plain Layout
6670 myarticle.layout
6671 \end_layout
6672
6673 \end_inset
6674
6675 , the header of this file should be:
6676 \end_layout
6677
6678 \begin_layout LyX-Code
6679
6680 \size small
6681 #% Do not delete the line below; configure depends on this
6682 \end_layout
6683
6684 \begin_layout LyX-Code
6685
6686 \size small
6687 #
6688 \backslash
6689 DeclareLaTeXClass[article]{article (with my own headings)}
6690 \end_layout
6691
6692 \begin_layout Standard
6693 This declares a text class
6694 \begin_inset Flex CharStyle:Code
6695 status collapsed
6696
6697 \begin_layout Plain Layout
6698 myarticle
6699 \end_layout
6700
6701 \end_inset
6702
6703 , associated with the LaTeX document class
6704 \begin_inset Flex CharStyle:Code
6705 status collapsed
6706
6707 \begin_layout Plain Layout
6708 article.cls
6709 \end_layout
6710
6711 \end_inset
6712
6713  and described as
6714 \begin_inset Quotes eld
6715 \end_inset
6716
6717 article (with my own headings)
6718 \begin_inset Quotes erd
6719 \end_inset
6720
6721 .
6722  If your text class depends on several packages, you can declare it as:
6723 \end_layout
6724
6725 \begin_layout LyX-Code
6726
6727 \size small
6728 #% Do not delete the line below; configure depends on this
6729 \end_layout
6730
6731 \begin_layout LyX-Code
6732
6733 \size small
6734 #
6735 \backslash
6736 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6737 \end_layout
6738
6739 \begin_layout Standard
6740 This indicates that your text class uses the foo.sty package.
6741  Finally, it is also possible to declare classes for DocBook code.
6742  Typical declarations will look like
6743 \end_layout
6744
6745 \begin_layout LyX-Code
6746
6747 \size small
6748 #% Do not delete the line below; configure depends on this
6749 \end_layout
6750
6751 \begin_layout LyX-Code
6752
6753 \size small
6754 #
6755 \backslash
6756 DeclareDocBookClass[article]{SGML (DocBook article)}
6757 \end_layout
6758
6759 \begin_layout Standard
6760 Note that these declarations can also be given an optional parameter declaring
6761  the name of the document class (but not a list).
6762 \end_layout
6763
6764 \begin_layout Standard
6765 So, to be as explicit as possible, the form of the layout declaration is:
6766 \end_layout
6767
6768 \begin_layout LyX-Code
6769
6770 \size small
6771 #
6772 \backslash
6773 DeclareLaTeXClass[class,package.sty]{layout description}
6774 \end_layout
6775
6776 \begin_layout Standard
6777 The class need only be specified if the name of the LaTeX class file and
6778  the name of the layout file are different; if the name of the classfile
6779  is not specified, then LyX will simply assume that it is the same as the
6780  name of the layout file.
6781 \end_layout
6782
6783 \begin_layout Standard
6784 When the text class has been modified to your taste, all you have to do
6785  is to copy it either to
6786 \begin_inset Flex CharStyle:Code
6787 status collapsed
6788
6789 \begin_layout Plain Layout
6790 LyXDir/layouts/
6791 \end_layout
6792
6793 \end_inset
6794
6795  or to
6796 \begin_inset Flex CharStyle:Code
6797 status collapsed
6798
6799 \begin_layout Plain Layout
6800 UserDir/layouts
6801 \end_layout
6802
6803 \end_inset
6804
6805 , run
6806 \begin_inset Flex CharStyle:MenuItem
6807 status collapsed
6808
6809 \begin_layout Plain Layout
6810
6811 \bar under
6812 T
6813 \bar default
6814 ools\SpecialChar \menuseparator
6815
6816 \bar under
6817 R
6818 \bar default
6819 econfigure
6820 \end_layout
6821
6822 \end_inset
6823
6824 , exit LyX and restart it.
6825  Then your new text class should be available along with the others.
6826 \end_layout
6827
6828 \begin_layout Standard
6829 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6830  you made to your layout files.
6831  As a result, editing layout files could be very time consuming.
6832  Beginning with 1.6, however, you can force a reload of the layout currently
6833  in use by using the LyX function
6834 \begin_inset Flex CharStyle:MenuItem
6835 status collapsed
6836
6837 \begin_layout Plain Layout
6838 layout-reload
6839 \end_layout
6840
6841 \end_inset
6842
6843 .
6844  There is no default binding for this function---though, of course, you
6845  can bind it to a key yourself.
6846  If you want to use this function, then, you should simply enter it in the
6847  mini-buffer.
6848
6849 \emph on
6850 Warning
6851 \emph default
6852 : This is very much an `advanced feature'.
6853  It is
6854 \emph on
6855 strongly
6856 \emph default
6857  recommended that you save your work before using this function.
6858  In fact, it is
6859 \emph on
6860 strongly
6861 \emph default
6862  recommended that you not attempt to edit your layout while simultaneously
6863  working on a document that you care about.
6864  Use a test document.
6865  Syntax errors and the like in your layout file could cause peculiar behavior.
6866  In particular, such errors could cause LyX to regard the current layout
6867  as invalid and to attempt to switch to some other layout.
6868  The LyX team strives to keep LyX stable in such situations, but safe is
6869  better than sorry.
6870 \end_layout
6871
6872 \begin_layout Subsection
6873 File format
6874 \end_layout
6875
6876 \begin_layout Standard
6877 The first non-comment line must contain the file format number:
6878 \end_layout
6879
6880 \begin_layout Description
6881 \begin_inset Flex CharStyle:Code
6882 status collapsed
6883
6884 \begin_layout Plain Layout
6885 Format
6886 \end_layout
6887
6888 \end_inset
6889
6890  [
6891 \begin_inset Flex CharStyle:Code
6892 status collapsed
6893
6894 \begin_layout Plain Layout
6895 int
6896 \end_layout
6897
6898 \end_inset
6899
6900 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6901  don't have an explicit file format).
6902  The file format that is documented here is format 8.
6903 \end_layout
6904
6905 \begin_layout Subsection
6906 General text class parameters
6907 \end_layout
6908
6909 \begin_layout Standard
6910 These are the general parameters which describe the form of the entire document:
6911 \end_layout
6912
6913 \begin_layout Description
6914 \begin_inset Flex CharStyle:Code
6915 status collapsed
6916
6917 \begin_layout Plain Layout
6918 AddToPreamble
6919 \end_layout
6920
6921 \end_inset
6922
6923  Adds information to the document preamble.
6924  Must end with
6925 \begin_inset Quotes eld
6926 \end_inset
6927
6928
6929 \begin_inset Flex CharStyle:Code
6930 status collapsed
6931
6932 \begin_layout Plain Layout
6933 EndPreamble
6934 \end_layout
6935
6936 \end_inset
6937
6938
6939 \begin_inset Quotes erd
6940 \end_inset
6941
6942 .
6943 \end_layout
6944
6945 \begin_layout Description
6946 \begin_inset Flex CharStyle:Code
6947 status collapsed
6948
6949 \begin_layout Plain Layout
6950 ClassOptions
6951 \end_layout
6952
6953 \end_inset
6954
6955  Describes various global options supported by the document class.
6956  See Section
6957 \begin_inset space ~
6958 \end_inset
6959
6960
6961 \begin_inset CommandInset ref
6962 LatexCommand ref
6963 reference "sec:classoptions"
6964
6965 \end_inset
6966
6967  for a description.
6968  Must end with
6969 \begin_inset Quotes eld
6970 \end_inset
6971
6972
6973 \begin_inset Flex CharStyle:Code
6974 status collapsed
6975
6976 \begin_layout Plain Layout
6977 End
6978 \end_layout
6979
6980 \end_inset
6981
6982
6983 \begin_inset Quotes erd
6984 \end_inset
6985
6986 .
6987 \end_layout
6988
6989 \begin_layout Description
6990 \begin_inset Flex CharStyle:Code
6991 status collapsed
6992
6993 \begin_layout Plain Layout
6994 Columns
6995 \end_layout
6996
6997 \end_inset
6998
6999  [
7000 \begin_inset Flex CharStyle:Code
7001 status collapsed
7002
7003 \begin_layout Plain Layout
7004
7005 \emph on
7006 1
7007 \end_layout
7008
7009 \end_inset
7010
7011 ,
7012 \begin_inset Flex CharStyle:Code
7013 status collapsed
7014
7015 \begin_layout Plain Layout
7016 2
7017 \end_layout
7018
7019 \end_inset
7020
7021 ] Whether the class should default to having one or two columns.
7022  Can be changed in the
7023 \begin_inset Flex CharStyle:MenuItem
7024 status collapsed
7025
7026 \begin_layout Plain Layout
7027
7028 \bar under
7029 D
7030 \bar default
7031 ocument\SpecialChar \menuseparator
7032
7033 \bar under
7034 S
7035 \bar default
7036 ettings
7037 \end_layout
7038
7039 \end_inset
7040
7041  dialog.
7042 \end_layout
7043
7044 \begin_layout Description
7045 \begin_inset Flex CharStyle:Code
7046 status collapsed
7047
7048 \begin_layout Plain Layout
7049 Counter
7050 \end_layout
7051
7052 \end_inset
7053
7054  This sequence defines a new counter.
7055  See Section
7056 \begin_inset space ~
7057 \end_inset
7058
7059
7060 \begin_inset CommandInset ref
7061 LatexCommand ref
7062 reference "sec:counter"
7063
7064 \end_inset
7065
7066  for details.
7067  Must end with
7068 \begin_inset Quotes eld
7069 \end_inset
7070
7071
7072 \begin_inset Flex CharStyle:Code
7073 status collapsed
7074
7075 \begin_layout Plain Layout
7076 End
7077 \end_layout
7078
7079 \end_inset
7080
7081
7082 \begin_inset Quotes erd
7083 \end_inset
7084
7085 .
7086 \end_layout
7087
7088 \begin_layout Description
7089 \begin_inset Flex CharStyle:Code
7090 status collapsed
7091
7092 \begin_layout Plain Layout
7093 DefaultFont
7094 \end_layout
7095
7096 \end_inset
7097
7098  Sets the default font used to display the document.
7099  See Section
7100 \begin_inset space ~
7101 \end_inset
7102
7103
7104 \begin_inset CommandInset ref
7105 LatexCommand ref
7106 reference "sec:fonts"
7107
7108 \end_inset
7109
7110  for how to declare fonts.
7111  Must end with
7112 \begin_inset Quotes eld
7113 \end_inset
7114
7115
7116 \begin_inset Flex CharStyle:Code
7117 status collapsed
7118
7119 \begin_layout Plain Layout
7120 EndFont
7121 \end_layout
7122
7123 \end_inset
7124
7125
7126 \begin_inset Quotes erd
7127 \end_inset
7128
7129 .
7130 \end_layout
7131
7132 \begin_layout Description
7133 \begin_inset Flex CharStyle:Code
7134 status collapsed
7135
7136 \begin_layout Plain Layout
7137 DefaultStyle
7138 \end_layout
7139
7140 \end_inset
7141
7142  [
7143 \begin_inset Flex CharStyle:Code
7144 status collapsed
7145
7146 \begin_layout Plain Layout
7147 string
7148 \end_layout
7149
7150 \end_inset
7151
7152 ] This is the style that will be assigned to new paragraphs, usually
7153 \begin_inset Flex CharStyle:MenuItem
7154 status collapsed
7155
7156 \begin_layout Plain Layout
7157 Standard
7158 \end_layout
7159
7160 \end_inset
7161
7162 .
7163  This will default to the first defined style if not given, but you are
7164  highly encouraged to use this directive.
7165 \end_layout
7166
7167 \begin_layout Description
7168 \begin_inset Flex CharStyle:Code
7169 status collapsed
7170
7171 \begin_layout Plain Layout
7172 Float
7173 \end_layout
7174
7175 \end_inset
7176
7177  Defines a new float.
7178  See Section
7179 \begin_inset space ~
7180 \end_inset
7181
7182
7183 \begin_inset CommandInset ref
7184 LatexCommand ref
7185 reference "sec:floats"
7186
7187 \end_inset
7188
7189  for details.
7190  Must end with
7191 \begin_inset Quotes eld
7192 \end_inset
7193
7194
7195 \begin_inset Flex CharStyle:Code
7196 status collapsed
7197
7198 \begin_layout Plain Layout
7199 End
7200 \end_layout
7201
7202 \end_inset
7203
7204
7205 \begin_inset Quotes erd
7206 \end_inset
7207
7208 .
7209 \end_layout
7210
7211 \begin_layout Description
7212 \begin_inset Flex CharStyle:Code
7213 status collapsed
7214
7215 \begin_layout Plain Layout
7216 Input
7217 \end_layout
7218
7219 \end_inset
7220
7221  As its name implies, this command allows you to include another layout
7222  definition file within yours to avoid duplicating commands.
7223  Common examples are the standard layout files, for example,
7224 \begin_inset Flex CharStyle:Code
7225 status collapsed
7226
7227 \begin_layout Plain Layout
7228 stdclass.inc
7229 \end_layout
7230
7231 \end_inset
7232
7233 , which contains most of the basic layouts.
7234 \end_layout
7235
7236 \begin_layout Description
7237 \begin_inset Flex CharStyle:Code
7238 status collapsed
7239
7240 \begin_layout Plain Layout
7241 InsetLayout
7242 \end_layout
7243
7244 \end_inset
7245
7246  This section (re-)defines the layout of an inset.
7247  It can be applied to an existing inset of to a new, user-defined inset,
7248  e.g., a new character style.
7249  See Section
7250 \begin_inset space ~
7251 \end_inset
7252
7253
7254 \begin_inset CommandInset ref
7255 LatexCommand ref
7256 reference "sec:charstyle"
7257
7258 \end_inset
7259
7260  for more information.
7261  Must end with
7262 \begin_inset Quotes eld
7263 \end_inset
7264
7265
7266 \begin_inset Flex CharStyle:Code
7267 status collapsed
7268
7269 \begin_layout Plain Layout
7270 End
7271 \end_layout
7272
7273 \end_inset
7274
7275
7276 \begin_inset Quotes erd
7277 \end_inset
7278
7279 .
7280 \end_layout
7281
7282 \begin_layout Description
7283 \begin_inset Flex CharStyle:Code
7284 status collapsed
7285
7286 \begin_layout Plain Layout
7287 LeftMargin
7288 \end_layout
7289
7290 \end_inset
7291
7292  [[FIXME]]
7293 \end_layout
7294
7295 \begin_layout Description
7296 \begin_inset Flex CharStyle:Code
7297 status collapsed
7298
7299 \begin_layout Plain Layout
7300 NoFloat
7301 \end_layout
7302
7303 \end_inset
7304
7305  This command deletes an existing float.
7306  This is particularly useful when you want to suppress a float that has
7307  be defined in an input file.
7308 \end_layout
7309
7310 \begin_layout Description
7311 \begin_inset Flex CharStyle:Code
7312 status collapsed
7313
7314 \begin_layout Plain Layout
7315 NoStyle
7316 \end_layout
7317
7318 \end_inset
7319
7320  This command deletes an existing style.
7321  This is particularly useful when you want to suppress a style that has
7322  be defined in an input file.
7323 \end_layout
7324
7325 \begin_layout Description
7326 \begin_inset Flex CharStyle:Code
7327 status collapsed
7328
7329 \begin_layout Plain Layout
7330 OutputType
7331 \end_layout
7332
7333 \end_inset
7334
7335  [[FIXME]]
7336 \end_layout
7337
7338 \begin_layout Description
7339 \begin_inset Flex CharStyle:Code
7340 status collapsed
7341
7342 \begin_layout Plain Layout
7343
7344 \series medium
7345 PageStyle
7346 \end_layout
7347
7348 \end_inset
7349
7350  [
7351 \emph on
7352
7353 \begin_inset Flex CharStyle:Code
7354 status collapsed
7355
7356 \begin_layout Plain Layout
7357
7358 \emph on
7359 plain
7360 \end_layout
7361
7362 \end_inset
7363
7364
7365 \emph default
7366 ,
7367 \begin_inset Flex CharStyle:Code
7368 status collapsed
7369
7370 \begin_layout Plain Layout
7371 empty
7372 \end_layout
7373
7374 \end_inset
7375
7376 ,
7377 \begin_inset Flex CharStyle:Code
7378 status collapsed
7379
7380 \begin_layout Plain Layout
7381 headings
7382 \end_layout
7383
7384 \end_inset
7385
7386 ] The class default pagestyle.
7387  Can be changed in the
7388 \begin_inset Flex CharStyle:MenuItem
7389 status collapsed
7390
7391 \begin_layout Plain Layout
7392
7393 \bar under
7394 D
7395 \bar default
7396 ocument\SpecialChar \menuseparator
7397
7398 \bar under
7399 S
7400 \bar default
7401 ettings
7402 \end_layout
7403
7404 \end_inset
7405
7406  dialog.
7407 \end_layout
7408
7409 \begin_layout Description
7410 \begin_inset Flex CharStyle:Code
7411 status collapsed
7412
7413 \begin_layout Plain Layout
7414 Preamble
7415 \end_layout
7416
7417 \end_inset
7418
7419  Sets the preamble for the LaTeX document.
7420  Note that this will completely override any prior
7421 \begin_inset Flex CharStyle:Code
7422 status collapsed
7423
7424 \begin_layout Plain Layout
7425 Premable
7426 \end_layout
7427
7428 \end_inset
7429
7430  or
7431 \begin_inset Flex CharStyle:Code
7432 status collapsed
7433
7434 \begin_layout Plain Layout
7435 AddToPreamble
7436 \end_layout
7437
7438 \end_inset
7439
7440  declarations.
7441  Must end with
7442 \begin_inset Quotes eld
7443 \end_inset
7444
7445
7446 \begin_inset Flex CharStyle:Code
7447 status collapsed
7448
7449 \begin_layout Plain Layout
7450 EndPreamble
7451 \end_layout
7452
7453 \end_inset
7454
7455
7456 \begin_inset Quotes erd
7457 \end_inset
7458
7459 .
7460 \end_layout
7461
7462 \begin_layout Description
7463 \begin_inset Flex CharStyle:Code
7464 status collapsed
7465
7466 \begin_layout Plain Layout
7467 Provides
7468 \end_layout
7469
7470 \end_inset
7471
7472  [
7473 \begin_inset Flex CharStyle:Code
7474 status collapsed
7475
7476 \begin_layout Plain Layout
7477 string
7478 \end_layout
7479
7480 \end_inset
7481
7482 ] [
7483 \begin_inset Flex CharStyle:Code
7484 status collapsed
7485
7486 \begin_layout Plain Layout
7487
7488 \emph on
7489 0
7490 \end_layout
7491
7492 \end_inset
7493
7494 ,
7495 \begin_inset Flex CharStyle:Code
7496 status collapsed
7497
7498 \begin_layout Plain Layout
7499 1
7500 \end_layout
7501
7502 \end_inset
7503
7504 ] Whether the class already provides the feature
7505 \begin_inset Flex CharStyle:Code
7506 status collapsed
7507
7508 \begin_layout Plain Layout
7509 string
7510 \end_layout
7511
7512 \end_inset
7513
7514 .
7515  A feature is in general the name of a package (
7516 \begin_inset Flex CharStyle:Code
7517 status collapsed
7518
7519 \begin_layout Plain Layout
7520 amsmath
7521 \end_layout
7522
7523 \end_inset
7524
7525 ,
7526 \begin_inset Flex CharStyle:Code
7527 status collapsed
7528
7529 \begin_layout Plain Layout
7530 makeidx
7531 \end_layout
7532
7533 \end_inset
7534
7535 , \SpecialChar \ldots{}
7536 ) or a macro (
7537 \begin_inset Flex CharStyle:Code
7538 status collapsed
7539
7540 \begin_layout Plain Layout
7541 url
7542 \end_layout
7543
7544 \end_inset
7545
7546 ,
7547 \begin_inset Flex CharStyle:Code
7548 status collapsed
7549
7550 \begin_layout Plain Layout
7551 boldsymbol
7552 \end_layout
7553
7554 \end_inset
7555
7556 ,\SpecialChar \ldots{}
7557 ); the complete list of supported features is unfortunately not documented
7558  outside the LyX source code---but see
7559 \begin_inset Flex CharStyle:Code
7560 status collapsed
7561
7562 \begin_layout Plain Layout
7563 LaTeXFeatures.cpp
7564 \end_layout
7565
7566 \end_inset
7567
7568  if you're interested.
7569
7570 \begin_inset Flex CharStyle:MenuItem
7571 status collapsed
7572
7573 \begin_layout Plain Layout
7574
7575 \bar under
7576 H
7577 \bar default
7578 elp\SpecialChar \menuseparator
7579
7580 \bar under
7581 L
7582 \bar default
7583 aTeX Configuration
7584 \end_layout
7585
7586 \end_inset
7587
7588  also gives an overview of the supported packages.
7589 \end_layout
7590
7591 \begin_layout Description
7592 \begin_inset Flex CharStyle:Code
7593 status collapsed
7594
7595 \begin_layout Plain Layout
7596 Requires
7597 \end_layout
7598
7599 \end_inset
7600
7601  [
7602 \begin_inset Flex CharStyle:Code
7603 status collapsed
7604
7605 \begin_layout Plain Layout
7606 string
7607 \end_layout
7608
7609 \end_inset
7610
7611 ] Whether the class requires the feature
7612 \begin_inset Flex CharStyle:Code
7613 status collapsed
7614
7615 \begin_layout Plain Layout
7616  string
7617 \end_layout
7618
7619 \end_inset
7620
7621 .
7622  Multiple features must be separated by commas.
7623  Note that you can only request supported features.
7624 \end_layout
7625
7626 \begin_layout Description
7627 \begin_inset Flex CharStyle:Code
7628 status collapsed
7629
7630 \begin_layout Plain Layout
7631 RightMargin
7632 \end_layout
7633
7634 \end_inset
7635
7636  [[FIXME]]
7637 \end_layout
7638
7639 \begin_layout Description
7640 \begin_inset Flex CharStyle:Code
7641 status collapsed
7642
7643 \begin_layout Plain Layout
7644 SecNumDepth
7645 \end_layout
7646
7647 \end_inset
7648
7649  [[FIXME]]
7650 \end_layout
7651
7652 \begin_layout Description
7653 \begin_inset Flex CharStyle:Code
7654 status collapsed
7655
7656 \begin_layout Plain Layout
7657 Sides
7658 \end_layout
7659
7660 \end_inset
7661
7662  [
7663 \emph on
7664
7665 \begin_inset Flex CharStyle:Code
7666 status collapsed
7667
7668 \begin_layout Plain Layout
7669
7670 \emph on
7671 1
7672 \end_layout
7673
7674 \end_inset
7675
7676
7677 \emph default
7678 ,
7679 \begin_inset Flex CharStyle:Code
7680 status collapsed
7681
7682 \begin_layout Plain Layout
7683 2
7684 \end_layout
7685
7686 \end_inset
7687
7688 ] Whether the class-default should be printing on one or both sides of the
7689  paper.
7690  Can be changed in the
7691 \begin_inset Flex CharStyle:MenuItem
7692 status collapsed
7693
7694 \begin_layout Plain Layout
7695
7696 \bar under
7697 D
7698 \bar default
7699 ocument\SpecialChar \menuseparator
7700
7701 \bar under
7702 S
7703 \bar default
7704 ettings
7705 \end_layout
7706
7707 \end_inset
7708
7709  dialog.
7710 \end_layout
7711
7712 \begin_layout Description
7713 \begin_inset Flex CharStyle:Code
7714 status collapsed
7715
7716 \begin_layout Plain Layout
7717 Style
7718 \end_layout
7719
7720 \end_inset
7721
7722  This sequence defines a new paragraph style.
7723  If the style already exists, it will redefine some of its parameters instead.
7724  See Section
7725 \begin_inset space ~
7726 \end_inset
7727
7728
7729 \begin_inset CommandInset ref
7730 LatexCommand ref
7731 reference "sec:style"
7732
7733 \end_inset
7734
7735  for details.
7736  Must end with
7737 \begin_inset Quotes eld
7738 \end_inset
7739
7740
7741 \begin_inset Flex CharStyle:Code
7742 status collapsed
7743
7744 \begin_layout Plain Layout
7745 End
7746 \end_layout
7747
7748 \end_inset
7749
7750
7751 \begin_inset Quotes erd
7752 \end_inset
7753
7754 .
7755 \end_layout
7756
7757 \begin_layout Description
7758 \begin_inset Flex CharStyle:Code
7759 status collapsed
7760
7761 \begin_layout Plain Layout
7762 TitleLatexName
7763 \end_layout
7764
7765 \end_inset
7766
7767  [
7768 \begin_inset Flex CharStyle:Code
7769 status collapsed
7770
7771 \begin_layout Plain Layout
7772 string="maketitle"
7773 \end_layout
7774
7775 \end_inset
7776
7777 ] The name of the command or environment to be used with
7778 \begin_inset Flex CharStyle:Code
7779 status collapsed
7780
7781 \begin_layout Plain Layout
7782 TitleLatexType
7783 \end_layout
7784
7785 \end_inset
7786
7787 .
7788 \end_layout
7789
7790 \begin_layout Description
7791 \begin_inset Flex CharStyle:Code
7792 status collapsed
7793
7794 \begin_layout Plain Layout
7795 TitleLatexType
7796 \end_layout
7797
7798 \end_inset
7799
7800  [
7801 \begin_inset Flex CharStyle:Code
7802 status collapsed
7803
7804 \begin_layout Plain Layout
7805
7806 \emph on
7807 CommandAfter
7808 \end_layout
7809
7810 \end_inset
7811
7812 ,
7813 \begin_inset Flex CharStyle:Code
7814 status collapsed
7815
7816 \begin_layout Plain Layout
7817 Environment
7818 \end_layout
7819
7820 \end_inset
7821
7822 ] Indicates what kind of markup is used to define the title of a document.
7823
7824 \begin_inset Flex CharStyle:Code
7825 status collapsed
7826
7827 \begin_layout Plain Layout
7828 CommandAfter
7829 \end_layout
7830
7831 \end_inset
7832
7833  means that the macro with name
7834 \begin_inset Flex CharStyle:Code
7835 status collapsed
7836
7837 \begin_layout Plain Layout
7838 TitleLatexName
7839 \end_layout
7840
7841 \end_inset
7842
7843  will be inserted after the last layout which has
7844 \begin_inset Quotes eld
7845 \end_inset
7846
7847
7848 \begin_inset Flex CharStyle:Code
7849 status collapsed
7850
7851 \begin_layout Plain Layout
7852 InTitle 1
7853 \end_layout
7854
7855 \end_inset
7856
7857
7858 \begin_inset Quotes erd
7859 \end_inset
7860
7861 .
7862
7863 \begin_inset Flex CharStyle:Code
7864 status collapsed
7865
7866 \begin_layout Plain Layout
7867 Environment
7868 \end_layout
7869
7870 \end_inset
7871
7872  corresponds to the case where the block of paragraphs which have
7873 \begin_inset Quotes eld
7874 \end_inset
7875
7876
7877 \begin_inset Flex CharStyle:Code
7878 status collapsed
7879
7880 \begin_layout Plain Layout
7881 InTitle 1
7882 \end_layout
7883
7884 \end_inset
7885
7886
7887 \begin_inset Quotes erd
7888 \end_inset
7889
7890  should be enclosed into the
7891 \begin_inset Flex CharStyle:Code
7892 status collapsed
7893
7894 \begin_layout Plain Layout
7895 TitleLatexName
7896 \end_layout
7897
7898 \end_inset
7899
7900  environment.
7901 \end_layout
7902
7903 \begin_layout Description
7904 \begin_inset Flex CharStyle:Code
7905 status open
7906
7907 \begin_layout Plain Layout
7908 TocDepth
7909 \end_layout
7910
7911 \end_inset
7912
7913  [[FIXME]]
7914 \end_layout
7915
7916 \begin_layout Description
7917 \begin_inset Flex CharStyle:Code
7918 status collapsed
7919
7920 \begin_layout Plain Layout
7921 UseModule
7922 \end_layout
7923
7924 \end_inset
7925
7926  [
7927 \begin_inset Flex CharStyle:Code
7928 status collapsed
7929
7930 \begin_layout Plain Layout
7931 string]
7932 \end_layout
7933
7934 \end_inset
7935
7936  Specifies a module to be included by default with this document class.
7937  The user can still remove the module, but it will be active at the outset.
7938  (This applies only when new files are created, or when this class is chosen
7939  for an existing document.)
7940 \end_layout
7941
7942 \begin_layout Subsection
7943 \begin_inset Flex CharStyle:Code
7944 status collapsed
7945
7946 \begin_layout Plain Layout
7947 ClassOptions
7948 \end_layout
7949
7950 \end_inset
7951
7952  section
7953 \end_layout
7954
7955 \begin_layout Standard
7956 \begin_inset CommandInset label
7957 LatexCommand label
7958 name "sec:classoptions"
7959
7960 \end_inset
7961
7962 The
7963 \begin_inset Flex CharStyle:Code
7964 status collapsed
7965
7966 \begin_layout Plain Layout
7967 ClassOptions
7968 \end_layout
7969
7970 \end_inset
7971
7972  section can contain the following entries:
7973 \end_layout
7974
7975 \begin_layout Description
7976 \begin_inset Flex CharStyle:Code
7977 status collapsed
7978
7979 \begin_layout Plain Layout
7980 FontSize
7981 \end_layout
7982
7983 \end_inset
7984
7985  [
7986 \begin_inset Flex CharStyle:Code
7987 status collapsed
7988
7989 \begin_layout Plain Layout
7990 string="10|11|12"
7991 \end_layout
7992
7993 \end_inset
7994
7995 ] The list of available font sizes for the document's main font, separated
7996  by
7997 \begin_inset Quotes eld
7998 \end_inset
7999
8000
8001 \begin_inset Flex CharStyle:Code
8002 status collapsed
8003
8004 \begin_layout Plain Layout
8005 |
8006 \end_layout
8007
8008 \end_inset
8009
8010
8011 \begin_inset Quotes erd
8012 \end_inset
8013
8014 .
8015 \end_layout
8016
8017 \begin_layout Description
8018 \begin_inset Flex CharStyle:Code
8019 status collapsed
8020
8021 \begin_layout Plain Layout
8022 Header
8023 \end_layout
8024
8025 \end_inset
8026
8027  [[FIXME]]
8028 \end_layout
8029
8030 \begin_layout Description
8031 \begin_inset Flex CharStyle:Code
8032 status collapsed
8033
8034 \begin_layout Plain Layout
8035 PageStyle
8036 \end_layout
8037
8038 \end_inset
8039
8040  [
8041 \begin_inset Flex CharStyle:Code
8042 status collapsed
8043
8044 \begin_layout Plain Layout
8045 string="empty|plain|headings|fancy"
8046 \end_layout
8047
8048 \end_inset
8049
8050 ] The list of available page styles, separated by
8051 \begin_inset Quotes eld
8052 \end_inset
8053
8054
8055 \begin_inset Flex CharStyle:Code
8056 status collapsed
8057
8058 \begin_layout Plain Layout
8059 |
8060 \end_layout
8061
8062 \end_inset
8063
8064
8065 \begin_inset Quotes erd
8066 \end_inset
8067
8068 .
8069 \end_layout
8070
8071 \begin_layout Description
8072 \begin_inset Flex CharStyle:Code
8073 status collapsed
8074
8075 \begin_layout Plain Layout
8076 Other
8077 \end_layout
8078
8079 \end_inset
8080
8081  [
8082 \begin_inset Flex CharStyle:Code
8083 status collapsed
8084
8085 \begin_layout Plain Layout
8086 string=""
8087 \end_layout
8088
8089 \end_inset
8090
8091 ] Some document class options, separated by a comma, that will be added
8092  to the optional part of the
8093 \begin_inset Flex CharStyle:Code
8094 status collapsed
8095
8096 \begin_layout Plain Layout
8097
8098 \backslash
8099 documentclass
8100 \end_layout
8101
8102 \end_inset
8103
8104  command.
8105 \end_layout
8106
8107 \begin_layout Standard
8108 The
8109 \begin_inset Flex CharStyle:Code
8110 status collapsed
8111
8112 \begin_layout Plain Layout
8113 ClassOptions
8114 \end_layout
8115
8116 \end_inset
8117
8118  section must end with
8119 \begin_inset Quotes eld
8120 \end_inset
8121
8122
8123 \begin_inset Flex CharStyle:Code
8124 status collapsed
8125
8126 \begin_layout Plain Layout
8127 End
8128 \end_layout
8129
8130 \end_inset
8131
8132
8133 \begin_inset Quotes erd
8134 \end_inset
8135
8136 .
8137 \end_layout
8138
8139 \begin_layout Subsection
8140 Paragraph Styles
8141 \end_layout
8142
8143 \begin_layout Standard
8144 \begin_inset CommandInset label
8145 LatexCommand label
8146 name "sec:style"
8147
8148 \end_inset
8149
8150 A paragraph style description looks like this:
8151 \begin_inset Foot
8152 status collapsed
8153
8154 \begin_layout Plain Layout
8155 Note that this will either define a new layout or modify an existing one.
8156 \end_layout
8157
8158 \end_inset
8159
8160
8161 \end_layout
8162
8163 \begin_layout LyX-Code
8164 Style
8165 \family roman
8166 \emph on
8167 name
8168 \end_layout
8169
8170 \begin_layout LyX-Code
8171  ...
8172 \end_layout
8173
8174 \begin_layout LyX-Code
8175 End
8176 \end_layout
8177
8178 \begin_layout Standard
8179 where the following commands are allowed:
8180 \end_layout
8181
8182 \begin_layout Description
8183 \begin_inset Flex CharStyle:Code
8184 status collapsed
8185
8186 \begin_layout Plain Layout
8187 Align
8188 \end_layout
8189
8190 \end_inset
8191
8192  [
8193 \begin_inset Flex CharStyle:Code
8194 status collapsed
8195
8196 \begin_layout Plain Layout
8197
8198 \emph on
8199 block
8200 \emph default
8201 , left, right, center
8202 \end_layout
8203
8204 \end_inset
8205
8206 ] Paragraph alignment.
8207 \end_layout
8208
8209 \begin_layout Description
8210 \begin_inset Flex CharStyle:Code
8211 status collapsed
8212
8213 \begin_layout Plain Layout
8214 AlignPossible
8215 \end_layout
8216
8217 \end_inset
8218
8219  [
8220 \begin_inset Flex CharStyle:Code
8221 status collapsed
8222
8223 \begin_layout Plain Layout
8224
8225 \emph on
8226 block
8227 \emph default
8228 , left, right, center
8229 \end_layout
8230
8231 \end_inset
8232
8233 ] A comma separated list of permitted alignments.
8234  (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8235  sense.
8236  For example a right-aligned or centered enumeration isn't possible.)
8237 \end_layout
8238
8239 \begin_layout Description
8240 \begin_inset Flex CharStyle:Code
8241 status collapsed
8242
8243 \begin_layout Plain Layout
8244 BottomSep
8245 \end_layout
8246
8247 \end_inset
8248
8249  [
8250 \begin_inset Flex CharStyle:Code
8251 status collapsed
8252
8253 \begin_layout Plain Layout
8254 float=0
8255 \end_layout
8256
8257 \end_inset
8258
8259 ]
8260 \begin_inset Foot
8261 status collapsed
8262
8263 \begin_layout Plain Layout
8264 Note that a `float' here is a real number, such as: 1.5.
8265 \end_layout
8266
8267 \end_inset
8268
8269  The vertical space with which the last of a chain of paragraphs with this
8270  layout is separated from the following paragraph.
8271  If the next paragraph has another layout, the separations are not simply
8272  added, but the maximum is taken.
8273 \end_layout
8274
8275 \begin_layout Description
8276 \begin_inset Flex CharStyle:Code
8277 status collapsed
8278
8279 \begin_layout Plain Layout
8280 Category
8281 \end_layout
8282
8283 \end_inset
8284
8285
8286 \begin_inset Flex CharStyle:Code
8287 status collapsed
8288
8289 \begin_layout Plain Layout
8290 [string]
8291 \end_layout
8292
8293 \end_inset
8294
8295  The category for this style.
8296  This is used to group related styles in the Layout combobox on the toolbar.
8297  Any string can be used, but you may want to use existing categories with
8298  your own styles.
8299
8300 \end_layout
8301
8302 \begin_layout Description
8303 \begin_inset Flex CharStyle:Code
8304 status collapsed
8305
8306 \begin_layout Plain Layout
8307 CommandDepth
8308 \end_layout
8309
8310 \end_inset
8311
8312  [[FIXME]]
8313 \end_layout
8314
8315 \begin_layout Description
8316 \begin_inset Flex CharStyle:Code
8317 status collapsed
8318
8319 \begin_layout Plain Layout
8320 CopyStyle
8321 \end_layout
8322
8323 \end_inset
8324
8325
8326 \begin_inset CommandInset label
8327 LatexCommand label
8328 name "des:CopyStyle"
8329
8330 \end_inset
8331
8332
8333 \begin_inset Flex CharStyle:Code
8334 status collapsed
8335
8336 \begin_layout Plain Layout
8337 [string]
8338 \end_layout
8339
8340 \end_inset
8341
8342  Copies all the features of an existing style into the current one.
8343
8344 \end_layout
8345
8346 \begin_layout Description
8347 \begin_inset Flex CharStyle:Code
8348 status collapsed
8349
8350 \begin_layout Plain Layout
8351 DependsOn
8352 \end_layout
8353
8354 \end_inset
8355
8356  The name of a style whose preamble should be output
8357 \emph on
8358 before
8359 \emph default
8360  this one.
8361  This allows to ensure some ordering of the preamble snippets when macros
8362  definitions depend on one another.
8363 \begin_inset Foot
8364 status collapsed
8365
8366 \begin_layout Plain Layout
8367 Note that, besides that functionality, there is no way to ensure any ordering
8368  of preambles.
8369  The ordering that you see in a given version of LyX may change without
8370  warning in later versions.
8371 \end_layout
8372
8373 \end_inset
8374
8375
8376 \end_layout
8377
8378 \begin_layout Description
8379 \begin_inset Flex CharStyle:Code
8380 status collapsed
8381
8382 \begin_layout Plain Layout
8383 EndLabeltype
8384 \end_layout
8385
8386 \end_inset
8387
8388  [
8389 \begin_inset Flex CharStyle:Code
8390 status collapsed
8391
8392 \begin_layout Plain Layout
8393
8394 \emph on
8395 No_Label
8396 \emph default
8397 , Box, Filled_Box, Static
8398 \end_layout
8399
8400 \end_inset
8401
8402 ] The type of label that stands at the end of the paragraph (or sequence
8403  of paragraphs if
8404 \begin_inset Flex CharStyle:Code
8405 status collapsed
8406
8407 \begin_layout Plain Layout
8408 LatexType
8409 \end_layout
8410
8411 \end_inset
8412
8413  is
8414 \begin_inset Flex CharStyle:Code
8415 status collapsed
8416
8417 \begin_layout Plain Layout
8418 Environment
8419 \end_layout
8420
8421 \end_inset
8422
8423 ,
8424 \begin_inset Flex CharStyle:Code
8425 status collapsed
8426
8427 \begin_layout Plain Layout
8428 Item_Environment
8429 \end_layout
8430
8431 \end_inset
8432
8433  or
8434 \begin_inset Flex CharStyle:Code
8435 status collapsed
8436
8437 \begin_layout Plain Layout
8438 List_Environment
8439 \end_layout
8440
8441 \end_inset
8442
8443 ).
8444
8445 \begin_inset Flex CharStyle:Code
8446 status collapsed
8447
8448 \begin_layout Plain Layout
8449 No_Label
8450 \end_layout
8451
8452 \end_inset
8453
8454  means
8455 \begin_inset Quotes eld
8456 \end_inset
8457
8458 nothing
8459 \begin_inset Quotes erd
8460 \end_inset
8461
8462 ,
8463 \begin_inset Flex CharStyle:Code
8464 status collapsed
8465
8466 \begin_layout Plain Layout
8467 Box
8468 \end_layout
8469
8470 \end_inset
8471
8472  (resp.
8473 \begin_inset Flex CharStyle:Code
8474 status collapsed
8475
8476 \begin_layout Plain Layout
8477 \begin_inset space ~
8478 \end_inset
8479
8480 Filled_Box
8481 \end_layout
8482
8483 \end_inset
8484
8485 ) is a white (resp.
8486 \begin_inset space ~
8487 \end_inset
8488
8489 black) square suitable for end of proof markers,
8490 \begin_inset Flex CharStyle:Code
8491 status collapsed
8492
8493 \begin_layout Plain Layout
8494 Static
8495 \end_layout
8496
8497 \end_inset
8498
8499  is an explicit text string.
8500 \end_layout
8501
8502 \begin_layout Description
8503 \begin_inset Flex CharStyle:Code
8504 status collapsed
8505
8506 \begin_layout Plain Layout
8507 EndLabelString
8508 \end_layout
8509
8510 \end_inset
8511
8512  [
8513 \begin_inset Flex CharStyle:Code
8514 status collapsed
8515
8516 \begin_layout Plain Layout
8517 string=""
8518 \end_layout
8519
8520 \end_inset
8521
8522 ] The string used for a label with a
8523 \begin_inset Flex CharStyle:Code
8524 status collapsed
8525
8526 \begin_layout Plain Layout
8527 Static
8528 \end_layout
8529
8530 \end_inset
8531
8532
8533 \begin_inset Flex CharStyle:Code
8534 status collapsed
8535
8536 \begin_layout Plain Layout
8537 EndLabelType
8538 \end_layout
8539
8540 \end_inset
8541
8542 .
8543
8544 \end_layout
8545
8546 \begin_layout Description
8547 \begin_inset Flex CharStyle:Code
8548 status collapsed
8549
8550 \begin_layout Plain Layout
8551 Fill_Bottom
8552 \end_layout
8553
8554 \end_inset
8555
8556  [
8557 \begin_inset Flex CharStyle:Code
8558 status collapsed
8559
8560 \begin_layout Plain Layout
8561
8562 \emph on
8563 0
8564 \emph default
8565 ,1
8566 \end_layout
8567
8568 \end_inset
8569
8570 ] Similar to
8571 \begin_inset Flex CharStyle:Code
8572 status collapsed
8573
8574 \begin_layout Plain Layout
8575 Fill_Top
8576 \end_layout
8577
8578 \end_inset
8579
8580 .
8581 \end_layout
8582
8583 \begin_layout Description
8584 \begin_inset Flex CharStyle:Code
8585 status collapsed
8586
8587 \begin_layout Plain Layout
8588 Fill_Top
8589 \end_layout
8590
8591 \end_inset
8592
8593  [
8594 \begin_inset Flex CharStyle:Code
8595 status collapsed
8596
8597 \begin_layout Plain Layout
8598
8599 \emph on
8600 0
8601 \emph default
8602 ,1
8603 \end_layout
8604
8605 \end_inset
8606
8607 ] With this parameter the
8608 \begin_inset Flex CharStyle:MenuItem
8609 status collapsed
8610
8611 \begin_layout Plain Layout
8612 Fill
8613 \end_layout
8614
8615 \end_inset
8616
8617  value of the
8618 \begin_inset Quotes eld
8619 \end_inset
8620
8621 Vertical space above
8622 \begin_inset Quotes erd
8623 \end_inset
8624
8625  list of the
8626 \begin_inset Flex CharStyle:MenuItem
8627 status collapsed
8628
8629 \begin_layout Plain Layout
8630
8631 \bar under
8632 E
8633 \bar default
8634 dit\SpecialChar \menuseparator
8635
8636 \bar under
8637 P
8638 \bar default
8639 aragraph
8640 \begin_inset space ~
8641 \end_inset
8642
8643 Settings
8644 \end_layout
8645
8646 \end_inset
8647
8648  dialog can be set when initializing a paragraph with this style.
8649 \begin_inset Foot
8650 status collapsed
8651
8652 \begin_layout Plain Layout
8653
8654 \emph on
8655 Note from Jean-Marc:
8656 \emph default
8657  I'm not sure that this setting has much use, and it should probably be
8658  removed in later versions.
8659 \end_layout
8660
8661 \end_inset
8662
8663
8664 \end_layout
8665
8666 \begin_layout Description
8667 \begin_inset Flex CharStyle:Code
8668 status collapsed
8669
8670 \begin_layout Plain Layout
8671 Font
8672 \end_layout
8673
8674 \end_inset
8675
8676  The font used for both the text body
8677 \emph on
8678 and
8679 \emph default
8680  the label.
8681  See section
8682 \begin_inset space ~
8683 \end_inset
8684
8685
8686 \begin_inset CommandInset ref
8687 LatexCommand ref
8688 reference "sec:fonts"
8689
8690 \end_inset
8691
8692 .
8693  Note that defining this font automatically defines the
8694 \begin_inset Flex CharStyle:Code
8695 status collapsed
8696
8697 \begin_layout Plain Layout
8698 LabelFont
8699 \end_layout
8700
8701 \end_inset
8702
8703  to the same value.
8704  So you should define this one first if you also want to define
8705 \begin_inset Flex CharStyle:Code
8706 status collapsed
8707
8708 \begin_layout Plain Layout
8709 LabelFont
8710 \end_layout
8711
8712 \end_inset
8713
8714 .
8715 \end_layout
8716
8717 \begin_layout Description
8718 \begin_inset Flex CharStyle:Code
8719 status collapsed
8720
8721 \begin_layout Plain Layout
8722 FreeSpacing
8723 \end_layout
8724
8725 \end_inset
8726
8727
8728 \begin_inset CommandInset label
8729 LatexCommand label
8730 name "des:FreeSpacing"
8731
8732 \end_inset
8733
8734 [
8735 \emph on
8736
8737 \begin_inset Flex CharStyle:Code
8738 status collapsed
8739
8740 \begin_layout Plain Layout
8741
8742 \emph on
8743 0
8744 \end_layout
8745
8746 \end_inset
8747
8748
8749 \emph default
8750 ,
8751 \begin_inset Flex CharStyle:Code
8752 status collapsed
8753
8754 \begin_layout Plain Layout
8755 1
8756 \end_layout
8757
8758 \end_inset
8759
8760 ] Usually LyX doesn't allow you to insert more than one space between words,
8761  since a space is considered as the separation between two words, not a
8762  character or symbol of its own.
8763  This is a very fine thing but sometimes annoying, for example, when typing
8764  program code or plain LaTeX code.
8765  For this reason,
8766 \begin_inset Flex CharStyle:Code
8767 status collapsed
8768
8769 \begin_layout Plain Layout
8770 FreeSpacing
8771 \end_layout
8772
8773 \end_inset
8774
8775  can be enabled.
8776  Note that LyX will create protected blanks for the additional blanks when
8777  in another mode than LaTeX-mode.
8778 \end_layout
8779
8780 \begin_layout Description
8781 \begin_inset Flex CharStyle:Code
8782 status collapsed
8783
8784 \begin_layout Plain Layout
8785 InnerTag
8786 \end_layout
8787
8788 \end_inset
8789
8790  [[FIXME]]
8791 \end_layout
8792
8793 \begin_layout Description
8794 \begin_inset Flex CharStyle:Code
8795 status collapsed
8796
8797 \begin_layout Plain Layout
8798 InTitle
8799 \end_layout
8800
8801 \end_inset
8802
8803
8804 \begin_inset Flex CharStyle:Code
8805 status collapsed
8806
8807 \begin_layout Plain Layout
8808 [1, 0]
8809 \end_layout
8810
8811 \end_inset
8812
8813  If 1, marks the layout as being part of a title block (see also the
8814 \begin_inset Flex CharStyle:Code
8815 status collapsed
8816
8817 \begin_layout Plain Layout
8818 TitleLatexType
8819 \end_layout
8820
8821 \end_inset
8822
8823  and
8824 \begin_inset Flex CharStyle:Code
8825 status collapsed
8826
8827 \begin_layout Plain Layout
8828 TitleLatexName
8829 \end_layout
8830
8831 \end_inset
8832
8833  global entries).
8834 \end_layout
8835
8836 \begin_layout Description
8837 \begin_inset Flex CharStyle:Code
8838 status collapsed
8839
8840 \begin_layout Plain Layout
8841 ItemSep
8842 \end_layout
8843
8844 \end_inset
8845
8846  [
8847 \begin_inset Flex CharStyle:Code
8848 status collapsed
8849
8850 \begin_layout Plain Layout
8851 float=0
8852 \end_layout
8853
8854 \end_inset
8855
8856 ] This provides extra space between paragraphs that have the same layout.
8857  If you put other layouts into an environment, each is separated with the
8858  environment's
8859 \begin_inset Flex CharStyle:Code
8860 status collapsed
8861
8862 \begin_layout Plain Layout
8863 Parsep
8864 \end_layout
8865
8866 \end_inset
8867
8868 .
8869  But the whole items of the environment are additionally separated with
8870  this
8871 \begin_inset Flex CharStyle:Code
8872 status collapsed
8873
8874 \begin_layout Plain Layout
8875 Itemsep
8876 \end_layout
8877
8878 \end_inset
8879
8880 .
8881  Note that this is a
8882 \emph on
8883  multiplier.
8884 \end_layout
8885
8886 \begin_layout Description
8887 \begin_inset Flex CharStyle:Code
8888 status collapsed
8889
8890 \begin_layout Plain Layout
8891 ItemTag
8892 \end_layout
8893
8894 \end_inset
8895
8896  [[FIXME]]
8897 \end_layout
8898
8899 \begin_layout Description
8900 \begin_inset Flex CharStyle:Code
8901 status collapsed
8902
8903 \begin_layout Plain Layout
8904 KeepEmpty
8905 \end_layout
8906
8907 \end_inset
8908
8909
8910 \begin_inset CommandInset label
8911 LatexCommand label
8912 name "des:KeepEmpty"
8913
8914 \end_inset
8915
8916 [
8917 \emph on
8918
8919 \begin_inset Flex CharStyle:Code
8920 status collapsed
8921
8922 \begin_layout Plain Layout
8923
8924 \emph on
8925 0
8926 \end_layout
8927
8928 \end_inset
8929
8930
8931 \emph default
8932 ,
8933 \begin_inset Flex CharStyle:Code
8934 status collapsed
8935
8936 \begin_layout Plain Layout
8937 1
8938 \end_layout
8939
8940 \end_inset
8941
8942 ] Usually LyX does not allow you to leave a paragraph empty, since it would
8943  lead to empty LaTeX output.
8944  There are some cases where this could be desirable however: in a letter
8945  template, the required fields can be provided as empty fields, so that
8946  people do not forget them; in some special classes, a layout can be used
8947  as some kind of break, which does not contain actual text.
8948 \end_layout
8949
8950 \begin_layout Description
8951 \begin_inset Flex CharStyle:Code
8952 status collapsed
8953
8954 \begin_layout Plain Layout
8955 LabelBottomsep
8956 \end_layout
8957
8958 \end_inset
8959
8960  [float=0] The vertical space between the label and the text body.
8961  Only used for labels that are above the text body (
8962 \begin_inset Flex CharStyle:Code
8963 status collapsed
8964
8965 \begin_layout Plain Layout
8966 Top_Environment
8967 \end_layout
8968
8969 \end_inset
8970
8971 ,
8972 \begin_inset Flex CharStyle:Code
8973 status collapsed
8974
8975 \begin_layout Plain Layout
8976 Centered_Top_Environment
8977 \end_layout
8978
8979 \end_inset
8980
8981 ).
8982 \end_layout
8983
8984 \begin_layout Description
8985 \begin_inset Flex CharStyle:Code
8986 status collapsed
8987
8988 \begin_layout Plain Layout
8989 LabelCounter
8990 \end_layout
8991
8992 \end_inset
8993
8994  [
8995 \begin_inset Flex CharStyle:Code
8996 status collapsed
8997
8998 \begin_layout Plain Layout
8999 string=""
9000 \end_layout
9001
9002 \end_inset
9003
9004 ]
9005 \begin_inset Newline newline
9006 \end_inset
9007
9008 The name of the counter for automatic numbering (see Section
9009 \begin_inset CommandInset ref
9010 LatexCommand ref
9011 reference "sec:counter"
9012
9013 \end_inset
9014
9015  for details).
9016  This must be given if
9017 \begin_inset Flex CharStyle:Code
9018 status collapsed
9019
9020 \begin_layout Plain Layout
9021 Labeltype
9022 \end_layout
9023
9024 \end_inset
9025
9026  is
9027 \begin_inset Flex CharStyle:Code
9028 status collapsed
9029
9030 \begin_layout Plain Layout
9031 Counter
9032 \end_layout
9033
9034 \end_inset
9035
9036 .
9037 \end_layout
9038
9039 \begin_layout Description
9040 \begin_inset Flex CharStyle:Code
9041 status collapsed
9042
9043 \begin_layout Plain Layout
9044 LabelFont
9045 \end_layout
9046
9047 \end_inset
9048
9049  The font used for the label.
9050  See section
9051 \begin_inset space ~
9052 \end_inset
9053
9054
9055 \begin_inset CommandInset ref
9056 LatexCommand ref
9057 reference "sec:fonts"
9058
9059 \end_inset
9060
9061 .
9062 \end_layout
9063
9064 \begin_layout Description
9065 \begin_inset Flex CharStyle:Code
9066 status collapsed
9067
9068 \begin_layout Plain Layout
9069 Labelsep
9070 \end_layout
9071
9072 \end_inset
9073
9074  [
9075 \begin_inset Flex CharStyle:Code
9076 status collapsed
9077
9078 \begin_layout Plain Layout
9079 string=""
9080 \end_layout
9081
9082 \end_inset
9083
9084 ] The horizontal space between the label and the text body.
9085  Only used for labels that are not above the text body.
9086 \end_layout
9087
9088 \begin_layout Description
9089 \begin_inset Flex CharStyle:Code
9090 status collapsed
9091
9092 \begin_layout Plain Layout
9093 LabelString
9094 \end_layout
9095
9096 \end_inset
9097
9098  [
9099 \begin_inset Flex CharStyle:Code
9100 status collapsed
9101
9102 \begin_layout Plain Layout
9103 string=""
9104 \end_layout
9105
9106 \end_inset
9107
9108 ] The string used for a label with a
9109 \begin_inset Flex CharStyle:Code
9110 status collapsed
9111
9112 \begin_layout Plain Layout
9113 Static
9114 \end_layout
9115
9116 \end_inset
9117
9118  labeltype.
9119  When
9120 \begin_inset Flex CharStyle:Code
9121 status collapsed
9122
9123 \begin_layout Plain Layout
9124 LabelCounter
9125 \end_layout
9126
9127 \end_inset
9128
9129  is set, this string can be contain the special formatting commands described
9130  in Section
9131 \begin_inset CommandInset ref
9132 LatexCommand ref
9133 reference "sec:counter"
9134
9135 \end_inset
9136
9137 .
9138 \begin_inset Foot
9139 status collapsed
9140
9141 \begin_layout Plain Layout
9142 For the sake of backwards compatibility, the string
9143 \begin_inset Flex CharStyle:Code
9144 status collapsed
9145
9146 \begin_layout Plain Layout
9147 @
9148 \emph on
9149 style-name
9150 \emph default
9151 @
9152 \end_layout
9153
9154 \end_inset
9155
9156  will be replaced by the expanded
9157 \begin_inset Flex CharStyle:Code
9158 status collapsed
9159
9160 \begin_layout Plain Layout
9161 LabelString
9162 \end_layout
9163
9164 \end_inset
9165
9166  of style
9167 \begin_inset Flex CharStyle:Code
9168 status collapsed
9169
9170 \begin_layout Plain Layout
9171
9172 \emph on
9173 style-name
9174 \end_layout
9175
9176 \end_inset
9177
9178 .
9179  This feature is now obsolete and should be replaced by the mechanisms of
9180  Section
9181 \begin_inset CommandInset ref
9182 LatexCommand ref
9183 reference "sec:counter"
9184
9185 \end_inset
9186
9187 .
9188 \end_layout
9189
9190 \end_inset
9191
9192
9193 \end_layout
9194
9195 \begin_layout Description
9196 \begin_inset Flex CharStyle:Code
9197 status collapsed
9198
9199 \begin_layout Plain Layout
9200 LabelStringAppendix
9201 \end_layout
9202
9203 \end_inset
9204
9205  [
9206 \begin_inset Flex CharStyle:Code
9207 status collapsed
9208
9209 \begin_layout Plain Layout
9210 string=""
9211 \end_layout
9212
9213 \end_inset
9214
9215 ] This is used inside the appendix instead of
9216 \begin_inset Flex CharStyle:Code
9217 status collapsed
9218
9219 \begin_layout Plain Layout
9220 LabelString
9221 \end_layout
9222
9223 \end_inset
9224
9225 .
9226  Note that every
9227 \begin_inset Flex CharStyle:Code
9228 status collapsed
9229
9230 \begin_layout Plain Layout
9231 LabelString
9232 \end_layout
9233
9234 \end_inset
9235
9236  statement resets
9237 \begin_inset Flex CharStyle:Code
9238 status collapsed
9239
9240 \begin_layout Plain Layout
9241 LabelStringAppendix
9242 \end_layout
9243
9244 \end_inset
9245
9246  too.
9247 \end_layout
9248
9249 \begin_layout Description
9250 \begin_inset Flex CharStyle:Code
9251 status collapsed
9252
9253 \begin_layout Plain Layout
9254 Labeltype
9255 \end_layout
9256
9257 \end_inset
9258
9259  [
9260 \begin_inset Flex CharStyle:Code
9261 status collapsed
9262
9263 \begin_layout Plain Layout
9264
9265 \emph on
9266 No_Label
9267 \emph default
9268 , Manual, Static, Top_Environment,
9269 \begin_inset Newline newline
9270 \end_inset
9271
9272 Centered_Top_Environment, Sensitive, Counter
9273 \end_layout
9274
9275 \end_inset
9276
9277 ]
9278 \begin_inset Newline newline
9279 \end_inset
9280
9281
9282 \begin_inset Flex CharStyle:Code
9283 status collapsed
9284
9285 \begin_layout Plain Layout
9286 Manual
9287 \end_layout
9288
9289 \end_inset
9290
9291  means the label is the very first word (up to the first real blank).
9292 \begin_inset Foot
9293 status collapsed
9294
9295 \begin_layout Plain Layout
9296 Use protected spaces if you want more than one word as the label.
9297 \end_layout
9298
9299 \end_inset
9300
9301
9302 \begin_inset Flex CharStyle:Code
9303 status collapsed
9304
9305 \begin_layout Plain Layout
9306 Static
9307 \end_layout
9308
9309 \end_inset
9310
9311  means it is defined in the layout (see
9312 \begin_inset Flex CharStyle:Code
9313 status collapsed
9314
9315 \begin_layout Plain Layout
9316 LabelString
9317 \end_layout
9318
9319 \end_inset
9320
9321 ).
9322
9323 \begin_inset Flex CharStyle:Code
9324 status collapsed
9325
9326 \begin_layout Plain Layout
9327 Top_Environment
9328 \end_layout
9329
9330 \end_inset
9331
9332  and
9333 \begin_inset Flex CharStyle:Code
9334 status collapsed
9335
9336 \begin_layout Plain Layout
9337 Centered_Top_Environment
9338 \end_layout
9339
9340 \end_inset
9341
9342  are special cases of
9343 \begin_inset Flex CharStyle:Code
9344 status collapsed
9345
9346 \begin_layout Plain Layout
9347 Static
9348 \end_layout
9349
9350 \end_inset
9351
9352 .
9353  The label will be printed above the paragraph, but only at the top of an
9354  environment or the top of a chain of paragraphs with this layout.
9355  Usage is for example the
9356 \begin_inset Flex CharStyle:MenuItem
9357 status collapsed
9358
9359 \begin_layout Plain Layout
9360 Abstract
9361 \end_layout
9362
9363 \end_inset
9364
9365  layout or the
9366 \begin_inset Flex CharStyle:MenuItem
9367 status collapsed
9368
9369 \begin_layout Plain Layout
9370 Bibliography
9371 \end_layout
9372
9373 \end_inset
9374
9375  layout.
9376  This is also the case for
9377 \begin_inset Flex CharStyle:Code
9378 status collapsed
9379
9380 \begin_layout Plain Layout
9381 Manual
9382 \end_layout
9383
9384 \end_inset
9385
9386  labels with latex type
9387 \begin_inset Flex CharStyle:Code
9388 status collapsed
9389
9390 \begin_layout Plain Layout
9391 Environment
9392 \end_layout
9393
9394 \end_inset
9395
9396 , in order to make layouts for theorems work correctly.
9397
9398 \begin_inset Flex CharStyle:Code
9399 status collapsed
9400
9401 \begin_layout Plain Layout
9402 Sensitive
9403 \end_layout
9404
9405 \end_inset
9406
9407  is a special case for the caption-labels
9408 \begin_inset Quotes eld
9409 \end_inset
9410
9411 Figure
9412 \begin_inset Quotes erd
9413 \end_inset
9414
9415  and
9416 \begin_inset Quotes eld
9417 \end_inset
9418
9419 Table
9420 \begin_inset Quotes erd
9421 \end_inset
9422
9423 .
9424
9425 \begin_inset Flex CharStyle:Code
9426 status collapsed
9427
9428 \begin_layout Plain Layout
9429 Sensitive
9430 \end_layout
9431
9432 \end_inset
9433
9434  means the (hardcoded) label string depends on the kind of float.
9435  The
9436 \begin_inset Flex CharStyle:Code
9437 status collapsed
9438
9439 \begin_layout Plain Layout
9440 Counter
9441 \end_layout
9442
9443 \end_inset
9444
9445  label type defines automatically numbered labels.
9446  See Section
9447 \begin_inset CommandInset ref
9448 LatexCommand ref
9449 reference "sec:counter"
9450
9451 \end_inset
9452
9453 .
9454 \end_layout
9455
9456 \begin_layout Description
9457 \begin_inset Flex CharStyle:Code
9458 status collapsed
9459
9460 \begin_layout Plain Layout
9461 LatexFooter
9462 \end_layout
9463
9464 \end_inset
9465
9466  [[FIXME]]
9467 \end_layout
9468
9469 \begin_layout Description
9470 \begin_inset Flex CharStyle:Code
9471 status collapsed
9472
9473 \begin_layout Plain Layout
9474 LatexHeader
9475 \end_layout
9476
9477 \end_inset
9478
9479  [[FIXME]]
9480 \end_layout
9481
9482 \begin_layout Description
9483 \begin_inset Flex CharStyle:Code
9484 status collapsed
9485
9486 \begin_layout Plain Layout
9487 LatexName
9488 \end_layout
9489
9490 \end_inset
9491
9492  The name of the corresponding LaTeX stuff.
9493  Either the environment or command name.
9494 \end_layout
9495
9496 \begin_layout Description
9497 \begin_inset Flex CharStyle:Code
9498 status collapsed
9499
9500 \begin_layout Plain Layout
9501 LatexParagraph
9502 \end_layout
9503
9504 \end_inset
9505
9506  [[FIXME]]
9507 \end_layout
9508
9509 \begin_layout Description
9510 \begin_inset Flex CharStyle:Code
9511 status collapsed
9512
9513 \begin_layout Plain Layout
9514 LatexParam
9515 \end_layout
9516
9517 \end_inset
9518
9519  An optional parameter for the corresponding
9520 \begin_inset Flex CharStyle:Code
9521 status collapsed
9522
9523 \begin_layout Plain Layout
9524 LatexName
9525 \end_layout
9526
9527 \end_inset
9528
9529  stuff.
9530  This parameter cannot be changed from within LyX.
9531 \end_layout
9532
9533 \begin_layout Description
9534 \begin_inset Flex CharStyle:Code
9535 status collapsed
9536
9537 \begin_layout Plain Layout
9538 LatexType
9539 \end_layout
9540
9541 \end_inset
9542
9543
9544 \begin_inset CommandInset label
9545 LatexCommand label
9546 name "des:LatexType"
9547
9548 \end_inset
9549
9550 [
9551 \begin_inset Flex CharStyle:Code
9552 status collapsed
9553
9554 \begin_layout Plain Layout
9555
9556 \emph on
9557 Paragraph
9558 \emph default
9559 , Command, Environment, Item_Environment,
9560 \end_layout
9561
9562 \end_inset
9563
9564
9565 \begin_inset Flex CharStyle:Code
9566 status collapsed
9567
9568 \begin_layout Plain Layout
9569 List_Environment
9570 \end_layout
9571
9572 \end_inset
9573
9574 ] How the layout should be translated into LaTeX.
9575
9576 \begin_inset Flex CharStyle:Code
9577 status collapsed
9578
9579 \begin_layout Plain Layout
9580 Paragraph
9581 \end_layout
9582
9583 \end_inset
9584
9585  means nothing special.
9586
9587 \begin_inset Flex CharStyle:Code
9588 status collapsed
9589
9590 \begin_layout Plain Layout
9591 Command
9592 \end_layout
9593
9594 \end_inset
9595
9596  means
9597 \begin_inset Flex CharStyle:Code
9598 status collapsed
9599
9600 \begin_layout Plain Layout
9601
9602 \backslash
9603
9604 \emph on
9605 LatexName
9606 \emph default
9607 {\SpecialChar \ldots{}
9608 }
9609 \end_layout
9610
9611 \end_inset
9612
9613  and
9614 \begin_inset Flex CharStyle:Code
9615 status collapsed
9616
9617 \begin_layout Plain Layout
9618 Environment
9619 \end_layout
9620
9621 \end_inset
9622
9623  means
9624 \begin_inset Flex CharStyle:Code
9625 status collapsed
9626
9627 \begin_layout Plain Layout
9628
9629 \backslash
9630 begin{
9631 \emph on
9632 LatexName
9633 \emph default
9634 }\SpecialChar \ldots{}
9635
9636 \backslash
9637 end{
9638 \emph on
9639 LatexName
9640 \emph default
9641 }
9642 \end_layout
9643
9644 \end_inset
9645
9646 .
9647
9648 \begin_inset Flex CharStyle:Code
9649 status collapsed
9650
9651 \begin_layout Plain Layout
9652 Item_Environment
9653 \end_layout
9654
9655 \end_inset
9656
9657  is the same as
9658 \begin_inset Flex CharStyle:Code
9659 status collapsed
9660
9661 \begin_layout Plain Layout
9662 Environment
9663 \end_layout
9664
9665 \end_inset
9666
9667 , except that a
9668 \begin_inset Flex CharStyle:Code
9669 status collapsed
9670
9671 \begin_layout Plain Layout
9672
9673 \backslash
9674 item
9675 \end_layout
9676
9677 \end_inset
9678
9679  is generated for each paragraph of this environment.
9680
9681 \begin_inset Flex CharStyle:Code
9682 status collapsed
9683
9684 \begin_layout Plain Layout
9685 List_Environment
9686 \end_layout
9687
9688 \end_inset
9689
9690  is the same as
9691 \begin_inset Flex CharStyle:Code
9692 status collapsed
9693
9694 \begin_layout Plain Layout
9695 Item_Environment
9696 \end_layout
9697
9698 \end_inset
9699
9700 , except that
9701 \begin_inset Flex CharStyle:Code
9702 status collapsed
9703
9704 \begin_layout Plain Layout
9705 LabelWidthString
9706 \end_layout
9707
9708 \end_inset
9709
9710  is passed as an argument to the environment.
9711
9712 \begin_inset Flex CharStyle:Code
9713 status collapsed
9714
9715 \begin_layout Plain Layout
9716 LabelWidthString
9717 \end_layout
9718
9719 \end_inset
9720
9721  can be defined in the
9722 \begin_inset Flex CharStyle:MenuItem
9723 status collapsed
9724
9725 \begin_layout Plain Layout
9726
9727 \bar under
9728 L
9729 \bar default
9730 ayout\SpecialChar \menuseparator
9731
9732 \bar under
9733 P
9734 \bar default
9735 aragraph
9736 \end_layout
9737
9738 \end_inset
9739
9740  dialog.
9741
9742 \begin_inset Flex CharStyle:Code
9743 status collapsed
9744
9745 \begin_layout Plain Layout
9746
9747 \emph on
9748 LatexType
9749 \end_layout
9750
9751 \end_inset
9752
9753  is perhaps a bit misleading, since these rules apply to SGML classes, too.
9754  Visit the SGML class files for specific examples.
9755 \end_layout
9756
9757 \begin_layout Standard
9758 Putting the last few things together, the LaTeX output will be either:
9759 \end_layout
9760
9761 \begin_layout LyX-Code
9762
9763 \backslash
9764 latexname[latexparam]{\SpecialChar \ldots{}
9765 }
9766 \end_layout
9767
9768 \begin_layout Standard
9769 or:
9770 \end_layout
9771
9772 \begin_layout LyX-Code
9773
9774 \backslash
9775 begin{latexname}[latexparam] \SpecialChar \ldots{}
9776
9777 \backslash
9778 end{latexname}.
9779 \end_layout
9780
9781 \begin_layout Standard
9782 depending upon the LaTex type.
9783 \end_layout
9784
9785 \begin_layout Description
9786 \begin_inset Flex CharStyle:Code
9787 status collapsed
9788
9789 \begin_layout Plain Layout
9790 LeftMargin
9791 \end_layout
9792
9793 \end_inset
9794
9795  [
9796 \begin_inset Flex CharStyle:Code
9797 status collapsed
9798
9799 \begin_layout Plain Layout
9800 string=""
9801 \end_layout
9802
9803 \end_inset
9804
9805 ] If you put layouts into environments, the leftmargins are not simply added,
9806  but added with a factor
9807 \begin_inset Formula $\frac{4}{depth+4}$
9808 \end_inset
9809
9810 .
9811  Note that this parameter is also used when the margin is defined as
9812 \begin_inset Flex CharStyle:Code
9813 status collapsed
9814
9815 \begin_layout Plain Layout
9816 Manual
9817 \end_layout
9818
9819 \end_inset
9820
9821  or
9822 \begin_inset Flex CharStyle:Code
9823 status collapsed
9824
9825 \begin_layout Plain Layout
9826 Dynamic
9827 \end_layout
9828
9829 \end_inset
9830
9831 .
9832  Then it is added to the manual or dynamic margin.
9833
9834 \begin_inset Newline newline
9835 \end_inset
9836
9837 The argument is passed as a string.
9838  For example
9839 \begin_inset Quotes eld
9840 \end_inset
9841
9842
9843 \begin_inset Flex CharStyle:Code
9844 status collapsed
9845
9846 \begin_layout Plain Layout
9847 MM
9848 \end_layout
9849
9850 \end_inset
9851
9852
9853 \begin_inset Quotes erd
9854 \end_inset
9855
9856  means that the paragraph is indented with the width of
9857 \begin_inset Quotes eld
9858 \end_inset
9859
9860
9861 \begin_inset Flex CharStyle:Code
9862 status collapsed
9863
9864 \begin_layout Plain Layout
9865 MM
9866 \end_layout
9867
9868 \end_inset
9869
9870
9871 \begin_inset Quotes erd
9872 \end_inset
9873
9874  in the normal font.
9875  You can get a negative width by prefixing the string with
9876 \begin_inset Quotes eld
9877 \end_inset
9878
9879
9880 \begin_inset Flex CharStyle:Code
9881 status collapsed
9882
9883 \begin_layout Plain Layout
9884 -
9885 \end_layout
9886
9887 \end_inset
9888
9889
9890 \begin_inset Quotes erd
9891 \end_inset
9892
9893 .
9894  This way was chosen so that the look is the same with each used screen
9895  font.
9896
9897 \end_layout
9898
9899 \begin_layout Description
9900 \begin_inset Flex CharStyle:Code
9901 status collapsed
9902
9903 \begin_layout Plain Layout
9904 Margin
9905 \end_layout
9906
9907 \end_inset
9908
9909  [
9910 \begin_inset Flex CharStyle:Code
9911 status collapsed
9912
9913 \begin_layout Plain Layout
9914
9915 \emph on
9916 Static
9917 \emph default
9918 , Manual, Dynamic, First_Dynamic, Right_Address_Box
9919 \end_layout
9920
9921 \end_inset
9922
9923 ]
9924 \begin_inset Newline newline
9925 \end_inset
9926
9927 The kind of margin that the layout has on the left side.
9928
9929 \begin_inset Flex CharStyle:Code
9930 status collapsed
9931
9932 \begin_layout Plain Layout
9933 Static
9934 \end_layout
9935
9936 \end_inset
9937
9938  just means a fixed margin.
9939
9940 \begin_inset Flex CharStyle:Code
9941 status collapsed
9942
9943 \begin_layout Plain Layout
9944 Manual
9945 \end_layout
9946
9947 \end_inset
9948
9949  means that the left margin depends on the string entered in the
9950 \begin_inset Flex CharStyle:MenuItem
9951 status collapsed
9952
9953 \begin_layout Plain Layout
9954
9955 \bar under
9956 E
9957 \bar default
9958 dit\SpecialChar \menuseparator
9959
9960 \bar under
9961 P
9962 \bar default
9963 aragraph
9964 \begin_inset space ~
9965 \end_inset
9966
9967 Settings
9968 \end_layout
9969
9970 \end_inset
9971
9972  dialog.
9973  This is used to typeset nice lists without tabulators.
9974
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  means that the margin depends on the size of the label.
9985  This is used for automatic enumerated headlines.
9986  It is obvious that the headline
9987 \begin_inset Quotes eld
9988 \end_inset
9989
9990 5.4.3.2.1 Very long headline
9991 \begin_inset Quotes erd
9992 \end_inset
9993
9994  must have a wider left margin (as wide as
9995 \begin_inset Quotes eld
9996 \end_inset
9997
9998 5.4.3.2.1
9999 \begin_inset Quotes erd
10000 \end_inset
10001
10002  plus the space) than
10003 \begin_inset Quotes eld
10004 \end_inset
10005
10006 3.2 Very long headline
10007 \begin_inset Quotes erd
10008 \end_inset
10009
10010 , even if standard
10011 \begin_inset Quotes eld
10012 \end_inset
10013
10014 word processors
10015 \begin_inset Quotes erd
10016 \end_inset
10017
10018  are not able to do this.
10019
10020 \begin_inset Flex CharStyle:Code
10021 status collapsed
10022
10023 \begin_layout Plain Layout
10024 First_Dynamic
10025 \end_layout
10026
10027 \end_inset
10028
10029  is similar, but only the very first row of the paragraph is dynamic, while
10030  the others are static; this is used, for example, for descriptions.
10031
10032 \begin_inset Flex CharStyle:Code
10033 status collapsed
10034
10035 \begin_layout Plain Layout
10036 Right_Address_Box
10037 \end_layout
10038
10039 \end_inset
10040
10041  means the margin is chosen in a way that the longest row of this paragraph
10042  fits to the right margin.
10043  This is used to typeset an address on the right edge of the page.
10044 \end_layout
10045
10046 \begin_layout Description
10047 \begin_inset Flex CharStyle:Code
10048 status collapsed
10049
10050 \begin_layout Plain Layout
10051 NeedProtect
10052 \end_layout
10053
10054 \end_inset
10055
10056  [
10057 \begin_inset Flex CharStyle:Code
10058 status collapsed
10059
10060 \begin_layout Plain Layout
10061
10062 \emph on
10063 0
10064 \end_layout
10065
10066 \end_inset
10067
10068 ,
10069 \begin_inset Flex CharStyle:Code
10070 status collapsed
10071
10072 \begin_layout Plain Layout
10073 1
10074 \end_layout
10075
10076 \end_inset
10077
10078 ] Whether fragile commands in this layout should be
10079 \begin_inset Flex CharStyle:Code
10080 status collapsed
10081
10082 \begin_layout Plain Layout
10083
10084 \backslash
10085 protect
10086 \end_layout
10087
10088 \end_inset
10089
10090 'ed.
10091  (Note: This is
10092 \emph on
10093 not
10094 \emph default
10095  whether this command should itself be protected.)
10096 \end_layout
10097
10098 \begin_layout Description
10099 \begin_inset Flex CharStyle:Code
10100 status collapsed
10101
10102 \begin_layout Plain Layout
10103 Newline
10104 \end_layout
10105
10106 \end_inset
10107
10108  [
10109 \begin_inset Flex CharStyle:Code
10110 status collapsed
10111
10112 \begin_layout Plain Layout
10113 0
10114 \end_layout
10115
10116 \end_inset
10117
10118 ,
10119 \begin_inset Flex CharStyle:Code
10120 status collapsed
10121
10122 \begin_layout Plain Layout
10123
10124 \emph on
10125 1
10126 \end_layout
10127
10128 \end_inset
10129
10130 ] Whether newlines are translated into LaTeX newlines (
10131 \begin_inset Flex CharStyle:Code
10132 status collapsed
10133
10134 \begin_layout Plain Layout
10135
10136 \backslash
10137
10138 \backslash
10139
10140 \end_layout
10141
10142 \end_inset
10143
10144 ) or not.
10145  The translation can be switched off to allow more comfortable LaTeX editing
10146  inside LyX.
10147 \end_layout
10148
10149 \begin_layout Description
10150 \begin_inset Flex CharStyle:Code
10151 status collapsed
10152
10153 \begin_layout Plain Layout
10154 NextNoIndent
10155 \end_layout
10156
10157 \end_inset
10158
10159  [
10160 \begin_inset Flex CharStyle:Code
10161 status collapsed
10162
10163 \begin_layout Plain Layout
10164 1
10165 \end_layout
10166
10167 \end_inset
10168
10169 ,
10170 \begin_inset Flex CharStyle:Code
10171 status collapsed
10172
10173 \begin_layout Plain Layout
10174
10175 \emph on
10176 0
10177 \end_layout
10178
10179 \end_inset
10180
10181 ] Whether the following Paragraph is allowed to indent its very first row.
10182
10183 \begin_inset Flex CharStyle:Code
10184 status collapsed
10185
10186 \begin_layout Plain Layout
10187 1
10188 \end_layout
10189
10190 \end_inset
10191
10192  means that it is not allowed to do so;
10193 \begin_inset Flex CharStyle:Code
10194 status collapsed
10195
10196 \begin_layout Plain Layout
10197 0
10198 \end_layout
10199
10200 \end_inset
10201
10202  means it could do so if it wants to.
10203 \end_layout
10204
10205 \begin_layout Description
10206 \begin_inset Flex CharStyle:Code
10207 status collapsed
10208
10209 \begin_layout Plain Layout
10210 ObsoletedBy
10211 \end_layout
10212
10213 \end_inset
10214
10215  [[FIXME]]
10216 \end_layout
10217
10218 \begin_layout Description
10219 \begin_inset Flex CharStyle:Code
10220 status collapsed
10221
10222 \begin_layout Plain Layout
10223 OptionalArgs
10224 \end_layout
10225
10226 \end_inset
10227
10228  [
10229 \begin_inset Flex CharStyle:Code
10230 status collapsed
10231
10232 \begin_layout Plain Layout
10233 int=0
10234 \end_layout
10235
10236 \end_inset
10237
10238 ] The number of optional arguments that can be used with this layout.
10239  This is useful for things like section headings, and only makes sense with
10240  LaTeX.
10241 \end_layout
10242
10243 \begin_layout Description
10244 \begin_inset Flex CharStyle:Code
10245 status collapsed
10246
10247 \begin_layout Plain Layout
10248 ParIndent
10249 \end_layout
10250
10251 \end_inset
10252
10253  [
10254 \begin_inset Flex CharStyle:Code
10255 status collapsed
10256
10257 \begin_layout Plain Layout
10258 string=""
10259 \end_layout
10260
10261 \end_inset
10262
10263 ] The indent of the very first line of a paragraph.
10264  The
10265 \begin_inset Flex CharStyle:Code
10266 status collapsed
10267
10268 \begin_layout Plain Layout
10269 Parindent
10270 \end_layout
10271
10272 \end_inset
10273
10274  will be fixed for a certain layout.
10275  The exception is Standard layout, since the indentation of a Standard layout
10276  paragraph can be prohibited with
10277 \begin_inset Flex CharStyle:Code
10278 status collapsed
10279
10280 \begin_layout Plain Layout
10281 NextNoIndent
10282 \end_layout
10283
10284 \end_inset
10285
10286 .
10287  Also, Standard layout paragraphs inside environments use the
10288 \begin_inset Flex CharStyle:Code
10289 status collapsed
10290
10291 \begin_layout Plain Layout
10292 Parindent
10293 \end_layout
10294
10295 \end_inset
10296
10297  of the environment, not their native one.
10298  For example, Standard paragraphs inside an enumeration are not indented.
10299 \end_layout
10300
10301 \begin_layout Description
10302 \begin_inset Flex CharStyle:Code
10303 status collapsed
10304
10305 \begin_layout Plain Layout
10306 Parsep
10307 \end_layout
10308
10309 \end_inset
10310
10311  [
10312 \begin_inset Flex CharStyle:Code
10313 status collapsed
10314
10315 \begin_layout Plain Layout
10316 float=0
10317 \end_layout
10318
10319 \end_inset
10320
10321 ] The vertical space between two paragraphs of this layout.
10322 \end_layout
10323
10324 \begin_layout Description
10325 \begin_inset Flex CharStyle:Code
10326 status collapsed
10327
10328 \begin_layout Plain Layout
10329 Parskip
10330 \end_layout
10331
10332 \end_inset
10333
10334  [
10335 \begin_inset Flex CharStyle:Code
10336 status collapsed
10337
10338 \begin_layout Plain Layout
10339 float=0
10340 \end_layout
10341
10342 \end_inset
10343
10344 ] LyX allows the user to choose either
10345 \begin_inset Quotes eld
10346 \end_inset
10347
10348 indent
10349 \begin_inset Quotes erd
10350 \end_inset
10351
10352  or
10353 \begin_inset Quotes eld
10354 \end_inset
10355
10356 skip
10357 \begin_inset Quotes erd
10358 \end_inset
10359
10360  to typeset a document.
10361  When
10362 \begin_inset Quotes eld
10363 \end_inset
10364
10365 indent
10366 \begin_inset Quotes erd
10367 \end_inset
10368
10369  is chosen, this value is completely ignored.
10370  When
10371 \begin_inset Quotes eld
10372 \end_inset
10373
10374 skip
10375 \begin_inset Quotes erd
10376 \end_inset
10377
10378  is chosen, the parindent of a LaTeXtype
10379 \begin_inset Quotes eld
10380 \end_inset
10381
10382 Paragraph
10383 \begin_inset Quotes erd
10384 \end_inset
10385
10386  layout is ignored and all paragraphs are separated by this parskip argument.
10387  The vertical space is calculated with
10388 \begin_inset Flex CharStyle:Code
10389 status collapsed
10390
10391 \begin_layout Plain Layout
10392 value
10393 \begin_inset space ~
10394 \end_inset
10395
10396 * DefaultHeight
10397 \end_layout
10398
10399 \end_inset
10400
10401  where
10402 \begin_inset Flex CharStyle:Code
10403 status collapsed
10404
10405 \begin_layout Plain Layout
10406 DefaultHeight
10407 \end_layout
10408
10409 \end_inset
10410
10411  is the height of a row with the normal font.
10412  This way, the look stays the same with different screen fonts.
10413 \end_layout
10414
10415 \begin_layout Description
10416 \begin_inset Flex CharStyle:Code
10417 status collapsed
10418
10419 \begin_layout Plain Layout
10420 PassThru
10421 \end_layout
10422
10423 \end_inset
10424
10425  [
10426 \emph on
10427
10428 \begin_inset Flex CharStyle:Code
10429 status collapsed
10430
10431 \begin_layout Plain Layout
10432
10433 \emph on
10434 0
10435 \end_layout
10436
10437 \end_inset
10438
10439
10440 \emph default
10441 ,
10442 \begin_inset Flex CharStyle:Code
10443 status collapsed
10444
10445 \begin_layout Plain Layout
10446 1
10447 \end_layout
10448
10449 \end_inset
10450
10451 ] Whether the contents of this paragraph should be output in raw form, meaning
10452  without special translations that LaTeX would require.
10453 \end_layout
10454
10455 \begin_layout Description
10456 \begin_inset Flex CharStyle:Code
10457 status collapsed
10458
10459 \begin_layout Plain Layout
10460 Preamble
10461 \end_layout
10462
10463 \end_inset
10464
10465
10466 \begin_inset CommandInset label
10467 LatexCommand label
10468 name "des:Preamble"
10469
10470 \end_inset
10471
10472 Information to be included in the LaTeX preamable when this style is used.
10473  Used to define macros, load packages, etc., required by this particular
10474  style.
10475  Must end with
10476 \begin_inset Quotes eld
10477 \end_inset
10478
10479
10480 \begin_inset Flex CharStyle:Code
10481 status collapsed
10482
10483 \begin_layout Plain Layout
10484 EndPreamble
10485 \end_layout
10486
10487 \end_inset
10488
10489
10490 \begin_inset Quotes erd
10491 \end_inset
10492
10493 .
10494 \end_layout
10495
10496 \begin_layout Description
10497 \begin_inset Flex CharStyle:Code
10498 status collapsed
10499
10500 \begin_layout Plain Layout
10501 Requires
10502 \end_layout
10503
10504 \end_inset
10505
10506 [
10507 \begin_inset Flex CharStyle:Code
10508 status collapsed
10509
10510 \begin_layout Plain Layout
10511 string
10512 \end_layout
10513
10514 \end_inset
10515
10516 ]
10517 \begin_inset CommandInset label
10518 LatexCommand label
10519 name "des:Requires"
10520
10521 \end_inset
10522
10523 Whether the layout requires the feature
10524 \begin_inset Flex CharStyle:Code
10525 status collapsed
10526
10527 \begin_layout Plain Layout
10528 string
10529 \end_layout
10530
10531 \end_inset
10532
10533 .
10534  See the description of
10535 \begin_inset Flex CharStyle:Code
10536 status collapsed
10537
10538 \begin_layout Plain Layout
10539 Provides
10540 \end_layout
10541
10542 \end_inset
10543
10544  above (page
10545 \begin_inset CommandInset ref
10546 LatexCommand pageref
10547 reference "des:FreeSpacing"
10548
10549 \end_inset
10550
10551 ) for information on `features'.
10552
10553 \end_layout
10554
10555 \begin_layout Description
10556 \begin_inset Flex CharStyle:Code
10557 status collapsed
10558
10559 \begin_layout Plain Layout
10560 RightMargin
10561 \end_layout
10562
10563 \end_inset
10564
10565  [
10566 \begin_inset Flex CharStyle:Code
10567 status collapsed
10568
10569 \begin_layout Plain Layout
10570 string=""
10571 \end_layout
10572
10573 \end_inset
10574
10575 ] Similar to
10576 \begin_inset Flex CharStyle:Code
10577 status collapsed
10578
10579 \begin_layout Plain Layout
10580 LeftMargin
10581 \end_layout
10582
10583 \end_inset
10584
10585 .
10586 \end_layout
10587
10588 \begin_layout Description
10589 \begin_inset Flex CharStyle:Code
10590 status collapsed
10591
10592 \begin_layout Plain Layout
10593 Spacing
10594 \end_layout
10595
10596 \end_inset
10597
10598  [
10599 \begin_inset Flex CharStyle:Code
10600 status collapsed
10601
10602 \begin_layout Plain Layout
10603
10604 \emph on
10605 single
10606 \emph default
10607 , onehalf, double, other
10608 \end_layout
10609
10610 \end_inset
10611
10612
10613 \emph on
10614 value
10615 \emph default
10616 ] This defines what the default spacing should be in the layout.
10617  The arguments
10618 \begin_inset Flex CharStyle:Code
10619 status collapsed
10620
10621 \begin_layout Plain Layout
10622 single
10623 \end_layout
10624
10625 \end_inset
10626
10627 ,
10628 \begin_inset Flex CharStyle:Code
10629 status collapsed
10630
10631 \begin_layout Plain Layout
10632 onehalf
10633 \end_layout
10634
10635 \end_inset
10636
10637  and
10638 \begin_inset Flex CharStyle:Code
10639 status collapsed
10640
10641 \begin_layout Plain Layout
10642 double
10643 \end_layout
10644
10645 \end_inset
10646
10647  correspond respectively to a multiplier value of 1, 1.25 and 1.667.
10648  If you specify the argument
10649 \begin_inset Flex CharStyle:Code
10650 status collapsed
10651
10652 \begin_layout Plain Layout
10653 other
10654 \end_layout
10655
10656 \end_inset
10657
10658 , then you should also provide a numerical argument which will be the actual
10659  multiplier value.
10660  Note that, contrary to other parameters,
10661 \begin_inset Flex CharStyle:Code
10662 status collapsed
10663
10664 \begin_layout Plain Layout
10665 Spacing
10666 \end_layout
10667
10668 \end_inset
10669
10670  implies the generation of specific LaTeX code, using the package
10671 \family roman
10672
10673 \begin_inset Flex CharStyle:Code
10674 status collapsed
10675
10676 \begin_layout Plain Layout
10677 setspace.sty
10678 \end_layout
10679
10680 \end_inset
10681
10682 .
10683 \end_layout
10684
10685 \begin_layout Description
10686 \begin_inset Flex CharStyle:Code
10687 status collapsed
10688
10689 \begin_layout Plain Layout
10690 TextFont
10691 \end_layout
10692
10693 \end_inset
10694
10695  The font used for the text body .
10696  See section
10697 \begin_inset CommandInset ref
10698 LatexCommand ref
10699 reference "sec:fonts"
10700
10701 \end_inset
10702
10703 .
10704 \end_layout
10705
10706 \begin_layout Description
10707 Need
10708 \begin_inset Flex CharStyle:Code
10709 status collapsed
10710
10711 \begin_layout Plain Layout
10712
10713 \series medium
10714 TocLevel [int]
10715 \end_layout
10716
10717 \end_inset
10718
10719  The level of the style in the table of contents.
10720  This is used for automatic numbering of section headings.
10721 \end_layout
10722
10723 \begin_layout Description
10724 \begin_inset Flex CharStyle:Code
10725 status collapsed
10726
10727 \begin_layout Plain Layout
10728 TopSep
10729 \end_layout
10730
10731 \end_inset
10732
10733  [
10734 \begin_inset Flex CharStyle:Code
10735 status collapsed
10736
10737 \begin_layout Plain Layout
10738 float=0
10739 \end_layout
10740
10741 \end_inset
10742
10743 ] The vertical space with which the very first of a chain of paragraphs
10744  with this layout is separated from the previous paragraph.
10745  If the previous paragraph has another layout, the separations are not simply
10746  added, but the maximum is taken.
10747 \end_layout
10748
10749 \begin_layout Subsection
10750 Floats
10751 \end_layout
10752
10753 \begin_layout Standard
10754 \begin_inset CommandInset label
10755 LatexCommand label
10756 name "sec:floats"
10757
10758 \end_inset
10759
10760 Since version 1.3.0 of LyX, it is has been both possible and necessary to
10761  define the floats (
10762 \begin_inset Flex CharStyle:MenuItem
10763 status collapsed
10764
10765 \begin_layout Plain Layout
10766 figure
10767 \end_layout
10768
10769 \end_inset
10770
10771 ,
10772 \begin_inset Flex CharStyle:MenuItem
10773 status collapsed
10774
10775 \begin_layout Plain Layout
10776 table
10777 \end_layout
10778
10779 \end_inset
10780
10781 , \SpecialChar \ldots{}
10782 ) in the text class itself.
10783  Standard floats are included in the file
10784 \begin_inset Flex CharStyle:Code
10785 status collapsed
10786
10787 \begin_layout Plain Layout
10788 stdfloats.inc
10789 \end_layout
10790
10791 \end_inset
10792
10793 , so you may have to do no more than add
10794 \end_layout
10795
10796 \begin_layout LyX-Code
10797 Input stdfloats.inc
10798 \end_layout
10799
10800 \begin_layout Standard
10801 to your layout file.
10802  If you want to implement a text class that proposes some other float types
10803  (like the AGU class bundled with LyX), the information below will hopefully
10804  help you:
10805 \end_layout
10806
10807 \begin_layout Description
10808 \begin_inset Flex CharStyle:Code
10809 status collapsed
10810
10811 \begin_layout Plain Layout
10812 Extension
10813 \end_layout
10814
10815 \end_inset
10816
10817  [
10818 \begin_inset Flex CharStyle:Code
10819 status collapsed
10820
10821 \begin_layout Plain Layout
10822 string
10823 \end_layout
10824
10825 \end_inset
10826
10827 =
10828 \begin_inset Quotes erd
10829 \end_inset
10830
10831
10832 \begin_inset Quotes erd
10833 \end_inset
10834
10835 ] The file name extension of an auxiliary file for the list of figures (or
10836  whatever).
10837  LaTeX writes the captions to this file.
10838 \end_layout
10839
10840 \begin_layout Description
10841 \begin_inset Flex CharStyle:Code
10842 status collapsed
10843
10844 \begin_layout Plain Layout
10845 GuiName
10846 \end_layout
10847
10848 \end_inset
10849
10850  [
10851 \begin_inset Flex CharStyle:Code
10852 status collapsed
10853
10854 \begin_layout Plain Layout
10855 string
10856 \end_layout
10857
10858 \end_inset
10859
10860 =
10861 \begin_inset Quotes erd
10862 \end_inset
10863
10864
10865 \begin_inset Quotes erd
10866 \end_inset
10867
10868 ] The string that will be used in the menus and also for the caption.
10869 \end_layout
10870
10871 \begin_layout Description
10872 \begin_inset Flex CharStyle:Code
10873 status collapsed
10874
10875 \begin_layout Plain Layout
10876 LaTeXBuiltin
10877 \end_layout
10878
10879 \end_inset
10880
10881  [
10882 \begin_inset Flex CharStyle:Code
10883 status collapsed
10884
10885 \begin_layout Plain Layout
10886
10887 \emph on
10888 0
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 1
10899 \end_layout
10900
10901 \end_inset
10902
10903 ] Set to
10904 \begin_inset Flex CharStyle:Code
10905 status collapsed
10906
10907 \begin_layout Plain Layout
10908 1
10909 \end_layout
10910
10911 \end_inset
10912
10913  if the float is already defined by the LaTeX document class.
10914  If this is set to
10915 \begin_inset Flex CharStyle:Code
10916 status collapsed
10917
10918 \begin_layout Plain Layout
10919 0
10920 \end_layout
10921
10922 \end_inset
10923
10924 , the float will be defined using the LaTeX package
10925 \begin_inset Flex CharStyle:Code
10926 status collapsed
10927
10928 \begin_layout Plain Layout
10929 float
10930 \end_layout
10931
10932 \end_inset
10933
10934 .
10935 \end_layout
10936
10937 \begin_layout Description
10938 \begin_inset Flex CharStyle:Code
10939 status collapsed
10940
10941 \begin_layout Plain Layout
10942 ListName
10943 \end_layout
10944
10945 \end_inset
10946
10947  [
10948 \begin_inset Flex CharStyle:Code
10949 status collapsed
10950
10951 \begin_layout Plain Layout
10952 string
10953 \end_layout
10954
10955 \end_inset
10956
10957 =
10958 \begin_inset Quotes erd
10959 \end_inset
10960
10961
10962 \begin_inset Quotes erd
10963 \end_inset
10964
10965 ] The heading used for the list of floats.
10966 \end_layout
10967
10968 \begin_layout Description
10969 \begin_inset Flex CharStyle:Code
10970 status collapsed
10971
10972 \begin_layout Plain Layout
10973 NumberWithin
10974 \end_layout
10975
10976 \end_inset
10977
10978  [
10979 \begin_inset Flex CharStyle:Code
10980 status collapsed
10981
10982 \begin_layout Plain Layout
10983 string
10984 \end_layout
10985
10986 \end_inset
10987
10988 =
10989 \begin_inset Quotes erd
10990 \end_inset
10991
10992
10993 \begin_inset Quotes erd
10994 \end_inset
10995
10996 ] This (optional) argument determines whether floats of this class will
10997  be numbered within some sectional unit of the document.
10998  For example, if within is equal to
10999 \begin_inset Flex CharStyle:Code
11000 status collapsed
11001
11002 \begin_layout Plain Layout
11003 chapter
11004 \end_layout
11005
11006 \end_inset
11007
11008 , the floats will be numbered within chapters.
11009
11010 \end_layout
11011
11012 \begin_layout Description
11013 \begin_inset Flex CharStyle:Code
11014 status collapsed
11015
11016 \begin_layout Plain Layout
11017 Placement
11018 \end_layout
11019
11020 \end_inset
11021
11022  [
11023 \begin_inset Flex CharStyle:Code
11024 status collapsed
11025
11026 \begin_layout Plain Layout
11027 string
11028 \end_layout
11029
11030 \end_inset
11031
11032 =
11033 \begin_inset Quotes erd
11034 \end_inset
11035
11036
11037 \begin_inset Quotes erd
11038 \end_inset
11039
11040 ] The default placement for the given class of floats.
11041  The string should be as in standard LaTeX:
11042 \begin_inset Flex CharStyle:Code
11043 status collapsed
11044
11045 \begin_layout Plain Layout
11046 t
11047 \end_layout
11048
11049 \end_inset
11050
11051 ,
11052 \begin_inset Flex CharStyle:Code
11053 status collapsed
11054
11055 \begin_layout Plain Layout
11056 b
11057 \end_layout
11058
11059 \end_inset
11060
11061 ,
11062 \begin_inset Flex CharStyle:Code
11063 status collapsed
11064
11065 \begin_layout Plain Layout
11066 p
11067 \end_layout
11068
11069 \end_inset
11070
11071  and
11072 \begin_inset Flex CharStyle:Code
11073 status collapsed
11074
11075 \begin_layout Plain Layout
11076 h
11077 \end_layout
11078
11079 \end_inset
11080
11081  for top, bottom, page, and here, respectively.
11082 \begin_inset Foot
11083 status collapsed
11084
11085 \begin_layout Plain Layout
11086 Note that the order of these letters in the string is irrelevant, like in
11087  LaTeX.
11088 \end_layout
11089
11090 \end_inset
11091
11092  On top of that there is a new type,
11093 \begin_inset Flex CharStyle:Code
11094 status collapsed
11095
11096 \begin_layout Plain Layout
11097 H
11098 \end_layout
11099
11100 \end_inset
11101
11102 , which does not really correspond to a float, since it means: put it
11103 \begin_inset Quotes eld
11104 \end_inset
11105
11106 here
11107 \begin_inset Quotes erd
11108 \end_inset
11109
11110  and nowhere else.
11111  Note however that the
11112 \begin_inset Flex CharStyle:Code
11113 status collapsed
11114
11115 \begin_layout Plain Layout
11116 H
11117 \end_layout
11118
11119 \end_inset
11120
11121  specifier is special and, because of implementation details, cannot be
11122  used in non-builtin float types.
11123  If you do not understand what this means, just use
11124 \begin_inset Quotes eld
11125 \end_inset
11126
11127
11128 \begin_inset Flex CharStyle:Code
11129 status collapsed
11130
11131 \begin_layout Plain Layout
11132 tbp
11133 \end_layout
11134
11135 \end_inset
11136
11137
11138 \begin_inset Quotes erd
11139 \end_inset
11140
11141 .
11142 \end_layout
11143
11144 \begin_layout Description
11145 \begin_inset Flex CharStyle:Code
11146 status collapsed
11147
11148 \begin_layout Plain Layout
11149 Style
11150 \end_layout
11151
11152 \end_inset
11153
11154  [
11155 \begin_inset Flex CharStyle:Code
11156 status collapsed
11157
11158 \begin_layout Plain Layout
11159 string
11160 \end_layout
11161
11162 \end_inset
11163
11164 =
11165 \begin_inset Quotes erd
11166 \end_inset
11167
11168
11169 \begin_inset Quotes erd
11170 \end_inset
11171
11172 ] The style used when defining the float using
11173 \begin_inset Flex CharStyle:Code
11174 status collapsed
11175
11176 \begin_layout Plain Layout
11177
11178 \backslash
11179 newfloat
11180 \end_layout
11181
11182 \end_inset
11183
11184 .
11185 \end_layout
11186
11187 \begin_layout Description
11188 \begin_inset Flex CharStyle:Code
11189 status collapsed
11190
11191 \begin_layout Plain Layout
11192 Type
11193 \end_layout
11194
11195 \end_inset
11196
11197  [
11198 \begin_inset Flex CharStyle:Code
11199 status collapsed
11200
11201 \begin_layout Plain Layout
11202 string
11203 \end_layout
11204
11205 \end_inset
11206
11207 =
11208 \begin_inset Quotes erd
11209 \end_inset
11210
11211
11212 \begin_inset Quotes erd
11213 \end_inset
11214
11215 ] The
11216 \begin_inset Quotes eld
11217 \end_inset
11218
11219 type
11220 \begin_inset Quotes erd
11221 \end_inset
11222
11223  of the new class of floats, like program or algorithm.
11224  After the appropriate
11225 \begin_inset Flex CharStyle:Code
11226 status collapsed
11227
11228 \begin_layout Plain Layout
11229
11230 \backslash
11231 newfloat
11232 \end_layout
11233
11234 \end_inset
11235
11236 , commands such as
11237 \begin_inset Flex CharStyle:Code
11238 status collapsed
11239
11240 \begin_layout Plain Layout
11241
11242 \backslash
11243 begin{program}
11244 \end_layout
11245
11246 \end_inset
11247
11248  or
11249 \begin_inset Flex CharStyle:Code
11250 status collapsed
11251
11252 \begin_layout Plain Layout
11253
11254 \backslash
11255 end{algorithm*}
11256 \end_layout
11257
11258 \end_inset
11259
11260  will be available.
11261 \end_layout
11262
11263 \begin_layout Standard
11264 Note that defining a float with type
11265 \begin_inset Flex CharStyle:Code
11266 status collapsed
11267
11268 \begin_layout Plain Layout
11269
11270 \emph on
11271 type
11272 \end_layout
11273
11274 \end_inset
11275
11276  automatically defines the corresponding counter with name
11277 \begin_inset Flex CharStyle:Code
11278 status collapsed
11279
11280 \begin_layout Plain Layout
11281
11282 \emph on
11283 type
11284 \end_layout
11285
11286 \end_inset
11287
11288 .
11289 \end_layout
11290
11291 \begin_layout Subsection
11292 Inset layouts and Flex insets
11293 \end_layout
11294
11295 \begin_layout Standard
11296 \begin_inset CommandInset label
11297 LatexCommand label
11298 name "sec:charstyle"
11299
11300 \end_inset
11301
11302 LyX has supported character styles since version 1.4.0; since version 1.6.0
11303  these are called Flex insets.
11304
11305 \end_layout
11306
11307 \begin_layout Standard
11308 Furthermore, it is possible to define the general layout of many different
11309  types of insets.
11310  Currently, InsetLayout can be used to customize the  layout parameters
11311  for footnotes, marginal notes, note insets, ERT insets, branches, listings,
11312  indexes, boxes, tables, algorithms, URLs, and optional arguments, as well
11313  as Flex insets.
11314
11315 \end_layout
11316
11317 \begin_layout Standard
11318 Flex insets come in three different kinds:
11319 \end_layout
11320
11321 \begin_layout Itemize
11322 character style (
11323 \begin_inset Flex CharStyle:Code
11324 status collapsed
11325
11326 \begin_layout Plain Layout
11327 CharStyle
11328 \end_layout
11329
11330 \end_inset
11331
11332 ): These define semantic markup corresponding to such LaTeX commands as
11333
11334 \begin_inset Flex CharStyle:Code
11335 status collapsed
11336
11337 \begin_layout Plain Layout
11338
11339 \backslash
11340 noun
11341 \end_layout
11342
11343 \end_inset
11344
11345  and
11346 \begin_inset Flex CharStyle:Code
11347 status collapsed
11348
11349 \begin_layout Plain Layout
11350
11351 \backslash
11352 code
11353 \end_layout
11354
11355 \end_inset
11356
11357 .
11358 \end_layout
11359
11360 \begin_layout Itemize
11361 user custom (
11362 \begin_inset Flex CharStyle:Code
11363 status collapsed
11364
11365 \begin_layout Plain Layout
11366 Custom
11367 \end_layout
11368
11369 \end_inset
11370
11371 ): These can be used to define custom collapsable insets, similar to ERT,
11372  footnote, and the like.
11373 \end_layout
11374
11375 \begin_layout Itemize
11376 XML elements (
11377 \begin_inset Flex CharStyle:Code
11378 status collapsed
11379
11380 \begin_layout Plain Layout
11381 Element
11382 \end_layout
11383
11384 \end_inset
11385
11386 ): For use with DocBook classes.
11387 \end_layout
11388
11389 \begin_layout Standard
11390 The
11391 \begin_inset Flex CharStyle:Code
11392 status collapsed
11393
11394 \begin_layout Plain Layout
11395 InsetLayout
11396 \end_layout
11397
11398 \end_inset
11399
11400  definition starting line is of the form
11401 \end_layout
11402
11403 \begin_layout LyX-Code
11404 InsetLayout <Type> <Name>
11405 \end_layout
11406
11407 \begin_layout Standard
11408 where
11409 \begin_inset Flex CharStyle:Code
11410 status collapsed
11411
11412 \begin_layout Plain Layout
11413 <Type>
11414 \end_layout
11415
11416 \end_inset
11417
11418  can be
11419 \begin_inset Flex CharStyle:Code
11420 status collapsed
11421
11422 \begin_layout Plain Layout
11423 Algorithm
11424 \end_layout
11425
11426 \end_inset
11427
11428 ,
11429 \begin_inset Flex CharStyle:Code
11430 status collapsed
11431
11432 \begin_layout Plain Layout
11433 Branch
11434 \end_layout
11435
11436 \end_inset
11437
11438 ,
11439 \begin_inset Flex CharStyle:Code
11440 status collapsed
11441
11442 \begin_layout Plain Layout
11443 Box
11444 \end_layout
11445
11446 \end_inset
11447
11448 ,
11449 \begin_inset Flex CharStyle:Code
11450 status collapsed
11451
11452 \begin_layout Plain Layout
11453 ERT
11454 \end_layout
11455
11456 \end_inset
11457
11458 ,
11459 \begin_inset Flex CharStyle:Code
11460 status collapsed
11461
11462 \begin_layout Plain Layout
11463 Figure
11464 \end_layout
11465
11466 \end_inset
11467
11468 ,
11469 \begin_inset Flex CharStyle:Code
11470 status collapsed
11471
11472 \begin_layout Plain Layout
11473 Foot
11474 \end_layout
11475
11476 \end_inset
11477
11478 ,
11479 \begin_inset Flex CharStyle:Code
11480 status collapsed
11481
11482 \begin_layout Plain Layout
11483 Index
11484 \end_layout
11485
11486 \end_inset
11487
11488 ,
11489 \begin_inset Flex CharStyle:Code
11490 status collapsed
11491
11492 \begin_layout Plain Layout
11493 Listings
11494 \end_layout
11495
11496 \end_inset
11497
11498 ,
11499 \begin_inset Flex CharStyle:Code
11500 status collapsed
11501
11502 \begin_layout Plain Layout
11503 Marginal
11504 \end_layout
11505
11506 \end_inset
11507
11508 ,
11509 \begin_inset Flex CharStyle:Code
11510 status collapsed
11511
11512 \begin_layout Plain Layout
11513 Note:Comment
11514 \end_layout
11515
11516 \end_inset
11517
11518 ,
11519 \begin_inset Flex CharStyle:Code
11520 status collapsed
11521
11522 \begin_layout Plain Layout
11523 Note:Note
11524 \end_layout
11525
11526 \end_inset
11527
11528 ,
11529 \begin_inset Flex CharStyle:Code
11530 status collapsed
11531
11532 \begin_layout Plain Layout
11533 Note:GreyedOut
11534 \end_layout
11535
11536 \end_inset
11537
11538 ,
11539 \begin_inset Flex CharStyle:Code
11540 status collapsed
11541
11542 \begin_layout Plain Layout
11543 OptArg
11544 \end_layout
11545
11546 \end_inset
11547
11548 ,
11549 \begin_inset Flex CharStyle:Code
11550 status collapsed
11551
11552 \begin_layout Plain Layout
11553 Table
11554 \end_layout
11555
11556 \end_inset
11557
11558 ,
11559 \begin_inset Flex CharStyle:Code
11560 status collapsed
11561
11562 \begin_layout Plain Layout
11563 URL
11564 \end_layout
11565
11566 \end_inset
11567
11568 , or
11569 \begin_inset Flex CharStyle:Code
11570 status collapsed
11571
11572 \begin_layout Plain Layout
11573 Flex
11574 \end_layout
11575
11576 \end_inset
11577
11578 .
11579  If
11580 \begin_inset Flex CharStyle:Code
11581 status collapsed
11582
11583 \begin_layout Plain Layout
11584 <Type>
11585 \end_layout
11586
11587 \end_inset
11588
11589  is
11590 \begin_inset Flex CharStyle:Code
11591 status collapsed
11592
11593 \begin_layout Plain Layout
11594 Flex
11595 \end_layout
11596
11597 \end_inset
11598
11599 , then
11600 \begin_inset Flex CharStyle:Code
11601 status collapsed
11602
11603 \begin_layout Plain Layout
11604 <Name>
11605 \end_layout
11606
11607 \end_inset
11608
11609  should have the form
11610 \begin_inset Flex CharStyle:Code
11611 status collapsed
11612
11613 \begin_layout Plain Layout
11614 SubType:StyleName
11615 \end_layout
11616
11617 \end_inset
11618
11619 , where
11620 \begin_inset Flex CharStyle:Code
11621 status collapsed
11622
11623 \begin_layout Plain Layout
11624 SubType
11625 \end_layout
11626
11627 \end_inset
11628
11629  is either
11630 \begin_inset Flex CharStyle:Code
11631 status collapsed
11632
11633 \begin_layout Plain Layout
11634 CharStyle
11635 \end_layout
11636
11637 \end_inset
11638
11639 ,
11640 \begin_inset Flex CharStyle:Code
11641 status collapsed
11642
11643 \begin_layout Plain Layout
11644 Custom
11645 \end_layout
11646
11647 \end_inset
11648
11649 , or
11650 \begin_inset Flex CharStyle:Code
11651 status collapsed
11652
11653 \begin_layout Plain Layout
11654 Element
11655 \end_layout
11656
11657 \end_inset
11658
11659 , and
11660 \begin_inset Flex CharStyle:Code
11661 status collapsed
11662
11663 \begin_layout Plain Layout
11664 StyleName
11665 \end_layout
11666
11667 \end_inset
11668
11669  is any valid identifier.
11670
11671 \end_layout
11672
11673 \begin_layout Standard
11674 The following
11675 \begin_inset Flex CharStyle:Code
11676 status collapsed
11677
11678 \begin_layout Plain Layout
11679 InsetLayout
11680 \end_layout
11681
11682 \end_inset
11683
11684  section can contain the following entries:
11685 \end_layout
11686
11687 \begin_layout Description
11688 \begin_inset Flex CharStyle:Code
11689 status collapsed
11690
11691 \begin_layout Plain Layout
11692 BgColor
11693 \end_layout
11694
11695 \end_inset
11696
11697  The color for the inset's background.
11698  These valid colors are defined in
11699 \begin_inset Flex CharStyle:Code
11700 status collapsed
11701
11702 \begin_layout Plain Layout
11703 src/ColorCode.h
11704 \end_layout
11705
11706 \end_inset
11707
11708 .
11709 \end_layout
11710
11711 \begin_layout Description
11712 \begin_inset Flex CharStyle:Code
11713 status collapsed
11714
11715 \begin_layout Plain Layout
11716 CopyStyle
11717 \end_layout
11718
11719 \end_inset
11720
11721  As with paragraph styles (see page
11722 \begin_inset CommandInset ref
11723 LatexCommand ref
11724 reference "des:CopyStyle"
11725
11726 \end_inset
11727
11728 ).
11729 \end_layout
11730
11731 \begin_layout Description
11732 \begin_inset Flex CharStyle:Code
11733 status collapsed
11734
11735 \begin_layout Plain Layout
11736 Decoration
11737 \end_layout
11738
11739 \end_inset
11740
11741  can be
11742 \begin_inset Flex CharStyle:Code
11743 status collapsed
11744
11745 \begin_layout Plain Layout
11746 Classic
11747 \end_layout
11748
11749 \end_inset
11750
11751 ,
11752 \begin_inset Flex CharStyle:Code
11753 status collapsed
11754
11755 \begin_layout Plain Layout
11756 Minimalistic
11757 \end_layout
11758
11759 \end_inset
11760
11761 , or
11762 \begin_inset Flex CharStyle:Code
11763 status collapsed
11764
11765 \begin_layout Plain Layout
11766 Conglomerate
11767 \end_layout
11768
11769 \end_inset
11770
11771 , describing the rendering style used for the inset's frame and buttons.
11772  Footnotes generally use
11773 \begin_inset Flex CharStyle:Code
11774 status collapsed
11775
11776 \begin_layout Plain Layout
11777 Classic
11778 \end_layout
11779
11780 \end_inset
11781
11782 ; ERT insets generally use
11783 \begin_inset Flex CharStyle:Code
11784 status collapsed
11785
11786 \begin_layout Plain Layout
11787 Minimalistic
11788 \end_layout
11789
11790 \end_inset
11791
11792 ; and character styles use
11793 \begin_inset Flex CharStyle:Code
11794 status collapsed
11795
11796 \begin_layout Plain Layout
11797 Conglomerate
11798 \end_layout
11799
11800 \end_inset
11801
11802 .
11803 \end_layout
11804
11805 \begin_layout Description
11806 \begin_inset Flex CharStyle:Code
11807 status collapsed
11808
11809 \begin_layout Plain Layout
11810 Font
11811 \end_layout
11812
11813 \end_inset
11814
11815  The font used for both the text body
11816 \emph on
11817 and
11818 \emph default
11819  the label.
11820  See section
11821 \begin_inset space ~
11822 \end_inset
11823
11824
11825 \begin_inset CommandInset ref
11826 LatexCommand ref
11827 reference "sec:fonts"
11828
11829 \end_inset
11830
11831 .
11832  Note that defining this font automatically defines the
11833 \begin_inset Flex CharStyle:Code
11834 status collapsed
11835
11836 \begin_layout Plain Layout
11837 LabelFont
11838 \end_layout
11839
11840 \end_inset
11841
11842  to the same value, so define this first and define
11843 \begin_inset Flex CharStyle:Code
11844 status collapsed
11845
11846 \begin_layout Plain Layout
11847 LabelFont
11848 \end_layout
11849
11850 \end_inset
11851
11852  later if you want them to be different.
11853 \end_layout
11854
11855 \begin_layout Description
11856 \begin_inset Flex CharStyle:Code
11857 status collapsed
11858
11859 \begin_layout Plain Layout
11860 ForceLTR
11861 \end_layout
11862
11863 \end_inset
11864
11865  [[FIXME]]
11866 \end_layout
11867
11868 \begin_layout Description
11869 \begin_inset Flex CharStyle:Code
11870 status collapsed
11871
11872 \begin_layout Plain Layout
11873 FreeSpacing
11874 \end_layout
11875
11876 \end_inset
11877
11878  As with paragraph styles (see page
11879 \begin_inset CommandInset ref
11880 LatexCommand pageref
11881 reference "des:FreeSpacing"
11882
11883 \end_inset
11884
11885 ).
11886 \end_layout
11887
11888 \begin_layout Description
11889 \begin_inset Flex CharStyle:Code
11890 status collapsed
11891
11892 \begin_layout Plain Layout
11893 KeepEmpty
11894 \end_layout
11895
11896 \end_inset
11897
11898  As with paragraph styles (see page
11899 \begin_inset CommandInset ref
11900 LatexCommand pageref
11901 reference "des:KeepEmpty"
11902
11903 \end_inset
11904
11905 ).
11906 \end_layout
11907
11908 \begin_layout Description
11909 \begin_inset Flex CharStyle:Code
11910 status collapsed
11911
11912 \begin_layout Plain Layout
11913 LabelString
11914 \end_layout
11915
11916 \end_inset
11917
11918  What will be displayed on the button or elsewhere as the inset label.
11919  Some inset types (ERT and Branch) modify this label on the fly.
11920 \end_layout
11921
11922 \begin_layout Description
11923 \begin_inset Flex CharStyle:Code
11924 status collapsed
11925
11926 \begin_layout Plain Layout
11927 LabelFont
11928 \end_layout
11929
11930 \end_inset
11931
11932  The font used for the label.
11933  See section
11934 \begin_inset space ~
11935 \end_inset
11936
11937
11938 \begin_inset CommandInset ref
11939 LatexCommand ref
11940 reference "sec:fonts"
11941
11942 \end_inset
11943
11944 .
11945  Note that this definition can never appear before
11946 \begin_inset Flex CharStyle:Code
11947 status collapsed
11948
11949 \begin_layout Plain Layout
11950 Font
11951 \end_layout
11952
11953 \end_inset
11954
11955 , lest it be ineffective.
11956 \end_layout
11957
11958 \begin_layout Description
11959 \begin_inset Flex CharStyle:Code
11960 status collapsed
11961
11962 \begin_layout Plain Layout
11963 LatexName
11964 \end_layout
11965
11966 \end_inset
11967
11968  The name of the corresponding LaTeX stuff.
11969  Either the environment or command name.
11970 \end_layout
11971
11972 \begin_layout Description
11973 \begin_inset Flex CharStyle:Code
11974 status collapsed
11975
11976 \begin_layout Plain Layout
11977 LatexParam
11978 \end_layout
11979
11980 \end_inset
11981
11982  The optional parameter for the corresponding
11983 \begin_inset Flex CharStyle:Code
11984 status collapsed
11985
11986 \begin_layout Plain Layout
11987 LatexName
11988 \end_layout
11989
11990 \end_inset
11991
11992  stuff, including possible bracket pairs like
11993 \begin_inset Flex CharStyle:Code
11994 status collapsed
11995
11996 \begin_layout Plain Layout
11997 []
11998 \end_layout
11999
12000 \end_inset
12001
12002 .
12003  This parameter cannot be changed from within LyX.
12004 \end_layout
12005
12006 \begin_layout Description
12007 \begin_inset Flex CharStyle:Code
12008 status collapsed
12009
12010 \begin_layout Plain Layout
12011 LatexType
12012 \end_layout
12013
12014 \end_inset
12015
12016  As with paragraph styles (see page
12017 \begin_inset CommandInset ref
12018 LatexCommand pageref
12019 reference "des:LatexType"
12020
12021 \end_inset
12022
12023 ).
12024 \end_layout
12025
12026 \begin_layout Description
12027 \begin_inset Flex CharStyle:Code
12028 status collapsed
12029
12030 \begin_layout Plain Layout
12031 LyxType
12032 \end_layout
12033
12034 \end_inset
12035
12036  Can be
12037 \begin_inset Flex CharStyle:Code
12038 status collapsed
12039
12040 \begin_layout Plain Layout
12041 charstyle
12042 \end_layout
12043
12044 \end_inset
12045
12046 ,
12047 \begin_inset Flex CharStyle:Code
12048 status collapsed
12049
12050 \begin_layout Plain Layout
12051 custom
12052 \end_layout
12053
12054 \end_inset
12055
12056 ,
12057 \begin_inset Flex CharStyle:Code
12058 status collapsed
12059
12060 \begin_layout Plain Layout
12061 element
12062 \end_layout
12063
12064 \end_inset
12065
12066 ,
12067 \begin_inset Flex CharStyle:Code
12068 status collapsed
12069
12070 \begin_layout Plain Layout
12071 end
12072 \end_layout
12073
12074 \end_inset
12075
12076  (indicating a dummy definition ending definitions of charstyles etc.).
12077  This entry is only meaningful for Flex (user definable) insets.
12078 \end_layout
12079
12080 \begin_layout Description
12081 \begin_inset Flex CharStyle:Code
12082 status collapsed
12083
12084 \begin_layout Plain Layout
12085 NeedProtect
12086 \end_layout
12087
12088 \end_inset
12089
12090  [
12091 \begin_inset Flex CharStyle:Code
12092 status collapsed
12093
12094 \begin_layout Plain Layout
12095
12096 \emph on
12097 0
12098 \end_layout
12099
12100 \end_inset
12101
12102 ,
12103 \begin_inset Flex CharStyle:Code
12104 status collapsed
12105
12106 \begin_layout Plain Layout
12107 1
12108 \end_layout
12109
12110 \end_inset
12111
12112 ] Whether fragile commands in this layout should be
12113 \begin_inset Flex CharStyle:Code
12114 status collapsed
12115
12116 \begin_layout Plain Layout
12117
12118 \backslash
12119 protect
12120 \end_layout
12121
12122 \end_inset
12123
12124 'ed.
12125  (Note: This is
12126 \emph on
12127 not
12128 \emph default
12129  whether this command should itself be protected.)
12130 \end_layout
12131
12132 \begin_layout Description
12133 \begin_inset Flex CharStyle:Code
12134 status collapsed
12135
12136 \begin_layout Plain Layout
12137 Preamble
12138 \end_layout
12139
12140 \end_inset
12141
12142  As with paragraph styles (see page
12143 \begin_inset CommandInset ref
12144 LatexCommand pageref
12145 reference "des:Preamble"
12146
12147 \end_inset
12148
12149 ).
12150 \end_layout
12151
12152 \begin_layout Description
12153 \begin_inset Flex CharStyle:Code
12154 status collapsed
12155
12156 \begin_layout Plain Layout
12157 Requires
12158 \end_layout
12159
12160 \end_inset
12161
12162  [
12163 \begin_inset Flex CharStyle:Code
12164 status collapsed
12165
12166 \begin_layout Plain Layout
12167 string
12168 \end_layout
12169
12170 \end_inset
12171
12172 ] As with paragraph styles (see page
12173 \begin_inset CommandInset ref
12174 LatexCommand pageref
12175 reference "des:Requires"
12176
12177 \end_inset
12178
12179 ).
12180 \end_layout
12181
12182 \begin_layout Subsection
12183 Counters
12184 \end_layout
12185
12186 \begin_layout Standard
12187 \begin_inset CommandInset label
12188 LatexCommand label
12189 name "sec:counter"
12190
12191 \end_inset
12192
12193 Since version 1.3.0 of LyX, it is both possible and necessary to define the
12194  counters (
12195 \begin_inset Flex CharStyle:MenuItem
12196 status collapsed
12197
12198 \begin_layout Plain Layout
12199 chapter
12200 \end_layout
12201
12202 \end_inset
12203
12204 ,
12205 \begin_inset Flex CharStyle:MenuItem
12206 status collapsed
12207
12208 \begin_layout Plain Layout
12209 figure
12210 \end_layout
12211
12212 \end_inset
12213
12214 , \SpecialChar \ldots{}
12215 ) in the text class itself.
12216  The standard counters are defined in the file
12217 \begin_inset Flex CharStyle:Code
12218 status collapsed
12219
12220 \begin_layout Plain Layout
12221 stdcounters.inc
12222 \end_layout
12223
12224 \end_inset
12225
12226 , so you may have to do no more than add
12227 \end_layout
12228
12229 \begin_layout LyX-Code
12230 Input stdcounters.inc
12231 \end_layout
12232
12233 \begin_layout Standard
12234 to your layout file to get them to work.
12235  But if you want to define custom counters, then you can do so, using the
12236  following parameters:
12237 \end_layout
12238
12239 \begin_layout Description
12240 \begin_inset Flex CharStyle:Code
12241 status collapsed
12242
12243 \begin_layout Plain Layout
12244 LabelString [string=""]
12245 \end_layout
12246
12247 \end_inset
12248
12249  when this is defined, this string defines how the counter is displayed.
12250  Setting this value sets
12251 \begin_inset Flex CharStyle:Code
12252 status collapsed
12253
12254 \begin_layout Plain Layout
12255 LabelStringAppendix
12256 \end_layout
12257
12258 \end_inset
12259
12260  to the same value.
12261  The following special constructs can be used in the string:
12262 \end_layout
12263
12264 \begin_deeper
12265 \begin_layout Itemize
12266 \begin_inset Flex CharStyle:Code
12267 status collapsed
12268
12269 \begin_layout Plain Layout
12270
12271 \backslash
12272 thecounter
12273 \end_layout
12274
12275 \end_inset
12276
12277  will be replaced by the expansion of the
12278 \begin_inset Flex CharStyle:Code
12279 status collapsed
12280
12281 \begin_layout Plain Layout
12282 LabelString
12283 \end_layout
12284
12285 \end_inset
12286
12287  (or
12288 \begin_inset Flex CharStyle:Code
12289 status collapsed
12290
12291 \begin_layout Plain Layout
12292 LabelStringAppendix
12293 \end_layout
12294
12295 \end_inset
12296
12297 ) of the counter
12298 \begin_inset Flex CharStyle:Code
12299 status collapsed
12300
12301 \begin_layout Plain Layout
12302 counter
12303 \end_layout
12304
12305 \end_inset
12306
12307 .
12308
12309 \end_layout
12310
12311 \begin_layout Itemize
12312 counter values can be expressed using LaTeX-like macros
12313 \begin_inset Flex CharStyle:Code
12314 status collapsed
12315
12316 \begin_layout Plain Layout
12317
12318 \backslash
12319
12320 \emph on
12321 numbertype
12322 \emph default
12323 {
12324 \emph on
12325 counter
12326 \emph default
12327 }
12328 \end_layout
12329
12330 \end_inset
12331
12332 , where
12333 \begin_inset Flex CharStyle:Code
12334 status collapsed
12335
12336 \begin_layout Plain Layout
12337
12338 \emph on
12339 numbertype
12340 \end_layout
12341
12342 \end_inset
12343
12344  can be:
12345 \begin_inset Foot
12346 status collapsed
12347
12348 \begin_layout Plain Layout
12349
12350 \family roman
12351 \series medium
12352 \shape up
12353 \size normal
12354 \emph off
12355 \bar no
12356 \noun off
12357 \color none
12358 Actually, the situation is a bit more complicated: any
12359 \family default
12360 \series default
12361 \shape default
12362 \emph default
12363 \bar default
12364
12365 \size default
12366 \emph on
12367 \noun default
12368 \color inherit
12369 numbertype
12370 \family roman
12371 \series medium
12372 \shape up
12373 \size normal
12374 \emph off
12375 \bar no
12376 \noun off
12377  other than those descibed below will produce arabic numerals.
12378  It would not be surprising to see this change in the future.
12379 \end_layout
12380
12381 \end_inset
12382
12383
12384 \begin_inset Flex CharStyle:Code
12385 status collapsed
12386
12387 \begin_layout Plain Layout
12388 arabic
12389 \end_layout
12390
12391 \end_inset
12392
12393 : 1, 2, 3,\SpecialChar \ldots{}
12394 ;
12395 \begin_inset Flex CharStyle:Code
12396 status collapsed
12397
12398 \begin_layout Plain Layout
12399 alph
12400 \end_layout
12401
12402 \end_inset
12403
12404  for lower-case letters: a, b, c, \SpecialChar \ldots{}
12405 ;
12406 \begin_inset Flex CharStyle:Code
12407 status collapsed
12408
12409 \begin_layout Plain Layout
12410 Alph
12411 \end_layout
12412
12413 \end_inset
12414
12415  for upper-case letters: A, B, C, \SpecialChar \ldots{}
12416 ;
12417 \begin_inset Flex CharStyle:Code
12418 status collapsed
12419
12420 \begin_layout Plain Layout
12421 roman
12422 \end_layout
12423
12424 \end_inset
12425
12426  for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
12427 ;
12428 \begin_inset Flex CharStyle:Code
12429 status collapsed
12430
12431 \begin_layout Plain Layout
12432 Roman
12433 \end_layout
12434
12435 \end_inset
12436
12437  for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
12438 ;
12439 \begin_inset Flex CharStyle:Code
12440 status collapsed
12441
12442 \begin_layout Plain Layout
12443 hebrew
12444 \end_layout
12445
12446 \end_inset
12447
12448  for hebrew numerals.
12449 \end_layout
12450
12451 \end_deeper
12452 \begin_layout Standard
12453 If LabelString is not defined, a default value is constructed as follows:
12454  if the counter has a master counter
12455 \begin_inset Flex CharStyle:Code
12456 status collapsed
12457
12458 \begin_layout Plain Layout
12459 master
12460 \end_layout
12461
12462 \end_inset
12463
12464  (defined via
12465 \begin_inset Flex CharStyle:Code
12466 status collapsed
12467
12468 \begin_layout Plain Layout
12469 Within
12470 \end_layout
12471
12472 \end_inset
12473
12474 ), the string
12475 \begin_inset Flex CharStyle:Code
12476 status collapsed
12477
12478 \begin_layout Plain Layout
12479
12480 \backslash
12481 themaster.
12482 \backslash
12483 arabic{counter}
12484 \end_layout
12485
12486 \end_inset
12487
12488  is used; otherwise the string
12489 \begin_inset Flex CharStyle:Code
12490 status collapsed
12491
12492 \begin_layout Plain Layout
12493
12494 \backslash
12495 arabic{counter}
12496 \end_layout
12497
12498 \end_inset
12499
12500  is used.
12501 \end_layout
12502
12503 \begin_layout Description
12504 \begin_inset Flex CharStyle:Code
12505 status collapsed
12506
12507 \begin_layout Plain Layout
12508 LabelStringAppendix [string=""]
12509 \end_layout
12510
12511 \end_inset
12512
12513  Same as
12514 \begin_inset Flex CharStyle:Code
12515 status collapsed
12516
12517 \begin_layout Plain Layout
12518 LabelString
12519 \end_layout
12520
12521 \end_inset
12522
12523 .
12524 \end_layout
12525
12526 \begin_layout Description
12527 \begin_inset Flex CharStyle:Code
12528 status collapsed
12529
12530 \begin_layout Plain Layout
12531 Name
12532 \end_layout
12533
12534 \end_inset
12535
12536  [
12537 \begin_inset Flex CharStyle:Code
12538 status collapsed
12539
12540 \begin_layout Plain Layout
12541 string
12542 \end_layout
12543
12544 \end_inset
12545
12546 =
12547 \begin_inset Quotes erd
12548 \end_inset
12549
12550
12551 \begin_inset Quotes erd
12552 \end_inset
12553
12554 ] The name of the counter.
12555 \end_layout
12556
12557 \begin_layout Description
12558 \begin_inset Flex CharStyle:Code
12559 status collapsed
12560
12561 \begin_layout Plain Layout
12562 Within
12563 \end_layout
12564
12565 \end_inset
12566
12567  [
12568 \begin_inset Flex CharStyle:Code
12569 status collapsed
12570
12571 \begin_layout Plain Layout
12572 string
12573 \end_layout
12574
12575 \end_inset
12576
12577 =
12578 \begin_inset Quotes erd
12579 \end_inset
12580
12581
12582 \begin_inset Quotes erd
12583 \end_inset
12584
12585 ] If this is set to the name of another counter, the present counter will
12586  be reset everytime the other one is increased.
12587  For example,
12588 \begin_inset Flex CharStyle:Code
12589 status collapsed
12590
12591 \begin_layout Plain Layout
12592 subsection
12593 \end_layout
12594
12595 \end_inset
12596
12597  is numbered inside
12598 \begin_inset Flex CharStyle:Code
12599 status collapsed
12600
12601 \begin_layout Plain Layout
12602 section
12603 \end_layout
12604
12605 \end_inset
12606
12607 .
12608 \end_layout
12609
12610 \begin_layout Subsection
12611 Font description
12612 \end_layout
12613
12614 \begin_layout Standard
12615 \begin_inset CommandInset label
12616 LatexCommand label
12617 name "sec:fonts"
12618
12619 \end_inset
12620
12621 A font description looks like this:
12622 \end_layout
12623
12624 \begin_layout LyX-Code
12625 Font
12626 \family roman
12627 \emph on
12628 or
12629 \family default
12630 \emph default
12631  LabelFont
12632 \end_layout
12633
12634 \begin_layout LyX-Code
12635  ...
12636 \end_layout
12637
12638 \begin_layout LyX-Code
12639 EndFont
12640 \end_layout
12641
12642 \begin_layout Standard
12643 The following commands are available:
12644 \end_layout
12645
12646 \begin_layout Description
12647 \begin_inset Flex CharStyle:Code
12648 status collapsed
12649
12650 \begin_layout Plain Layout
12651 Color
12652 \end_layout
12653
12654 \end_inset
12655
12656  [
12657 \begin_inset Flex CharStyle:Code
12658 status collapsed
12659
12660 \begin_layout Plain Layout
12661
12662 \emph on
12663 none
12664 \end_layout
12665
12666 \end_inset
12667
12668 ,
12669 \begin_inset Flex CharStyle:Code
12670 status collapsed
12671
12672 \begin_layout Plain Layout
12673 black
12674 \end_layout
12675
12676 \end_inset
12677
12678 ,
12679 \begin_inset Flex CharStyle:Code
12680 status collapsed
12681
12682 \begin_layout Plain Layout
12683 white
12684 \end_layout
12685
12686 \end_inset
12687
12688 ,
12689 \begin_inset Flex CharStyle:Code
12690 status collapsed
12691
12692 \begin_layout Plain Layout
12693 red
12694 \end_layout
12695
12696 \end_inset
12697
12698 ,
12699 \begin_inset Flex CharStyle:Code
12700 status collapsed
12701
12702 \begin_layout Plain Layout
12703 green
12704 \end_layout
12705
12706 \end_inset
12707
12708 ,
12709 \begin_inset Flex CharStyle:Code
12710 status collapsed
12711
12712 \begin_layout Plain Layout
12713 blue
12714 \end_layout
12715
12716 \end_inset
12717
12718 ,
12719 \begin_inset Flex CharStyle:Code
12720 status collapsed
12721
12722 \begin_layout Plain Layout
12723 cyan
12724 \end_layout
12725
12726 \end_inset
12727
12728 ,
12729 \begin_inset Flex CharStyle:Code
12730 status collapsed
12731
12732 \begin_layout Plain Layout
12733 magenta
12734 \end_layout
12735
12736 \end_inset
12737
12738 ,
12739 \begin_inset Flex CharStyle:Code
12740 status collapsed
12741
12742 \begin_layout Plain Layout
12743 yellow
12744 \end_layout
12745
12746 \end_inset
12747
12748 ]
12749 \end_layout
12750
12751 \begin_layout Description
12752 \begin_inset Flex CharStyle:Code
12753 status collapsed
12754
12755 \begin_layout Plain Layout
12756 Family
12757 \end_layout
12758
12759 \end_inset
12760
12761  [
12762 \emph on
12763
12764 \begin_inset Flex CharStyle:Code
12765 status collapsed
12766
12767 \begin_layout Plain Layout
12768
12769 \emph on
12770 Roman
12771 \end_layout
12772
12773 \end_inset
12774
12775
12776 \emph default
12777 ,
12778 \begin_inset Flex CharStyle:Code
12779 status collapsed
12780
12781 \begin_layout Plain Layout
12782 Sans
12783 \end_layout
12784
12785 \end_inset
12786
12787 ,
12788 \begin_inset Flex CharStyle:Code
12789 status collapsed
12790
12791 \begin_layout Plain Layout
12792 Typewriter
12793 \end_layout
12794
12795 \end_inset
12796
12797 ]
12798 \end_layout
12799
12800 \begin_layout Description
12801 \begin_inset Flex CharStyle:Code
12802 status collapsed
12803
12804 \begin_layout Plain Layout
12805 Misc
12806 \end_layout
12807
12808 \end_inset
12809
12810  [
12811 \begin_inset Flex CharStyle:Code
12812 status collapsed
12813
12814 \begin_layout Plain Layout
12815 string
12816 \end_layout
12817
12818 \end_inset
12819
12820 ] Valid argument sare:
12821 \begin_inset Flex CharStyle:Code
12822 status collapsed
12823
12824 \begin_layout Plain Layout
12825 emph
12826 \end_layout
12827
12828 \end_inset
12829
12830 ,
12831 \begin_inset Flex CharStyle:Code
12832 status collapsed
12833
12834 \begin_layout Plain Layout
12835 noun
12836 \end_layout
12837
12838 \end_inset
12839
12840 ,
12841 \begin_inset Flex CharStyle:Code
12842 status collapsed
12843
12844 \begin_layout Plain Layout
12845 underbar
12846 \end_layout
12847
12848 \end_inset
12849
12850 ,
12851 \begin_inset Flex CharStyle:Code
12852 status collapsed
12853
12854 \begin_layout Plain Layout
12855 no_emph
12856 \end_layout
12857
12858 \end_inset
12859
12860 ,
12861 \begin_inset Flex CharStyle:Code
12862 status collapsed
12863
12864 \begin_layout Plain Layout
12865 no_noun
12866 \end_layout
12867
12868 \end_inset
12869
12870  and
12871 \begin_inset Flex CharStyle:Code
12872 status collapsed
12873
12874 \begin_layout Plain Layout
12875 no_bar
12876 \end_layout
12877
12878 \end_inset
12879
12880 .
12881  Each of these turns on or off the corresponding attribute.
12882 \end_layout
12883
12884 \begin_layout Description
12885 \begin_inset Flex CharStyle:Code
12886 status collapsed
12887
12888 \begin_layout Plain Layout
12889 Series
12890 \end_layout
12891
12892 \end_inset
12893
12894  [
12895 \emph on
12896
12897 \begin_inset Flex CharStyle:Code
12898 status collapsed
12899
12900 \begin_layout Plain Layout
12901
12902 \emph on
12903 Medium
12904 \end_layout
12905
12906 \end_inset
12907
12908
12909 \emph default
12910 ,
12911 \begin_inset Flex CharStyle:Code
12912 status collapsed
12913
12914 \begin_layout Plain Layout
12915 Bold
12916 \end_layout
12917
12918 \end_inset
12919
12920 ]
12921 \end_layout
12922
12923 \begin_layout Description
12924 \begin_inset Flex CharStyle:Code
12925 status collapsed
12926
12927 \begin_layout Plain Layout
12928 Shape
12929 \end_layout
12930
12931 \end_inset
12932
12933  [
12934 \emph on
12935
12936 \begin_inset Flex CharStyle:Code
12937 status collapsed
12938
12939 \begin_layout Plain Layout
12940
12941 \emph on
12942 Up
12943 \end_layout
12944
12945 \end_inset
12946
12947
12948 \emph default
12949 ,
12950 \begin_inset Flex CharStyle:Code
12951 status collapsed
12952
12953 \begin_layout Plain Layout
12954 Italic
12955 \end_layout
12956
12957 \end_inset
12958
12959 ,
12960 \begin_inset Flex CharStyle:Code
12961 status collapsed
12962
12963 \begin_layout Plain Layout
12964 SmallCaps
12965 \end_layout
12966
12967 \end_inset
12968
12969 ,
12970 \begin_inset Flex CharStyle:Code
12971 status collapsed
12972
12973 \begin_layout Plain Layout
12974 Slanted
12975 \end_layout
12976
12977 \end_inset
12978
12979 ]
12980 \end_layout
12981
12982 \begin_layout Description
12983 \begin_inset Flex CharStyle:Code
12984 status collapsed
12985
12986 \begin_layout Plain Layout
12987 Size
12988 \end_layout
12989
12990 \end_inset
12991
12992  [
12993 \begin_inset Flex CharStyle:Code
12994 status collapsed
12995
12996 \begin_layout Plain Layout
12997 tiny
12998 \end_layout
12999
13000 \end_inset
13001
13002 ,
13003 \begin_inset Flex CharStyle:Code
13004 status collapsed
13005
13006 \begin_layout Plain Layout
13007 small
13008 \end_layout
13009
13010 \end_inset
13011
13012 ,
13013 \begin_inset Flex CharStyle:Code
13014 status collapsed
13015
13016 \begin_layout Plain Layout
13017
13018 \emph on
13019 normal
13020 \end_layout
13021
13022 \end_inset
13023
13024 ,
13025 \begin_inset Flex CharStyle:Code
13026 status collapsed
13027
13028 \begin_layout Plain Layout
13029 large
13030 \end_layout
13031
13032 \end_inset
13033
13034 ,
13035 \begin_inset Flex CharStyle:Code
13036 status collapsed
13037
13038 \begin_layout Plain Layout
13039 larger
13040 \end_layout
13041
13042 \end_inset
13043
13044 ,
13045 \begin_inset Flex CharStyle:Code
13046 status collapsed
13047
13048 \begin_layout Plain Layout
13049 largest
13050 \end_layout
13051
13052 \end_inset
13053
13054 ,
13055 \begin_inset Flex CharStyle:Code
13056 status collapsed
13057
13058 \begin_layout Plain Layout
13059 huge
13060 \end_layout
13061
13062 \end_inset
13063
13064 ,
13065 \begin_inset Flex CharStyle:Code
13066 status collapsed
13067
13068 \begin_layout Plain Layout
13069 giant
13070 \end_layout
13071
13072 \end_inset
13073
13074 ]
13075 \end_layout
13076
13077 \begin_layout Subsection
13078 Upgrading old layout files
13079 \end_layout
13080
13081 \begin_layout Standard
13082 The file format of layout files changes from time to time, so old layout
13083  files need to be converted.
13084  This process has been automated since LyX 1.4.0: If LyX reads an old format
13085  layout file it will call the conversion tool
13086 \begin_inset Flex CharStyle:Code
13087 status collapsed
13088
13089 \begin_layout Plain Layout
13090 LyXDir/scripts/layout2layout.py
13091 \end_layout
13092
13093 \end_inset
13094
13095  and convert it to a temporary file in current format.
13096  The original file is left untouched.
13097  If you want to convert the layout file permanently, just call the converter
13098  by hand:
13099 \end_layout
13100
13101 \begin_layout LyX-Code
13102 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13103 \end_layout
13104
13105 \begin_layout Standard
13106 (You need to replace
13107 \begin_inset Flex CharStyle:Code
13108 status collapsed
13109
13110 \begin_layout Plain Layout
13111 $LyXDir
13112 \end_layout
13113
13114 \end_inset
13115
13116  with the name of your LyX system directory, unless you happen to have defined
13117  such an environment variable.) Then copy
13118 \begin_inset Flex CharStyle:Code
13119 status collapsed
13120
13121 \begin_layout Plain Layout
13122 myclassnew.layout
13123 \end_layout
13124
13125 \end_inset
13126
13127  to
13128 \begin_inset Flex CharStyle:Code
13129 status collapsed
13130
13131 \begin_layout Plain Layout
13132 UserDir/layouts/
13133 \end_layout
13134
13135 \end_inset
13136
13137 .
13138 \end_layout
13139
13140 \begin_layout Standard
13141 The automatic conversion only handles syntax changes.
13142  It cannot handle the case where the contents of included files was changed,
13143  so these will have to be converted separately.
13144 \end_layout
13145
13146 \begin_layout Section
13147 Creating Templates
13148 \begin_inset CommandInset label
13149 LatexCommand label
13150 name "sec:templates"
13151
13152 \end_inset
13153
13154
13155 \end_layout
13156
13157 \begin_layout Standard
13158 Templates are created just like usual documents.
13159  The only difference is that usual documents contain all possible settings,
13160  including the font scheme and the paper size.
13161  Usually a user doesn't want a template to overwrite his defaults in these
13162  cases.
13163  For that reason, the designer of a template should remove the corresponding
13164  commands like
13165 \begin_inset Flex CharStyle:Code
13166 status collapsed
13167
13168 \begin_layout Plain Layout
13169
13170 \backslash
13171 fontscheme
13172 \end_layout
13173
13174 \end_inset
13175
13176  or
13177 \begin_inset Flex CharStyle:Code
13178 status collapsed
13179
13180 \begin_layout Plain Layout
13181
13182 \backslash
13183 papersize
13184 \end_layout
13185
13186 \end_inset
13187
13188  from the template LyX file.
13189  This can be done with any simple text-editor, for example
13190 \begin_inset Flex CharStyle:Code
13191 status collapsed
13192
13193 \begin_layout Plain Layout
13194 vi
13195 \end_layout
13196
13197 \end_inset
13198
13199  or
13200 \begin_inset Flex CharStyle:Code
13201 status collapsed
13202
13203 \begin_layout Plain Layout
13204 xedit
13205 \end_layout
13206
13207 \end_inset
13208
13209 .
13210
13211 \end_layout
13212
13213 \begin_layout Standard
13214 Put the edited template files you create in
13215 \begin_inset Flex CharStyle:Code
13216 status collapsed
13217
13218 \begin_layout Plain Layout
13219 UserDir/templates/
13220 \end_layout
13221
13222 \end_inset
13223
13224 , copy the ones you use from the global template directory in
13225 \begin_inset Flex CharStyle:Code
13226 status collapsed
13227
13228 \begin_layout Plain Layout
13229 LyXDir/templates/
13230 \end_layout
13231
13232 \end_inset
13233
13234  to the same place, and redefine the template path in the
13235 \begin_inset Flex CharStyle:MenuItem
13236 status collapsed
13237
13238 \begin_layout Plain Layout
13239
13240 \bar under
13241 T
13242 \family sans
13243 \bar default
13244 ools
13245 \family default
13246 \SpecialChar \menuseparator
13247
13248 \bar under
13249 P
13250 \bar default
13251 references\SpecialChar \menuseparator
13252 Paths
13253 \end_layout
13254
13255 \end_inset
13256
13257  dialog.
13258 \end_layout
13259
13260 \begin_layout Standard
13261 Note that there is a template which has a particular meaning:
13262 \begin_inset Flex CharStyle:Code
13263 status collapsed
13264
13265 \begin_layout Plain Layout
13266 defaults.lyx
13267 \end_layout
13268
13269 \end_inset
13270
13271 .
13272  This template is loaded everytime you create a new document with
13273 \begin_inset Flex CharStyle:MenuItem
13274 status collapsed
13275
13276 \begin_layout Plain Layout
13277
13278 \bar under
13279 F
13280 \bar default
13281 ile
13282 \end_layout
13283
13284 \end_inset
13285
13286 \SpecialChar \menuseparator
13287
13288 \begin_inset Flex CharStyle:MenuItem
13289 status collapsed
13290
13291 \begin_layout Plain Layout
13292
13293 \bar under
13294 N
13295 \bar default
13296 ew
13297 \end_layout
13298
13299 \end_inset
13300
13301  in order to provide useful defaults.
13302  To create this template from inside LyX, all you have to do is to open
13303  a document with the correct settings, and use the
13304 \begin_inset Flex CharStyle:MenuItem
13305 status collapsed
13306
13307 \begin_layout Plain Layout
13308 Sa
13309 \bar under
13310 v
13311 \bar default
13312 e as Document Defaults
13313 \end_layout
13314
13315 \end_inset
13316
13317  button.
13318 \end_layout
13319
13320 \begin_layout Chapter
13321 Including External Material
13322 \end_layout
13323
13324 \begin_layout Standard
13325 The use of material from sources external to LyX is covered in detail in
13326  the
13327 \emph on
13328 Embedded Objects
13329 \emph default
13330  manual.
13331  This part of the manual covers what needs to happen behind the scenes for
13332  new sorts of material to be included.
13333 \end_layout
13334
13335 \begin_layout Section
13336 How does it work?
13337 \end_layout
13338
13339 \begin_layout Standard
13340 The external material feature is based on the concept of a
13341 \emph on
13342 template
13343 \emph default
13344 .
13345  A template is a specification of how LyX should interface with a certain
13346  kind of material.
13347  As bundled, LyX comes with predefined templates for Xfig figures, various
13348  raster format images, chess diagrams, and LilyPond music notation.
13349  You can check the actual list by using the menu
13350 \begin_inset Flex CharStyle:MenuItem
13351 status collapsed
13352
13353 \begin_layout Plain Layout
13354 Insert\SpecialChar \menuseparator
13355 File\SpecialChar \menuseparator
13356 External Material
13357 \end_layout
13358
13359 \end_inset
13360
13361 .
13362  Furthermore, it is possible to roll your own template to support a specific
13363  kind of material.
13364  Later we'll describe in more detail what is involved, and hopefully you
13365  will submit all the templates you create so we can include them in a later
13366  LyX version.
13367 \end_layout
13368
13369 \begin_layout Standard
13370 Another basic idea of the external material feature is to distinguish between
13371  the original file that serves as a base for final material and the produced
13372  file that is included in your exported or printed document.
13373  For example, consider the case of a figure produced with
13374 \begin_inset Flex CharStyle:Code
13375 status collapsed
13376
13377 \begin_layout Plain Layout
13378 Xfig
13379 \end_layout
13380
13381 \end_inset
13382
13383 .
13384  The Xfig application itself works on an original file with the
13385 \begin_inset Flex CharStyle:Code
13386 status collapsed
13387
13388 \begin_layout Plain Layout
13389 .fig
13390 \end_layout
13391
13392 \end_inset
13393
13394  extension.
13395  Within XFig, you create and change your figure, and when you are done,
13396  you save the
13397 \begin_inset Flex CharStyle:Code
13398 status collapsed
13399
13400 \begin_layout Plain Layout
13401 fig
13402 \end_layout
13403
13404 \end_inset
13405
13406 -file.
13407  When you want to include the figure in your document, you invoke
13408 \begin_inset Flex CharStyle:Code
13409 status collapsed
13410
13411 \begin_layout Plain Layout
13412 transfig
13413 \end_layout
13414
13415 \end_inset
13416
13417  in order to create a PostScript file that can readily be included in your
13418  LaTeX file.
13419  In this case, the
13420 \begin_inset Flex CharStyle:Code
13421 status collapsed
13422
13423 \begin_layout Plain Layout
13424 .fig
13425 \end_layout
13426
13427 \end_inset
13428
13429  file is the original file, and the PostScript file is the produced file.
13430 \end_layout
13431
13432 \begin_layout Standard
13433 This distinction is important in order to allow updating of the material
13434  while you are in the process of writing the document.
13435  Furthermore, it provides us with the flexibility that is needed to support
13436  multiple export formats.
13437  For instance, in the case of a plain text file, it is not exactly an award-winn
13438 ing idea to include the figure as raw PostScript®.
13439  Instead, you'd either prefer to just include a reference to the figure
13440  or try to invoke some graphics to Ascii converter to make the final result
13441  look similar to the real graphics.
13442  The external material management allows you to do this, because it is parameter
13443 ized on the different export formats that LyX supports.
13444 \end_layout
13445
13446 \begin_layout Standard
13447 Besides supporting the production of different products according to the
13448  exported format, it supports tight integration with editing and viewing
13449  applications.
13450  In the case of an XFig figure, you are able to invoke Xfig on the original
13451  file with a single click from within the external material dialog in LyX,
13452  and also preview the produced PostScript file with ghostview with another
13453  click.
13454  No more fiddling around with the command line and/or file browsers to locate
13455  and manipulate the original or produced files.
13456  In this way, you are finally able to take full advantage of the many different
13457  applications that are relevant to use when you write your documents, and
13458  ultimately be more productive.
13459 \end_layout
13460
13461 \begin_layout Section
13462 The external template configuration file
13463 \end_layout
13464
13465 \begin_layout Standard
13466 It is relatively easy to add custom external template definitions to LyX.
13467  However, be aware that doing this in an careless manner most probably
13468 \emph on
13469 will
13470 \emph default
13471  introduce an easily exploitable security hole.
13472  So before you do this, please read the discussion about security in section
13473
13474 \begin_inset CommandInset ref
13475 LatexCommand ref
13476 reference "sec:Security-discussion"
13477
13478 \end_inset
13479
13480 .
13481 \end_layout
13482
13483 \begin_layout Standard
13484 Having said that, we encourage you to submit any interesting templates that
13485  you create.
13486
13487 \end_layout
13488
13489 \begin_layout Standard
13490 The external templates are defined in the
13491 \begin_inset Flex CharStyle:Code
13492 status collapsed
13493
13494 \begin_layout Plain Layout
13495 LyXDir/lib/external_templates
13496 \end_layout
13497
13498 \end_inset
13499
13500  file.
13501  You can place your own version in
13502 \begin_inset Flex CharStyle:Code
13503 status collapsed
13504
13505 \begin_layout Plain Layout
13506 UserDir/external_templates
13507 \end_layout
13508
13509 \end_inset
13510
13511 .
13512 \end_layout
13513
13514 \begin_layout Standard
13515 A typical template looks like this:
13516 \end_layout
13517
13518 \begin_layout LyX-Code
13519 Template XFig
13520 \end_layout
13521
13522 \begin_layout LyX-Code
13523 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
13524 \end_layout
13525
13526 \begin_layout LyX-Code
13527 HelpText
13528 \end_layout
13529
13530 \begin_layout LyX-Code
13531 An XFig figure.
13532 \end_layout
13533
13534 \begin_layout LyX-Code
13535 HelpTextEnd
13536 \end_layout
13537
13538 \begin_layout LyX-Code
13539 InputFormat fig
13540 \end_layout
13541
13542 \begin_layout LyX-Code
13543 FileFilter "*.fig"
13544 \end_layout
13545
13546 \begin_layout LyX-Code
13547 AutomaticProduction true
13548 \end_layout
13549
13550 \begin_layout LyX-Code
13551 Transform Rotate
13552 \end_layout
13553
13554 \begin_layout LyX-Code
13555 Transform Resize
13556 \end_layout
13557
13558 \begin_layout LyX-Code
13559 Format LaTeX
13560 \end_layout
13561
13562 \begin_layout LyX-Code
13563 TransformCommand Rotate RotationLatexCommand
13564 \end_layout
13565
13566 \begin_layout LyX-Code
13567 TransformCommand Resize ResizeLatexCommand
13568 \end_layout
13569
13570 \begin_layout LyX-Code
13571 Product "$$RotateFront$$ResizeFront
13572 \end_layout
13573
13574 \begin_layout LyX-Code
13575
13576 \backslash
13577
13578 \backslash
13579 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
13580 \end_layout
13581
13582 \begin_layout LyX-Code
13583          $$ResizeBack$$RotateBack"
13584 \end_layout
13585
13586 \begin_layout LyX-Code
13587 UpdateFormat pstex
13588 \end_layout
13589
13590 \begin_layout LyX-Code
13591 UpdateResult "$$AbsPath$$Basename.pstex_t"
13592 \end_layout
13593
13594 \begin_layout LyX-Code
13595 Requirement "graphicx"
13596 \end_layout
13597
13598 \begin_layout LyX-Code
13599 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
13600 \end_layout
13601
13602 \begin_layout LyX-Code
13603 ReferencedFile latex "$$AbsPath$$Basename.eps"
13604 \end_layout
13605
13606 \begin_layout LyX-Code
13607 ReferencedFile dvi "$$AbsPath$$Basename.eps"
13608 \end_layout
13609
13610 \begin_layout LyX-Code
13611 FormatEnd
13612 \end_layout
13613
13614 \begin_layout LyX-Code
13615 Format PDFLaTeX
13616 \end_layout
13617
13618 \begin_layout LyX-Code
13619 TransformCommand Rotate RotationLatexCommand
13620 \end_layout
13621
13622 \begin_layout LyX-Code
13623 TransformCommand Resize ResizeLatexCommand
13624 \end_layout
13625
13626 \begin_layout LyX-Code
13627 Product "$$RotateFront$$ResizeFront
13628 \end_layout
13629
13630 \begin_layout LyX-Code
13631
13632 \backslash
13633
13634 \backslash
13635 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
13636 \end_layout
13637
13638 \begin_layout LyX-Code
13639          $$ResizeBack$$RotateBack"
13640 \end_layout
13641
13642 \begin_layout LyX-Code
13643 UpdateFormat pdftex
13644 \end_layout
13645
13646 \begin_layout LyX-Code
13647 UpdateResult "$$AbsPath$$Basename.pdftex_t"
13648 \end_layout
13649
13650 \begin_layout LyX-Code
13651 Requirement "graphicx"
13652 \end_layout
13653
13654 \begin_layout LyX-Code
13655 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
13656 \end_layout
13657
13658 \begin_layout LyX-Code
13659 ReferencedFile latex "$$AbsPath$$Basename.pdf"
13660 \end_layout
13661
13662 \begin_layout LyX-Code
13663 FormatEnd
13664 \end_layout
13665
13666 \begin_layout LyX-Code
13667 Format Ascii
13668 \end_layout
13669
13670 \begin_layout LyX-Code
13671 Product "$$Contents(
13672 \backslash
13673 "$$AbsPath$$Basename.asc
13674 \backslash
13675 ")"
13676 \end_layout
13677
13678 \begin_layout LyX-Code
13679 UpdateFormat asciixfig
13680 \end_layout
13681
13682 \begin_layout LyX-Code
13683 UpdateResult "$$AbsPath$$Basename.asc"
13684 \end_layout
13685
13686 \begin_layout LyX-Code
13687 FormatEnd
13688 \end_layout
13689
13690 \begin_layout LyX-Code
13691 Format DocBook
13692 \end_layout
13693
13694 \begin_layout LyX-Code
13695 Product "<graphic fileref=
13696 \backslash
13697 "$$AbsOrRelPathMaster$$Basename.eps
13698 \backslash
13699 ">
13700 \end_layout
13701
13702 \begin_layout LyX-Code
13703          </graphic>"
13704 \end_layout
13705
13706 \begin_layout LyX-Code
13707 UpdateFormat eps
13708 \end_layout
13709
13710 \begin_layout LyX-Code
13711 UpdateResult "$$AbsPath$$Basename.eps"
13712 \end_layout
13713
13714 \begin_layout LyX-Code
13715 ReferencedFile docbook "$$AbsPath$$Basename.eps"
13716 \end_layout
13717
13718 \begin_layout LyX-Code
13719 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
13720 \end_layout
13721
13722 \begin_layout LyX-Code
13723 FormatEnd
13724 \end_layout
13725
13726 \begin_layout LyX-Code
13727 Product "[XFig: $$FName]"
13728 \end_layout
13729
13730 \begin_layout LyX-Code
13731 FormatEnd
13732 \end_layout
13733
13734 \begin_layout LyX-Code
13735 TemplateEnd
13736 \end_layout
13737
13738 \begin_layout Standard
13739 As you can see, the template is enclosed in
13740 \begin_inset Flex CharStyle:Code
13741 status collapsed
13742
13743 \begin_layout Plain Layout
13744 Template
13745 \end_layout
13746
13747 \end_inset
13748
13749  \SpecialChar \ldots{}
13750
13751 \begin_inset Flex CharStyle:Code
13752 status collapsed
13753
13754 \begin_layout Plain Layout
13755 TemplateEnd
13756 \end_layout
13757
13758 \end_inset
13759
13760 .
13761  It contains a header specifying some general settings and, for each supported
13762  primary document file format, a section
13763 \begin_inset Flex CharStyle:Code
13764 status collapsed
13765
13766 \begin_layout Plain Layout
13767 Format
13768 \end_layout
13769
13770 \end_inset
13771
13772  \SpecialChar \ldots{}
13773
13774 \begin_inset Flex CharStyle:Code
13775 status collapsed
13776
13777 \begin_layout Plain Layout
13778 FormatEnd
13779 \end_layout
13780
13781 \end_inset
13782
13783 .
13784 \end_layout
13785
13786 \begin_layout Subsection
13787 The template header
13788 \end_layout
13789
13790 \begin_layout Description
13791 \begin_inset Flex CharStyle:Code
13792 status collapsed
13793
13794 \begin_layout Plain Layout
13795 AutomaticProduction
13796 \begin_inset space ~
13797 \end_inset
13798
13799 true|false
13800 \end_layout
13801
13802 \end_inset
13803
13804  Whether the file represented by the template must be generated by LyX.
13805  This command must occur exactly once.
13806 \end_layout
13807
13808 \begin_layout Description
13809 \begin_inset Flex CharStyle:Code
13810 status collapsed
13811
13812 \begin_layout Plain Layout
13813 FileFilter
13814 \begin_inset space ~
13815 \end_inset
13816
13817 <pattern>
13818 \end_layout
13819
13820 \end_inset
13821
13822  A glob pattern that is used in the file dialog to filter out the desired
13823  files.
13824  If there is more than one possible file extension (e.g.
13825 \begin_inset space ~
13826 \end_inset
13827
13828 tgif has
13829 \begin_inset Flex CharStyle:Code
13830 status collapsed
13831
13832 \begin_layout Plain Layout
13833 .obj
13834 \end_layout
13835
13836 \end_inset
13837
13838  and
13839 \begin_inset Flex CharStyle:Code
13840 status collapsed
13841
13842 \begin_layout Plain Layout
13843 .tgo
13844 \end_layout
13845
13846 \end_inset
13847
13848 ), use something like
13849 \begin_inset Flex CharStyle:Code
13850 status collapsed
13851
13852 \begin_layout Plain Layout
13853 "*.{obj,tgo}"
13854 \end_layout
13855
13856 \end_inset
13857
13858 .
13859  This command must occur exactly once.
13860 \end_layout
13861
13862 \begin_layout Description
13863 \begin_inset Flex CharStyle:Code
13864 status collapsed
13865
13866 \begin_layout Plain Layout
13867 GuiName
13868 \begin_inset space ~
13869 \end_inset
13870
13871 <guiname>
13872 \end_layout
13873
13874 \end_inset
13875
13876  The text that is displayed on the button.
13877  This command must occur exactly once.
13878 \end_layout
13879
13880 \begin_layout Description
13881 \begin_inset Flex CharStyle:Code
13882 status collapsed
13883
13884 \begin_layout Plain Layout
13885 HelpText
13886 \begin_inset space ~
13887 \end_inset
13888
13889 <text>
13890 \begin_inset space ~
13891 \end_inset
13892
13893 HelpTextEnd
13894 \end_layout
13895
13896 \end_inset
13897
13898  The help text that is used in the External dialog.
13899  Provide enough information to explain to the user just what the template
13900  can provide him with.
13901  This command must occur exactly once.
13902 \end_layout
13903
13904 \begin_layout Description
13905 \begin_inset Flex CharStyle:Code
13906 status collapsed
13907
13908 \begin_layout Plain Layout
13909 InputFormat
13910 \begin_inset space ~
13911 \end_inset
13912
13913 <format>
13914 \end_layout
13915
13916 \end_inset
13917
13918  The file format of the original file.
13919  This must be the name of a format that is known to LyX (see section
13920 \begin_inset CommandInset ref
13921 LatexCommand ref
13922 reference "sub:Formats"
13923
13924 \end_inset
13925
13926 ).
13927  Use
13928 \begin_inset Quotes eld
13929 \end_inset
13930
13931
13932 \begin_inset Flex CharStyle:Code
13933 status collapsed
13934
13935 \begin_layout Plain Layout
13936 *
13937 \end_layout
13938
13939 \end_inset
13940
13941
13942 \begin_inset Quotes erd
13943 \end_inset
13944
13945  if the template can handle original files of more than one format.
13946  LyX will attempt to interrogate the file itself in order to deduce its
13947  format in this case.
13948  This command must occur exactly once.
13949 \end_layout
13950
13951 \begin_layout Description
13952 \begin_inset Flex CharStyle:Code
13953 status collapsed
13954
13955 \begin_layout Plain Layout
13956 Template
13957 \begin_inset space ~
13958 \end_inset
13959
13960 <id>
13961 \end_layout
13962
13963 \end_inset
13964
13965  A unique name for the template.
13966  It must not contain substitution macros (see below).
13967 \end_layout
13968
13969 \begin_layout Description
13970 \begin_inset Flex CharStyle:Code
13971 status collapsed
13972
13973 \begin_layout Plain Layout
13974 Transform
13975 \begin_inset space ~
13976 \end_inset
13977
13978 Rotate|Resize|Clip|Extra
13979 \end_layout
13980
13981 \end_inset
13982
13983  This command specifies which transformations are supported by this template.
13984  It may occur zero or more times.
13985  This command enables the corresponding tabs in the external dialog.
13986  Each
13987 \begin_inset Flex CharStyle:Code
13988 status collapsed
13989
13990 \begin_layout Plain Layout
13991 Transform
13992 \end_layout
13993
13994 \end_inset
13995
13996  command must have either a corresponding
13997 \begin_inset Flex CharStyle:Code
13998 status collapsed
13999
14000 \begin_layout Plain Layout
14001 TransformCommand
14002 \end_layout
14003
14004 \end_inset
14005
14006  or a
14007 \begin_inset Flex CharStyle:Code
14008 status collapsed
14009
14010 \begin_layout Plain Layout
14011 TransformOption
14012 \end_layout
14013
14014 \end_inset
14015
14016  command in the
14017 \begin_inset Flex CharStyle:Code
14018 status collapsed
14019
14020 \begin_layout Plain Layout
14021 Format
14022 \end_layout
14023
14024 \end_inset
14025
14026  section.
14027  Otherwise the transformation will not be supported by that format.
14028 \end_layout
14029
14030 \begin_layout Subsection
14031 The Format section
14032 \end_layout
14033
14034 \begin_layout Description
14035 \begin_inset Flex CharStyle:Code
14036 status collapsed
14037
14038 \begin_layout Plain Layout
14039 Format
14040 \begin_inset space ~
14041 \end_inset
14042
14043 LaTeX|PDFLaTeX|PlainText|DocBook
14044 \end_layout
14045
14046 \end_inset
14047
14048  The primary document file format that this format definition is for.
14049  Not every template has a sensible representation in all document file formats.
14050  Please define nevertheless a
14051 \begin_inset Flex CharStyle:Code
14052 status collapsed
14053
14054 \begin_layout Plain Layout
14055 Format
14056 \end_layout
14057
14058 \end_inset
14059
14060  section for all formats.
14061  Use a dummy text when no representation is available.
14062  Then you can at least see a reference to the external material in the exported
14063  document.
14064 \end_layout
14065
14066 \begin_layout Description
14067 \begin_inset Flex CharStyle:Code
14068 status collapsed
14069
14070 \begin_layout Plain Layout
14071 Option
14072 \begin_inset space ~
14073 \end_inset
14074
14075 <name>
14076 \begin_inset space ~
14077 \end_inset
14078
14079 <value>
14080 \end_layout
14081
14082 \end_inset
14083
14084  This command defines an additional macro
14085 \begin_inset Flex CharStyle:Code
14086 status collapsed
14087
14088 \begin_layout Plain Layout
14089 $$<name>
14090 \end_layout
14091
14092 \end_inset
14093
14094  for substitution in
14095 \begin_inset Flex CharStyle:Code
14096 status collapsed
14097
14098 \begin_layout Plain Layout
14099 Product
14100 \end_layout
14101
14102 \end_inset
14103
14104 .
14105
14106 \begin_inset Flex CharStyle:Code
14107 status collapsed
14108
14109 \begin_layout Plain Layout
14110 <value>
14111 \end_layout
14112
14113 \end_inset
14114
14115  itself may contain substitution macros.
14116  The advantage over using
14117 \begin_inset Flex CharStyle:Code
14118 status collapsed
14119
14120 \begin_layout Plain Layout
14121 <value>
14122 \end_layout
14123
14124 \end_inset
14125
14126  directly in
14127 \begin_inset Flex CharStyle:Code
14128 status collapsed
14129
14130 \begin_layout Plain Layout
14131 Product
14132 \end_layout
14133
14134 \end_inset
14135
14136  is that the substituted value of
14137 \begin_inset Flex CharStyle:Code
14138 status collapsed
14139
14140 \begin_layout Plain Layout
14141 $$<name>
14142 \end_layout
14143
14144 \end_inset
14145
14146  is sanitized so that it is a valid optional argument in the document format.
14147  This command may occur zero or more times.
14148 \end_layout
14149
14150 \begin_layout Description
14151 \begin_inset Flex CharStyle:Code
14152 status collapsed
14153
14154 \begin_layout Plain Layout
14155 Product
14156 \begin_inset space ~
14157 \end_inset
14158
14159 <text>
14160 \end_layout
14161
14162 \end_inset
14163
14164  The text that is inserted in the exported document.
14165  This is actually the most important command and can be quite complex.
14166  This command must occur exactly once.
14167 \end_layout
14168
14169 \begin_layout Description
14170 \begin_inset Flex CharStyle:Code
14171 status collapsed
14172
14173 \begin_layout Plain Layout
14174 Preamble
14175 \begin_inset space ~
14176 \end_inset
14177
14178 <name>
14179 \end_layout
14180
14181 \end_inset
14182
14183  This command specifies a preamble snippet that will be included in the
14184  LaTeX preamble.
14185  It has to be defined using
14186 \begin_inset Flex CharStyle:Code
14187 status collapsed
14188
14189 \begin_layout Plain Layout
14190 PreambleDef
14191 \end_layout
14192
14193 \end_inset
14194
14195  \SpecialChar \ldots{}
14196
14197 \begin_inset Flex CharStyle:Code
14198 status collapsed
14199
14200 \begin_layout Plain Layout
14201 PreambleDefEnd
14202 \end_layout
14203
14204 \end_inset
14205
14206 .
14207  This command may occur zero or more times.
14208 \end_layout
14209
14210 \begin_layout Description
14211 \begin_inset Flex CharStyle:Code
14212 status collapsed
14213
14214 \begin_layout Plain Layout
14215 ReferencedFile
14216 \begin_inset space ~
14217 \end_inset
14218
14219 <format>
14220 \begin_inset space ~
14221 \end_inset
14222
14223 <filename>
14224 \end_layout
14225
14226 \end_inset
14227
14228  This command denotes files that are created by the conversion process and
14229  are needed for a particular export format.
14230  If the filename is relative, it is interpreted relative to the master document.
14231  This command may be given zero or more times.
14232 \end_layout
14233
14234 \begin_layout Description
14235 \begin_inset Flex CharStyle:Code
14236 status collapsed
14237
14238 \begin_layout Plain Layout
14239 Requirement
14240 \begin_inset space ~
14241 \end_inset
14242
14243 <package>
14244 \end_layout
14245
14246 \end_inset
14247
14248  The name of a required LaTeX package.
14249  The package is included via
14250 \begin_inset Flex CharStyle:Code
14251 status collapsed
14252
14253 \begin_layout Plain Layout
14254
14255 \backslash
14256 usepackage{}
14257 \end_layout
14258
14259 \end_inset
14260
14261  in the LaTeX preamble.
14262  This command may occur zero or more times.
14263 \end_layout
14264
14265 \begin_layout Description
14266 \begin_inset Flex CharStyle:Code
14267 status collapsed
14268
14269 \begin_layout Plain Layout
14270 TransformCommand
14271 \begin_inset space ~
14272 \end_inset
14273
14274 Rotate
14275 \begin_inset space ~
14276 \end_inset
14277
14278 RotationLatexCommand
14279 \end_layout
14280
14281 \end_inset
14282
14283  This command specifies that the built in LaTeX command should be used for
14284  rotation.
14285  This command may occur once or not at all.
14286 \end_layout
14287
14288 \begin_layout Description
14289 \begin_inset Flex CharStyle:Code
14290 status collapsed
14291
14292 \begin_layout Plain Layout
14293 TransformCommand
14294 \begin_inset space ~
14295 \end_inset
14296
14297 Resize
14298 \begin_inset space ~
14299 \end_inset
14300
14301 ResizeLatexCommand
14302 \end_layout
14303
14304 \end_inset
14305
14306  This command specifies that the built in LaTeX command should be used for
14307  resizing.
14308  This command may occur once or not at all.
14309 \end_layout
14310
14311 \begin_layout Description
14312 \begin_inset Flex CharStyle:Code
14313 status collapsed
14314
14315 \begin_layout Plain Layout
14316 TransformOption
14317 \begin_inset space ~
14318 \end_inset
14319
14320 Rotate
14321 \begin_inset space ~
14322 \end_inset
14323
14324 RotationLatexOption
14325 \end_layout
14326
14327 \end_inset
14328
14329  This command specifies that rotation is done via an optional argument.
14330  This command may occur once or not at all.
14331 \end_layout
14332
14333 \begin_layout Description
14334 \begin_inset Flex CharStyle:Code
14335 status collapsed
14336
14337 \begin_layout Plain Layout
14338 TransformOption
14339 \begin_inset space ~
14340 \end_inset
14341
14342 Resize
14343 \begin_inset space ~
14344 \end_inset
14345
14346 ResizeLatexOption
14347 \end_layout
14348
14349 \end_inset
14350
14351  This command specifies that resizing is done via an optional argument.
14352  This command may occur once or not at all.
14353 \end_layout
14354
14355 \begin_layout Description
14356 \begin_inset Flex CharStyle:Code
14357 status collapsed
14358
14359 \begin_layout Plain Layout
14360 TransformOption
14361 \begin_inset space ~
14362 \end_inset
14363
14364 Clip
14365 \begin_inset space ~
14366 \end_inset
14367
14368 ClipLatexOption
14369 \end_layout
14370
14371 \end_inset
14372
14373  This command specifies that clipping is done via an optional argument.
14374  This command may occur once or not at all.
14375 \end_layout
14376
14377 \begin_layout Description
14378 \begin_inset Flex CharStyle:Code
14379 status collapsed
14380
14381 \begin_layout Plain Layout
14382 TransformOption
14383 \begin_inset space ~
14384 \end_inset
14385
14386 Extra
14387 \begin_inset space ~
14388 \end_inset
14389
14390 ExtraLatexOption
14391 \end_layout
14392
14393 \end_inset
14394
14395  This command specifies that an extra optional argument is used.
14396  This command may occur once or not at all.
14397 \end_layout
14398
14399 \begin_layout Description
14400 \begin_inset Flex CharStyle:Code
14401 status collapsed
14402
14403 \begin_layout Plain Layout
14404 UpdateFormat
14405 \begin_inset space ~
14406 \end_inset
14407
14408 <format>
14409 \end_layout
14410
14411 \end_inset
14412
14413  The file format of the converted file.
14414  This must be the name of a format that is known to LyX (see the
14415 \begin_inset Flex CharStyle:MenuItem
14416 status collapsed
14417
14418 \begin_layout Plain Layout
14419
14420 \bar under
14421 T
14422 \bar default
14423 ools\SpecialChar \menuseparator
14424
14425 \bar under
14426 P
14427 \bar default
14428 references:Conversion
14429 \end_layout
14430
14431 \end_inset
14432
14433  dialog).
14434  This command must occur exactly once.
14435 \end_layout
14436
14437 \begin_layout Description
14438 \begin_inset Flex CharStyle:Code
14439 status collapsed
14440
14441 \begin_layout Plain Layout
14442 UpdateResult
14443 \begin_inset space ~
14444 \end_inset
14445
14446 <filename>
14447 \end_layout
14448
14449 \end_inset
14450
14451  The file name of the converted file.
14452  The file name must be absolute.
14453  This command must occur exactly once.
14454 \end_layout
14455
14456 \begin_layout Subsection
14457 Preamble definitions
14458 \end_layout
14459
14460 \begin_layout Standard
14461 The external template configuration file may contain additional preamble
14462  definitions enclosed by
14463 \begin_inset Flex CharStyle:Code
14464 status collapsed
14465
14466 \begin_layout Plain Layout
14467 PreambleDef
14468 \end_layout
14469
14470 \end_inset
14471
14472  \SpecialChar \ldots{}
14473
14474 \begin_inset Flex CharStyle:Code
14475 status collapsed
14476
14477 \begin_layout Plain Layout
14478 PreambleDefEnd
14479 \end_layout
14480
14481 \end_inset
14482
14483 .
14484  They can be used by the templates in the
14485 \begin_inset Flex CharStyle:Code
14486 status collapsed
14487
14488 \begin_layout Plain Layout
14489 Format
14490 \end_layout
14491
14492 \end_inset
14493
14494  section.
14495 \end_layout
14496
14497 \begin_layout Section
14498 The substitution mechanism
14499 \end_layout
14500
14501 \begin_layout Standard
14502 When the external material facility invokes an external program, it is done
14503  on the basis of a command defined in the template configuration file.
14504  These commands can contain various macros that are expanded before execution.
14505  Execution always take place in the directory of the containing document.
14506 \end_layout
14507
14508 \begin_layout Standard
14509 Also, whenever external material is to be displayed, the name will be produced
14510  by the substitution mechanism, and most other commands in the template
14511  definition support substitution as well.
14512 \end_layout
14513
14514 \begin_layout Standard
14515 The available macros are the following:
14516 \end_layout
14517
14518 \begin_layout Description
14519 \begin_inset Flex CharStyle:Code
14520 status collapsed
14521
14522 \begin_layout Plain Layout
14523 $$AbsOrRelPathMaster
14524 \end_layout
14525
14526 \end_inset
14527
14528  The file path, absolute or relative to the master LyX document.
14529 \end_layout
14530
14531 \begin_layout Description
14532 \begin_inset Flex CharStyle:Code
14533 status collapsed
14534
14535 \begin_layout Plain Layout
14536 $$AbsOrRelPathParent
14537 \end_layout
14538
14539 \end_inset
14540
14541  The file path, absolute or relative to the LyX document.
14542 \end_layout
14543
14544 \begin_layout Description
14545 \begin_inset Flex CharStyle:Code
14546 status collapsed
14547
14548 \begin_layout Plain Layout
14549 $$AbsPath
14550 \end_layout
14551
14552 \end_inset
14553
14554  The absolute file path.
14555 \end_layout
14556
14557 \begin_layout Description
14558 \begin_inset Flex CharStyle:Code
14559 status collapsed
14560
14561 \begin_layout Plain Layout
14562 $$Basename
14563 \end_layout
14564
14565 \end_inset
14566
14567  The filename without path and without the extension.
14568 \end_layout
14569
14570 \begin_layout Description
14571 \begin_inset Flex CharStyle:Code
14572 status collapsed
14573
14574 \begin_layout Plain Layout
14575 $$Contents(
14576 \begin_inset Quotes eld
14577 \end_inset
14578
14579 filename.ext
14580 \begin_inset Quotes erd
14581 \end_inset
14582
14583 )
14584 \end_layout
14585
14586 \end_inset
14587
14588  This macro will expand to the contents of the file with the name
14589 \begin_inset Flex CharStyle:Code
14590 status collapsed
14591
14592 \begin_layout Plain Layout
14593 filename.ext
14594 \end_layout
14595
14596 \end_inset
14597
14598 .
14599 \end_layout
14600
14601 \begin_layout Description
14602 \begin_inset Flex CharStyle:Code
14603 status collapsed
14604
14605 \begin_layout Plain Layout
14606 $$Extension
14607 \end_layout
14608
14609 \end_inset
14610
14611  The file extension (including the dot).
14612 \end_layout
14613
14614 \begin_layout Description
14615 \begin_inset Flex CharStyle:Code
14616 status collapsed
14617
14618 \begin_layout Plain Layout
14619 $$FName
14620 \end_layout
14621
14622 \end_inset
14623
14624  The filename of the file specified in the external material dialog.
14625  This is either an absolute name, or it is relative to the LyX document.
14626 \end_layout
14627
14628 \begin_layout Description
14629 \begin_inset Flex CharStyle:Code
14630 status collapsed
14631
14632 \begin_layout Plain Layout
14633 $$FPath
14634 \end_layout
14635
14636 \end_inset
14637
14638  The path part of
14639 \begin_inset Flex CharStyle:Code
14640 status collapsed
14641
14642 \begin_layout Plain Layout
14643 $$FName
14644 \end_layout
14645
14646 \end_inset
14647
14648  (absolute name or relative to the LyX document).
14649 \end_layout
14650
14651 \begin_layout Description
14652 \begin_inset Flex CharStyle:Code
14653 status collapsed
14654
14655 \begin_layout Plain Layout
14656 $$RelPathMaster
14657 \end_layout
14658
14659 \end_inset
14660
14661  The file path, relative to the master LyX document.
14662 \end_layout
14663
14664 \begin_layout Description
14665 \begin_inset Flex CharStyle:Code
14666 status collapsed
14667
14668 \begin_layout Plain Layout
14669 $$RelPathParent
14670 \end_layout
14671
14672 \end_inset
14673
14674  The file path, relative to the LyX document.
14675 \end_layout
14676
14677 \begin_layout Description
14678 \begin_inset Flex CharStyle:Code
14679 status collapsed
14680
14681 \begin_layout Plain Layout
14682 $$Sysdir
14683 \end_layout
14684
14685 \end_inset
14686
14687  This macro will expand to the absolute path of the system directory.
14688  This is typically used to point to the various helper scripts that are
14689  bundled with LyX.
14690 \end_layout
14691
14692 \begin_layout Description
14693 \begin_inset Flex CharStyle:Code
14694 status collapsed
14695
14696 \begin_layout Plain Layout
14697 $$Tempname
14698 \end_layout
14699
14700 \end_inset
14701
14702  A name and full path to a temporary file which will be automatically deleted
14703  whenever the containing document is closed, or the external material insertion
14704  deleted.
14705 \end_layout
14706
14707 \begin_layout Standard
14708 All path macros contain a trailing directory separator, so you can construct
14709  e.g.
14710  the absolute filename with
14711 \begin_inset Flex CharStyle:Code
14712 status collapsed
14713
14714 \begin_layout Plain Layout
14715 $$AbsPath$$Basename$$Extension
14716 \end_layout
14717
14718 \end_inset
14719
14720 .
14721 \end_layout
14722
14723 \begin_layout Standard
14724 The macros above are substituted in all commands unless otherwise noted.
14725  The command
14726 \begin_inset Flex CharStyle:Code
14727 status collapsed
14728
14729 \begin_layout Plain Layout
14730 Product
14731 \end_layout
14732
14733 \end_inset
14734
14735  supports additionally the following substitutions if they are enabled by
14736  the
14737 \begin_inset Flex CharStyle:Code
14738 status collapsed
14739
14740 \begin_layout Plain Layout
14741 Transform
14742 \end_layout
14743
14744 \end_inset
14745
14746  and
14747 \begin_inset Flex CharStyle:Code
14748 status collapsed
14749
14750 \begin_layout Plain Layout
14751 TransformCommand
14752 \end_layout
14753
14754 \end_inset
14755
14756  commands:
14757 \end_layout
14758
14759 \begin_layout Description
14760 \begin_inset Flex CharStyle:Code
14761 status collapsed
14762
14763 \begin_layout Plain Layout
14764 $$ResizeFront
14765 \end_layout
14766
14767 \end_inset
14768
14769  The front part of the resize command.
14770 \end_layout
14771
14772 \begin_layout Description
14773 \begin_inset Flex CharStyle:Code
14774 status collapsed
14775
14776 \begin_layout Plain Layout
14777 $$ResizeBack
14778 \end_layout
14779
14780 \end_inset
14781
14782  The back part of the resize command.
14783 \end_layout
14784
14785 \begin_layout Description
14786 \begin_inset Flex CharStyle:Code
14787 status collapsed
14788
14789 \begin_layout Plain Layout
14790 $$RotateFront
14791 \end_layout
14792
14793 \end_inset
14794
14795  The front part of the rotation command.
14796 \end_layout
14797
14798 \begin_layout Description
14799 \begin_inset Flex CharStyle:Code
14800 status collapsed
14801
14802 \begin_layout Plain Layout
14803 $$RotateBack
14804 \end_layout
14805
14806 \end_inset
14807
14808  The back part of the rotation command.
14809 \end_layout
14810
14811 \begin_layout Standard
14812 The value string of the
14813 \begin_inset Flex CharStyle:Code
14814 status collapsed
14815
14816 \begin_layout Plain Layout
14817 Option
14818 \end_layout
14819
14820 \end_inset
14821
14822  command supports additionally the following substitutions if they are enabled
14823  by the
14824 \begin_inset Flex CharStyle:Code
14825 status collapsed
14826
14827 \begin_layout Plain Layout
14828 Transform
14829 \end_layout
14830
14831 \end_inset
14832
14833  and
14834 \begin_inset Flex CharStyle:Code
14835 status collapsed
14836
14837 \begin_layout Plain Layout
14838 TransformOption
14839 \end_layout
14840
14841 \end_inset
14842
14843  commands:
14844 \end_layout
14845
14846 \begin_layout Description
14847 \begin_inset Flex CharStyle:Code
14848 status collapsed
14849
14850 \begin_layout Plain Layout
14851 $$Clip
14852 \end_layout
14853
14854 \end_inset
14855
14856  The clip option.
14857 \end_layout
14858
14859 \begin_layout Description
14860 \begin_inset Flex CharStyle:Code
14861 status collapsed
14862
14863 \begin_layout Plain Layout
14864 $$Extra
14865 \end_layout
14866
14867 \end_inset
14868
14869  The extra option.
14870 \end_layout
14871
14872 \begin_layout Description
14873 \begin_inset Flex CharStyle:Code
14874 status collapsed
14875
14876 \begin_layout Plain Layout
14877 $$Resize
14878 \end_layout
14879
14880 \end_inset
14881
14882  The resize option.
14883 \end_layout
14884
14885 \begin_layout Description
14886 \begin_inset Flex CharStyle:Code
14887 status collapsed
14888
14889 \begin_layout Plain Layout
14890 $$Rotate
14891 \end_layout
14892
14893 \end_inset
14894
14895  The rotation option.
14896 \end_layout
14897
14898 \begin_layout Standard
14899 You may ask why there are so many path macros.
14900  There are mainly two reasons:
14901 \end_layout
14902
14903 \begin_layout Enumerate
14904 Relative and absolute file names should remain relative or absolute, respectivel
14905 y.
14906  Users may have reasons to prefer either form.
14907  Relative names are useful for portable documents that should work on different
14908  machines, for example.
14909  Absolute names may be required by some programs.
14910 \end_layout
14911
14912 \begin_layout Enumerate
14913 LaTeX treats relative file names differently than LyX and other programs
14914  in nested included files.
14915  For LyX, a relative file name is always relative to the document that contains
14916  the file name.
14917  For LaTeX, it is always relative to the master document.
14918  These two definitions are identical if you have only one document, but
14919  differ if you have a master document that includes part documents.
14920  That means that relative filenames must be transformed when presented to
14921  LaTeX.
14922  Fortunately LyX does this automatically for you if you choose the right
14923  macros.
14924 \end_layout
14925
14926 \begin_layout Standard
14927 So which path macro should be used in new template definitions? The rule
14928  is not difficult:
14929 \end_layout
14930
14931 \begin_layout Itemize
14932 Use
14933 \begin_inset Flex CharStyle:Code
14934 status collapsed
14935
14936 \begin_layout Plain Layout
14937 $$AbsPath
14938 \end_layout
14939
14940 \end_inset
14941
14942  if an absolute path is required.
14943 \end_layout
14944
14945 \begin_layout Itemize
14946 Use
14947 \begin_inset Flex CharStyle:Code
14948 status collapsed
14949
14950 \begin_layout Plain Layout
14951 $$AbsOrRelPathMaster
14952 \end_layout
14953
14954 \end_inset
14955
14956  if the substituted string is some kind of LaTeX input.
14957 \end_layout
14958
14959 \begin_layout Itemize
14960 Else use
14961 \begin_inset Flex CharStyle:Code
14962 status collapsed
14963
14964 \begin_layout Plain Layout
14965 $$AbsOrRelPathParent
14966 \end_layout
14967
14968 \end_inset
14969
14970  in order to preserve the user's choice.
14971 \end_layout
14972
14973 \begin_layout Standard
14974 There are special cases where this rule does not work and e.g.
14975 \begin_inset space ~
14976 \end_inset
14977
14978 relative names are needed, but normally it will work just fine.
14979  One example for such a case is the command
14980 \begin_inset Flex CharStyle:Code
14981 status collapsed
14982
14983 \begin_layout Plain Layout
14984 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14985 \end_layout
14986
14987 \end_inset
14988
14989  in the XFig template above: We can't use the absolute name because the
14990  copier for
14991 \begin_inset Flex CharStyle:Code
14992 status collapsed
14993
14994 \begin_layout Plain Layout
14995 .pstex_t
14996 \end_layout
14997
14998 \end_inset
14999
15000  files needs the relative name in order to rewrite the file content.
15001 \end_layout
15002
15003 \begin_layout Section
15004 \begin_inset CommandInset label
15005 LatexCommand label
15006 name "sec:Security-discussion"
15007
15008 \end_inset
15009
15010 Security discussion
15011 \end_layout
15012
15013 \begin_layout Standard
15014 \begin_inset Note Note
15015 status collapsed
15016
15017 \begin_layout Plain Layout
15018 This section is outdated
15019 \end_layout
15020
15021 \end_inset
15022
15023 The external material feature interfaces with a lot of external programs
15024  and does so automatically, so we have to consider the security implications
15025  of this.
15026  In particular, since you have the option of including your own filenames
15027  and/or parameter strings and those are expanded into a command, it seems
15028  that it would be possible to create a malicious document which executes
15029  arbitrary commands when a user views or prints the document.
15030  This is something we definately want to avoid.
15031 \end_layout
15032
15033 \begin_layout Standard
15034 However, since the external program commands are specified in the template
15035  configuration file only, there are no security issues if LyX is properly
15036  configured with safe templates only.
15037  This is so because the external programs are invoked with the
15038 \begin_inset Flex CharStyle:Code
15039 status collapsed
15040
15041 \begin_layout Plain Layout
15042 execvp
15043 \end_layout
15044
15045 \end_inset
15046
15047 -system call rather than the
15048 \begin_inset Flex CharStyle:Code
15049 status collapsed
15050
15051 \begin_layout Plain Layout
15052 system
15053 \end_layout
15054
15055 \end_inset
15056
15057  system-call, so it's not possible to execute arbitrary commands from the
15058  filename or parameter section via the shell.
15059 \end_layout
15060
15061 \begin_layout Standard
15062 This also implies that you are restricted in what command strings you can
15063  use in the external material templates.
15064  In particular, pipes and redirection are not readily available.
15065  This has to be so if LyX should remain safe.
15066  If you want to use some of the shell features, you should write a safe
15067  script to do this in a controlled manner, and then invoke the script from
15068  the command string.
15069  In the
15070 \begin_inset Flex CharStyle:Code
15071 status collapsed
15072
15073 \begin_layout Plain Layout
15074 lib/scripts
15075 \end_layout
15076
15077 \end_inset
15078
15079  directory of the LyX installation, you can find a safe wrapper script
15080 \begin_inset Flex CharStyle:Code
15081 status collapsed
15082
15083 \begin_layout Plain Layout
15084 general_command_wrapper.py
15085 \end_layout
15086
15087 \end_inset
15088
15089  that supports redirection of input and output.
15090  That can serve as an example for how to write safe template scripts.
15091  For a more advanced example that uses
15092 \begin_inset Flex CharStyle:Code
15093 status collapsed
15094
15095 \begin_layout Plain Layout
15096 fork
15097 \end_layout
15098
15099 \end_inset
15100
15101  and friends, take a look at the
15102 \begin_inset Flex CharStyle:Code
15103 status collapsed
15104
15105 \begin_layout Plain Layout
15106 pic2ascii.py
15107 \end_layout
15108
15109 \end_inset
15110
15111  converter script.
15112 \end_layout
15113
15114 \begin_layout Standard
15115 It is possible to design a template that interacts directly with the shell,
15116  but since this would allow a malicious user to execute arbitrary commands
15117  by writing clever filenames and/or parameters, we generally recommend that
15118  you only use safe scripts that work with the
15119 \begin_inset Flex CharStyle:Code
15120 status collapsed
15121
15122 \begin_layout Plain Layout
15123 execvp
15124 \end_layout
15125
15126 \end_inset
15127
15128  system call in a controlled manner.
15129  Of course, for use in a controlled environment, it can be tempting to just
15130  fall back to use ordinary shell scripts.
15131  If you do so, be aware that you
15132 \emph on
15133 will
15134 \emph default
15135  provide an easily exploitable security hole in your system.
15136  Of course it stands to reason that such unsafe templates will never be
15137  included in the standard LyX distribution, although we do encourage people
15138  to submit new templates in the open source tradition.
15139  But LyX as shipped from the official distribution channels will never have
15140  unsafe templates.
15141 \end_layout
15142
15143 \begin_layout Standard
15144 Including external material provides a lot of power, and you have to be
15145  careful not to introduce security hazards with this power.
15146  A subtle error in a single line in an innocent looking script can open
15147  the door to huge security problems.
15148  So if you do not fully understand the issues, we recommend that you consult
15149  a knowledgable security professional or the LyX development team if you
15150  have any questions about whether a given template is safe or not.
15151  And do this before you use it in an uncontrolled environment.
15152 \end_layout
15153
15154 \begin_layout Chapter
15155 The LyX Server
15156 \end_layout
15157
15158 \begin_layout Section
15159 Introduction
15160 \end_layout
15161
15162 \begin_layout Standard
15163 The LyX server is a method implemented in LyX that will enable other programs
15164  to talk to LyX, invoke LyX commands, and retrieve information about the
15165  LyX internal state.
15166  This is only intended for advanced users, but they should find it useful.
15167  Please note that, at present,
15168 \emph on
15169 the server does not work on Windows
15170 \emph default
15171 .
15172 \begin_inset Foot
15173 status collapsed
15174
15175 \begin_layout Plain Layout
15176 There is no principled reason it cannot do so.
15177  But none of the developers on Windows® have yet implemented this functionality
15178  there.
15179 \end_layout
15180
15181 \end_inset
15182
15183
15184 \end_layout
15185
15186 \begin_layout Section
15187 Starting the LyX Server
15188 \end_layout
15189
15190 \begin_layout Standard
15191 The LyX server works through the use of a pair of named pipes.
15192  These are usually located in
15193 \begin_inset Flex CharStyle:Code
15194 status collapsed
15195
15196 \begin_layout Plain Layout
15197 UserDir
15198 \end_layout
15199
15200 \end_inset
15201
15202  and have the names
15203 \begin_inset Quotes eld
15204 \end_inset
15205
15206
15207 \begin_inset Flex CharStyle:Code
15208 status collapsed
15209
15210 \begin_layout Plain Layout
15211 .lyxpipe.in
15212 \end_layout
15213
15214 \end_inset
15215
15216
15217 \begin_inset Quotes erd
15218 \end_inset
15219
15220  and
15221 \begin_inset Quotes eld
15222 \end_inset
15223
15224
15225 \begin_inset Flex CharStyle:Code
15226 status collapsed
15227
15228 \begin_layout Plain Layout
15229 .lyxpipe.out
15230 \end_layout
15231
15232 \end_inset
15233
15234
15235 \begin_inset Quotes erd
15236 \end_inset
15237
15238 .
15239  External programs write into
15240 \begin_inset Flex CharStyle:Code
15241 status collapsed
15242
15243 \begin_layout Plain Layout
15244 .lyxpipe.in
15245 \end_layout
15246
15247 \end_inset
15248
15249  and read back data from
15250 \begin_inset Flex CharStyle:Code
15251 status collapsed
15252
15253 \begin_layout Plain Layout
15254 .lyxpipe.out
15255 \end_layout
15256
15257 \end_inset
15258
15259 .
15260  The stem of the pipe names can be defined in the
15261 \begin_inset Flex CharStyle:MenuItem
15262 status collapsed
15263
15264 \begin_layout Plain Layout
15265
15266 \bar under
15267 T
15268 \bar default
15269 ools\SpecialChar \menuseparator
15270
15271 \bar under
15272 P
15273 \bar default
15274 references
15275 \end_layout
15276
15277 \end_inset
15278
15279  dialog, for example
15280 \begin_inset Flex CharStyle:Code
15281 status collapsed
15282
15283 \begin_layout Plain Layout
15284 "/home/myhome/.lyxpipe"
15285 \end_layout
15286
15287 \end_inset
15288
15289 .
15290 \end_layout
15291
15292 \begin_layout Standard
15293 LyX will add the '
15294 \begin_inset Flex CharStyle:Code
15295 status collapsed
15296
15297 \begin_layout Plain Layout
15298 .in
15299 \end_layout
15300
15301 \end_inset
15302
15303 ' and '
15304 \begin_inset Flex CharStyle:Code
15305 status collapsed
15306
15307 \begin_layout Plain Layout
15308 .out
15309 \end_layout
15310
15311 \end_inset
15312
15313 ' to create the pipes.
15314  The above setting also has the effect of activating the LyX server.
15315  If one of the pipes already exists, LyX will assume that another LyX process
15316  is already running and will not start the server.
15317  To have several LyX processes with servers at the same time, you have to
15318  change the configuration between the start of the programs.
15319 \end_layout
15320
15321 \begin_layout Standard
15322 If you are developing a client program, you might find it useful to enable
15323  debugging information from the LyX server.
15324  Do this by starting LyX as lyx -dbg lyxserver.
15325 \end_layout
15326
15327 \begin_layout Standard
15328 Warning: if LyX crashes, it may not manage to remove the pipes; in this
15329  case you must remove them manually.
15330  If LyX starts and the pipes exist already, it will not start any server.
15331 \end_layout
15332
15333 \begin_layout Standard
15334 Other than this, there are a few points to consider:
15335 \end_layout
15336
15337 \begin_layout Itemize
15338 Both server and clients must run on UNIX or OS/2 machines.
15339  Communications between LyX on UNIX and clients on OS/2 or vice versa is
15340  not possible right now.
15341 \end_layout
15342
15343 \begin_layout Itemize
15344 On OS/2, only one client can connect to LyXServer at a time.
15345 \end_layout
15346
15347 \begin_layout Itemize
15348 On OS/2, clients must open inpipe with
15349 \begin_inset Flex CharStyle:Code
15350 status collapsed
15351
15352 \begin_layout Plain Layout
15353 O_WRONLY
15354 \end_layout
15355
15356 \end_inset
15357
15358
15359 \end_layout
15360
15361 \begin_layout Standard
15362 mode.
15363 \end_layout
15364
15365 \begin_layout Standard
15366 You can find a complete example client written in C in the source distribution
15367  as
15368 \begin_inset Flex CharStyle:Code
15369 status collapsed
15370
15371 \begin_layout Plain Layout
15372 development/lyxserver/server_monitor.c
15373 \end_layout
15374
15375 \end_inset
15376
15377 .
15378 \end_layout
15379
15380 \begin_layout Section
15381 Normal communication
15382 \end_layout
15383
15384 \begin_layout Standard
15385 To issue a LyX call, the client writes a line of ASCII text into the input
15386  pipe.
15387  This line has the following format:
15388 \end_layout
15389
15390 \begin_layout Quote
15391 LYXCMD:
15392 \emph on
15393 clientname
15394 \emph default
15395 :
15396 \emph on
15397 function
15398 \emph default
15399 :
15400 \emph on
15401 argument
15402 \end_layout
15403
15404 \begin_layout Description
15405
15406 \emph on
15407 clientname
15408 \emph default
15409  is a name that the client can choose arbitrarily.
15410  Its only use is that LyX will echo it if it sends an answer---so a client
15411  can dispatch results from different requesters.
15412 \end_layout
15413
15414 \begin_layout Description
15415
15416 \emph on
15417 function
15418 \emph default
15419  is the function you want LyX to perform.
15420  It is the same as the commands you'd use in the minibuffer.
15421 \end_layout
15422
15423 \begin_layout Description
15424
15425 \emph on
15426 argument
15427 \emph default
15428  is an optional argument which is meaningful only to some functions (for
15429  instance
15430 \begin_inset Quotes eld
15431 \end_inset
15432
15433 self-insert
15434 \begin_inset Quotes erd
15435 \end_inset
15436
15437  which will insert the argument as text at the cursor position.)
15438 \end_layout
15439
15440 \begin_layout Standard
15441 The answer from LyX will arrive in the output pipe and be of the form
15442 \end_layout
15443
15444 \begin_layout Quote
15445 INFO:
15446 \emph on
15447 clientname
15448 \emph default
15449 :
15450 \emph on
15451 function
15452 \emph default
15453 :
15454 \emph on
15455 data
15456 \end_layout
15457
15458 \begin_layout Standard
15459 where
15460 \emph on
15461 clientname
15462 \emph default
15463  and
15464 \emph on
15465 function
15466 \emph default
15467  are just echoed from the command request, while
15468 \emph on
15469 data
15470 \emph default
15471  is more or less useful information filled according to how the command
15472  execution worked out.
15473  Some commands will return information about the internal state of LyX,
15474  such as
15475 \begin_inset Quotes eld
15476 \end_inset
15477
15478 font-state
15479 \begin_inset Quotes erd
15480 \end_inset
15481
15482 , while other will return an empty data-response.
15483  This means that the command execution went fine.
15484 \end_layout
15485
15486 \begin_layout Standard
15487 In case of errors, the response from LyX will have this form
15488 \end_layout
15489
15490 \begin_layout Quote
15491 ERROR:
15492 \emph on
15493 clientname
15494 \emph default
15495 :
15496 \emph on
15497 function
15498 \emph default
15499 :
15500 \emph on
15501 error message
15502 \end_layout
15503
15504 \begin_layout Standard
15505 where the
15506 \emph on
15507 error message
15508 \emph default
15509  should contain an explanation of why the command failed.
15510 \end_layout
15511
15512 \begin_layout Standard
15513 Examples:
15514 \end_layout
15515
15516 \begin_layout LyX-Code
15517 echo "LYXCMD:test:beginning-of-buffer:" >~/.lyxpipe.in
15518 \end_layout
15519
15520 \begin_layout LyX-Code
15521 echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in
15522 \begin_inset Newline newline
15523 \end_inset
15524
15525 read a <~/.lyxpipe.out
15526 \begin_inset Newline newline
15527 \end_inset
15528
15529 echo $a
15530 \end_layout
15531
15532 \begin_layout Section
15533 Notification
15534 \end_layout
15535
15536 \begin_layout Standard
15537 LyX can notify clients of events going on asynchronously.
15538  Currently it will only do this if the user binds a key sequence with the
15539  function
15540 \begin_inset Quotes eld
15541 \end_inset
15542
15543 notify
15544 \begin_inset Quotes erd
15545 \end_inset
15546
15547 .
15548  The format of the string LyX sends is as follows:
15549 \end_layout
15550
15551 \begin_layout Quote
15552 \begin_inset Flex CharStyle:Code
15553 status collapsed
15554
15555 \begin_layout Plain Layout
15556 NOTIFY:
15557 \end_layout
15558
15559 \end_inset
15560
15561
15562 \emph on
15563 key-sequence
15564 \end_layout
15565
15566 \begin_layout Standard
15567 where
15568 \emph on
15569 key-sequence
15570 \emph default
15571  is the printed representation of the key sequence that was actually typed
15572  by the user.
15573 \end_layout
15574
15575 \begin_layout Standard
15576 This mechanism can be used to extend LyX's command set and implement macros:
15577  bind some key sequence to
15578 \begin_inset Quotes eld
15579 \end_inset
15580
15581 notify
15582 \begin_inset Quotes erd
15583 \end_inset
15584
15585 , start a client that listens on the out pipe, dispatches the command according
15586  to the sequence and starts a function that may use LyX calls and LyX requests
15587  to issue a command or a series of commands to LyX.
15588 \end_layout
15589
15590 \begin_layout Section
15591 The simple LyX Server Protocol
15592 \end_layout
15593
15594 \begin_layout Standard
15595 LyX implements a simple protocol that can be used for session management.
15596  All messages are of the form
15597 \end_layout
15598
15599 \begin_layout Quote
15600 LYXSRV:
15601 \emph on
15602 clientname
15603 \emph default
15604 :
15605 \emph on
15606 protocol message
15607 \end_layout
15608
15609 \begin_layout Standard
15610 where
15611 \emph on
15612 protocol message
15613 \emph default
15614  can be
15615 \begin_inset Quotes eld
15616 \end_inset
15617
15618 hello
15619 \begin_inset Quotes erd
15620 \end_inset
15621
15622  or
15623 \begin_inset Quotes eld
15624 \end_inset
15625
15626 bye
15627 \begin_inset Quotes erd
15628 \end_inset
15629
15630 .
15631  If
15632 \begin_inset Quotes eld
15633 \end_inset
15634
15635 hello
15636 \begin_inset Quotes erd
15637 \end_inset
15638
15639  is received from a client, LyX will report back to inform the client that
15640  it's listening to it's messages, while
15641 \begin_inset Quotes eld
15642 \end_inset
15643
15644 bye
15645 \begin_inset Quotes erd
15646 \end_inset
15647
15648  sent from LyX will inform clients that LyX is closing.
15649 \end_layout
15650
15651 \end_body
15652 \end_document