lib/doc/Development.lyx

   1 #LyX 2.2 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 508
   3 \begin_document
   4 \begin_header
   5 \save_transient_properties true
   6 \origin /systemlyxdir/doc/
   7 \textclass scrartcl
   8 \options BCOR8mm,captions=tableheading
   9 \use_default_options false
  10 \begin_modules
  11 logicalmkup
  12 \end_modules
  13 \maintain_unincluded_children false
  14 \language english
  15 \language_package default
  16 \inputencoding auto
  17 \fontencoding global
  18 \font_roman "lmodern" "default"
  19 \font_sans "lmss" "default"
  20 \font_typewriter "lmtt" "default"
  21 \font_math "auto" "auto"
  22 \font_default_family default
  23 \use_non_tex_fonts false
  24 \font_sc false
  25 \font_osf false
  26 \font_sf_scale 100 100
  27 \font_tt_scale 100 100
  28 \graphics default
  29 \default_output_format pdf2
  30 \output_sync 1
  31 \bibtex_command default
  32 \index_command default
  33 \paperfontsize 12
  34 \spacing single
  35 \use_hyperref true
  36 \pdf_title "LyX's Development manual"
  37 \pdf_author "LyX Team"
  38 \pdf_subject "LyX's development documentation"
  39 \pdf_keywords "LyX, Documentation, Development"
  40 \pdf_bookmarks true
  41 \pdf_bookmarksnumbered true
  42 \pdf_bookmarksopen true
  43 \pdf_bookmarksopenlevel 1
  44 \pdf_breaklinks false
  45 \pdf_pdfborder false
  46 \pdf_colorlinks true
  47 \pdf_backref false
  48 \pdf_pdfusetitle false
  49 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
  50 \papersize a4paper
  51 \use_geometry false
  52 \use_package amsmath 1
  53 \use_package amssymb 1
  54 \use_package cancel 0
  55 \use_package esint 0
  56 \use_package mathdots 1
  57 \use_package mathtools 0
  58 \use_package mhchem 1
  59 \use_package stackrel 0
  60 \use_package stmaryrd 0
  61 \use_package undertilde 0
  62 \cite_engine basic
  63 \cite_engine_type default
  64 \biblio_style plain
  65 \use_bibtopic false
  66 \use_indices false
  67 \paperorientation portrait
  68 \suppress_date false
  69 \justification true
  70 \use_refstyle 0
  71 \notefontcolor #0000ff
  72 \index Index
  73 \shortcut idx
  74 \color #008000
  75 \end_index
  76 \secnumdepth 4
  77 \tocdepth 4
  78 \paragraph_separation indent
  79 \paragraph_indentation default
  80 \quotes_language english
  81 \papercolumns 1
  82 \papersides 2
  83 \paperpagestyle headings
  84 \tracking_changes true
  85 \output_changes false
  86 \html_math_output 0
  87 \html_css_as_file 0
  88 \html_be_strict true
  89 \author 34634807 "Jean-Pierre"
  90 \end_header
  91
  92 \begin_body
  93
  94 \begin_layout Title
  95 Developing \SpecialChar LyX
  96
  97 \end_layout
  98
  99 \begin_layout Subtitle
 100 Version 2.2.x
 101 \end_layout
 102
 103 \begin_layout Author
 104 by the \SpecialChar LyX
 105  Team
 106 \begin_inset Foot
 107 status collapsed
 108
 109 \begin_layout Plain Layout
 110 \noindent
 111 If you have comments or error corrections, please send them to the \SpecialChar LyX
 112  Documentatio
 113 n mailing list,
 114 \begin_inset Flex Code
 115 status collapsed
 116
 117 \begin_layout Plain Layout
 118 \noindent
 119 <lyx-docs@lists.lyx.org>
 120 \end_layout
 121
 122 \end_inset
 123
 124 .
 125 \end_layout
 126
 127 \end_inset
 128
 129
 130 \end_layout
 131
 132 \begin_layout Standard
 133 \begin_inset CommandInset toc
 134 LatexCommand tableofcontents
 135
 136 \end_inset
 137
 138
 139 \end_layout
 140
 141 \begin_layout Section
 142 Introduction
 143 \end_layout
 144
 145 \begin_layout Standard
 146 This manual documents some aspects of \SpecialChar LyX
 147  development.
 148  It is currently rather incomplete, but will hopefully be extended in the
 149  future.
 150  Meanwhile, additional information can be found in the
 151 \begin_inset Flex Code
 152 status collapsed
 153
 154 \begin_layout Plain Layout
 155 development
 156 \end_layout
 157
 158 \end_inset
 159
 160  subfolder of the \SpecialChar LyX
 161  source code distribution.
 162  This document is not translated, since the development language of \SpecialChar LyX
 163  is
 164  English.
 165  If you just want to use \SpecialChar LyX
 166 , then you don't need to read this manual.
 167  However, if you want to learn more about how \SpecialChar LyX
 168  is developed, or even want
 169  to participate in \SpecialChar LyX
 170  development, you may find some interesting information
 171  here.
 172 \end_layout
 173
 174 \begin_layout Section
 175 File formats
 176 \end_layout
 177
 178 \begin_layout Standard
 179 \SpecialChar LyX
 180  uses several custom file formats for configuration files and documents.
 181  This chapter contains some background concerning these file formats.
 182  Several file formats are also described in detail in the regular user documenta
 183 tion.
 184 \end_layout
 185
 186 \begin_layout Subsection
 187 File Format Numbers
 188 \end_layout
 189
 190 \begin_layout Subsection
 191 When is an update of the .lyx file format number needed?
 192 \begin_inset CommandInset label
 193 LatexCommand label
 194 name "sec:When-is-an"
 195
 196 \end_inset
 197
 198
 199 \end_layout
 200
 201 \begin_layout Standard
 202 When you are working on a new feature you may ask yourself whether it needs
 203  an update of the .lyx file format number.
 204  Whether an update is needed or not is not always obvious.
 205  Rule of thumb:
 206 \end_layout
 207
 208 \begin_layout Quote
 209 Whenever there is the danger that a previous version of LyX cannot open
 210  a file using the new feature, a file format update is needed.
 211 \end_layout
 212
 213 \begin_layout Standard
 214 The file format change allows lyx2lyx rules to implement backwards compatibility.
 215  Below you can find a list of reasons for file format updates with explanations:
 216 \end_layout
 217
 218 \begin_layout Description
 219 New
 220 \begin_inset space ~
 221 \end_inset
 222
 223 document
 224 \begin_inset space ~
 225 \end_inset
 226
 227 setting Whenever you introduce a new setting that is stored in the document
 228  header, a file format update is needed.
 229 \end_layout
 230
 231 \begin_layout Description
 232 Removed
 233 \begin_inset space ~
 234 \end_inset
 235
 236 document
 237 \begin_inset space ~
 238 \end_inset
 239
 240 setting If a certain setting becomes obsolete and gets removed, a file format
 241  update is needed.
 242 \end_layout
 243
 244 \begin_layout Description
 245 New
 246 \begin_inset space ~
 247 \end_inset
 248
 249 valid
 250 \begin_inset space ~
 251 \end_inset
 252
 253 value
 254 \begin_inset space ~
 255 \end_inset
 256
 257 for
 258 \begin_inset space ~
 259 \end_inset
 260
 261 an
 262 \begin_inset space ~
 263 \end_inset
 264
 265 existing
 266 \begin_inset space ~
 267 \end_inset
 268
 269 setting, e.
 270 \begin_inset space \thinspace{}
 271 \end_inset
 272
 273 g.
 274 \end_layout
 275
 276 \begin_deeper
 277 \begin_layout Description
 278 \paragraph_spacing single
 279 Automatically
 280 \begin_inset space ~
 281 \end_inset
 282
 283 loaded
 284 \begin_inset space ~
 285 \end_inset
 286
 287 math
 288 \begin_inset space ~
 289 \end_inset
 290
 291 package The reason for this is that there is no true ERT inset for math
 292  formulas: Each command is parsed, and if a user happens to define a local
 293  command with the same name as a command that triggers an automatic load
 294  of a package, they need to be able to switch off the automatic loading
 295  of that package.
 296  This switch is stored by the
 297 \begin_inset Flex Code
 298 status collapsed
 299
 300 \begin_layout Plain Layout
 301 use_package
 302 \end_layout
 303
 304 \end_inset
 305
 306  header setting.
 307 \end_layout
 308
 309 \begin_layout Description
 310 New
 311 \begin_inset space ~
 312 \end_inset
 313
 314 language that is stored in
 315 \begin_inset Flex Code
 316 status collapsed
 317
 318 \begin_layout Plain Layout
 319
 320 \backslash
 321 language
 322 \end_layout
 323
 324 \end_inset
 325
 326 .
 327
 328 \begin_inset Note Note
 329 status collapsed
 330
 331 \begin_layout Plain Layout
 332 This requirement is under discussion.
 333 \end_layout
 334
 335 \end_inset
 336
 337
 338 \end_layout
 339
 340 \end_deeper
 341 \begin_layout Description
 342 New
 343 \begin_inset space ~
 344 \end_inset
 345
 346 inset Of course a new inset requires a file format update.
 347 \end_layout
 348
 349 \begin_layout Description
 350 New
 351 \begin_inset space ~
 352 \end_inset
 353
 354 style If a new style or inset layout is added to any layout file or module
 355  shipped with \SpecialChar LyX
 356 , then a new file format is needed in the master (development)
 357  branch.
 358  It is possible to backport new styles to the stable version without a file
 359  format change.
 360  See
 361 \begin_inset CommandInset ref
 362 LatexCommand ref
 363 reference "subsec:Backporting-new-styles"
 364
 365 \end_inset
 366
 367  for more information.
 368 \end_layout
 369
 370 \begin_layout Description
 371 Removed
 372 \begin_inset space ~
 373 \end_inset
 374
 375 style If a style or inset layout is removed in any layout file or module
 376  shipped with \SpecialChar LyX
 377 , a new file format is required.
 378 \end_layout
 379
 380 \begin_layout Standard
 381 However,
 382 \series bold
 383 new
 384 \series default
 385  layouts and modules do
 386 \series bold
 387 not
 388 \series default
 389  require a file format update (changed 03/16, see
 390 \begin_inset CommandInset ref
 391 LatexCommand ref
 392 reference "subsec:New-layouts"
 393
 394 \end_inset
 395
 396 ).
 397
 398 \end_layout
 399
 400 \begin_layout Standard
 401 If you are still unsure, please ask on the development list.
 402 \end_layout
 403
 404 \begin_layout Subsection
 405 \begin_inset CommandInset label
 406 LatexCommand label
 407 name "subsec:update_lyx_files"
 408
 409 \end_inset
 410
 411 How to update the file format number of .lyx files
 412 \end_layout
 413
 414 \begin_layout Standard
 415 Once you come to the conclusion that a file format update is needed, you
 416  should use the following procedure to perform the update:
 417 \end_layout
 418
 419 \begin_layout Enumerate
 420 Implement and test the new feature, including the reading and writing of
 421  .lyx files.
 422  Note that any file produced at this stage does not use a valid format,
 423  so do not use this version of \SpecialChar LyX
 424  for working on any important documents.
 425 \end_layout
 426
 427 \begin_layout Enumerate
 428 \begin_inset CommandInset label
 429 LatexCommand label
 430 name "enu:Describe_format"
 431
 432 \end_inset
 433
 434 Describe the new format in
 435 \begin_inset Flex Code
 436 status collapsed
 437
 438 \begin_layout Plain Layout
 439 development/FORMAT
 440 \end_layout
 441
 442 \end_inset
 443
 444 .
 445 \end_layout
 446
 447 \begin_layout Enumerate
 448 Update the \SpecialChar LyX
 449  file format number in
 450 \begin_inset Flex Code
 451 status collapsed
 452
 453 \begin_layout Plain Layout
 454 src/version.h
 455 \end_layout
 456
 457 \end_inset
 458
 459 .
 460 \end_layout
 461
 462 \begin_layout Enumerate
 463 Update the range of file formats in the array
 464 \begin_inset Flex Code
 465 status collapsed
 466
 467 \begin_layout Plain Layout
 468 format_relation
 469 \end_layout
 470
 471 \end_inset
 472
 473  in
 474 \begin_inset Flex Code
 475 status collapsed
 476
 477 \begin_layout Plain Layout
 478 lib/lyx2lyx/LyX.py
 479 \end_layout
 480
 481 \end_inset
 482
 483 .
 484 \end_layout
 485
 486 \begin_layout Enumerate
 487 \begin_inset CommandInset label
 488 LatexCommand label
 489 name "enu:Add-an-entry"
 490
 491 \end_inset
 492
 493 Add an entry to both format lists (for conversion and reversion) in
 494 \begin_inset Newline newline
 495 \end_inset
 496
 497
 498 \begin_inset Flex Code
 499 status collapsed
 500
 501 \begin_layout Plain Layout
 502 lib/lyx2lyx/lyx_2_3.py
 503 \end_layout
 504
 505 \end_inset
 506
 507 .
 508  Add a conversion routine if needed (e.
 509 \begin_inset space \thinspace{}
 510 \end_inset
 511
 512 g., a new header setting always needs a conversion that adds the new setting,
 513  but a new document language does not need one).
 514  Add a reversion routine if needed.
 515
 516 \begin_inset Newline newline
 517 \end_inset
 518
 519 While the conversion routine is required to produce a document that is equivalen
 520 t to the old version, the requirements of the reversion are not that strict.
 521  If possible, try to produce a proper reversion, using ERT if needed, but
 522  for some features this might be too complicated.
 523  In this case, the minimum requirement of the reversion routine is that
 524  it produces a valid document which can be read by an older \SpecialChar LyX
 525 .
 526  If absolutely needed, even data loss is allowed for the reversion.
 527  (In that case, you might want to add a LyX comment that indicates what
 528  you have had to do, so the user is at least warned).
 529 \end_layout
 530
 531 \begin_layout Enumerate
 532 Since tex2lyx has several implicit file format dependencies caused by sharing
 533  code with \SpecialChar LyX
 534 , updating the file format of .lyx files produced by tex2lyx at
 535  the same time as updating the main .lyx file format is strongly recommended.
 536  Therefore, a compiler warning will be issued if the \SpecialChar LyX
 537  and tex2lyx .lyx file
 538  format numbers differ.
 539  In many cases the tex2lyx update requires only the first and last item
 540  of the list below:
 541 \end_layout
 542
 543 \begin_deeper
 544 \begin_layout Enumerate
 545 Update the tex2lyx file format number in
 546 \begin_inset Flex Code
 547 status collapsed
 548
 549 \begin_layout Plain Layout
 550 src/version.h
 551 \end_layout
 552
 553 \end_inset
 554
 555 .
 556 \end_layout
 557
 558 \begin_layout Enumerate
 559 If the lyx2lyx conversion from the old to the new format is empty, or if
 560  tex2lyx does not yet output the changed feature, you do not need any further
 561  tex2lyx changes.
 562  Otherwise, search for the changed feature in tex2lyx, and adjust the output
 563  according to the lyx2lyx changes.
 564 \end_layout
 565
 566 \begin_layout Enumerate
 567 Update the tex2lyx test references as described in
 568 \begin_inset CommandInset ref
 569 LatexCommand formatted
 570 reference "sec:Updating-test-references"
 571
 572 \end_inset
 573
 574 .
 575 \end_layout
 576
 577 \end_deeper
 578 \begin_layout Enumerate
 579 If you did not implement full tex2lyx support for the new feature, add a
 580  line to
 581 \begin_inset Flex Code
 582 status collapsed
 583
 584 \begin_layout Plain Layout
 585 src/tex2lyx/TODO.txt
 586 \end_layout
 587
 588 \end_inset
 589
 590  describing the missing bits.
 591  Note that it is perfectly fine if you do not add full tex2lyx support for
 592  a new feature: The updating recommendation above is only issued for the
 593  syntax of the produced .lyx file.
 594  It is no problem if some features supported by \SpecialChar LyX
 595  are still output as ERT
 596  by tex2lyx.
 597  The problems in the past that resulted in the update recommendation were
 598  related to mixed version syntax, not ERT.
 599 \end_layout
 600
 601 \begin_layout Enumerate
 602 It would be nice if you could create a .lyx test file which contains instances
 603  of all changed or added features.
 604  This could then be used to test lyx2lyx and tex2lyx.
 605  Unfortunately, it has not yet been decided how to collect such examples,
 606  so please ask on the development list if you want to create one.
 607 \end_layout
 608
 609 \begin_layout Enumerate
 610 \begin_inset CommandInset label
 611 LatexCommand label
 612 name "enu:updatefiles"
 613
 614 \end_inset
 615
 616 Update LyX's .lyx documentation files to the new format.
 617  The developer who makes the change knows best what changes to expect when
 618  inspecting the resulting diff.
 619  Because of this, you might be able to catch a bug in the lyx2lyx code that
 620  updates the format just by taking a quick scan through the large diff that
 621  is the result.
 622 \begin_inset Note Note
 623 status collapsed
 624
 625 \begin_layout Plain Layout
 626 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
 627  see which layout update made an unexpected change by looking at the git
 628  log of a .lyx file that suffers the problem.
 629 \end_layout
 630
 631 \end_inset
 632
 633  To do this, first make sure that there are no changes to the git repository
 634  that you will not want to commit (this is needed because it will be convenient
 635  to commit with the command
 636 \begin_inset Flex Code
 637 status collapsed
 638
 639 \begin_layout Plain Layout
 640 git commit -a
 641 \end_layout
 642
 643 \end_inset
 644
 645 ).
 646  Then run the following command in the root folder of the source:
 647 \begin_inset Flex Code
 648 status collapsed
 649
 650 \begin_layout Plain Layout
 651 python development/tools/updatedocs.py
 652 \end_layout
 653
 654 \end_inset
 655
 656 .
 657  Look at the resulting changes using the command
 658 \begin_inset Flex Code
 659 status collapsed
 660
 661 \begin_layout Plain Layout
 662 git diff
 663 \end_layout
 664
 665 \end_inset
 666
 667 .
 668  If anything looks surprising, please investigate.
 669  Keep in mind that the case of
 670 \begin_inset Flex Code
 671 status collapsed
 672
 673 \begin_layout Plain Layout
 674 LFUNs.lyx
 675 \end_layout
 676
 677 \end_inset
 678
 679  is special, because it is first generated with
 680 \begin_inset Flex Code
 681 status collapsed
 682
 683 \begin_layout Plain Layout
 684 gen_lfuns.py
 685 \end_layout
 686
 687 \end_inset
 688
 689  before being converted to the latest format.
 690  Finally, commit using
 691 \begin_inset Flex Code
 692 status collapsed
 693
 694 \begin_layout Plain Layout
 695 git commit -a
 696 \end_layout
 697
 698 \end_inset
 699
 700 .
 701 \end_layout
 702
 703 \begin_layout Subsection
 704 Updating the file format number of layout files
 705 \end_layout
 706
 707 \begin_layout Standard
 708 The procedure for updating the layout files is similar to that in step
 709 \begin_inset CommandInset ref
 710 LatexCommand ref
 711 reference "enu:updatefiles"
 712
 713 \end_inset
 714
 715  in section
 716 \begin_inset CommandInset ref
 717 LatexCommand ref
 718 reference "subsec:update_lyx_files"
 719
 720 \end_inset
 721
 722 .
 723  One need only run
 724 \begin_inset Flex Code
 725 status collapsed
 726
 727 \begin_layout Plain Layout
 728 python development/tools/updatelayouts.py
 729 \end_layout
 730
 731 \end_inset
 732
 733  instead of
 734 \begin_inset Flex Code
 735 status collapsed
 736
 737 \begin_layout Plain Layout
 738 updatedocs.py
 739 \end_layout
 740
 741 \end_inset
 742
 743 .
 744 \end_layout
 745
 746 \begin_layout Standard
 747 Note that we do not automatically any local layout used in the
 748 \begin_inset Flex Code
 749 status collapsed
 750
 751 \begin_layout Plain Layout
 752 .lyx
 753 \end_layout
 754
 755 \end_inset
 756
 757  files shipped with \SpecialChar LyX
 758  because users would then not be able to export to older
 759  formats.
 760  For example, if a 2.2.0 user exported a template to 2.1.x format and tried
 761  to open the file in \SpecialChar LyX
 762  2.1.x, there would be an error because the file would
 763  contain a local layout whose format is too new.
 764  The root reason for this is that we do not support converting layouts to
 765  older layout formats, as we do for the
 766 \begin_inset Flex Code
 767 status collapsed
 768
 769 \begin_layout Plain Layout
 770 .lyx
 771 \end_layout
 772
 773 \end_inset
 774
 775  file format.
 776 \end_layout
 777
 778 \begin_layout Subsection
 779 Updating the file format number of bind/ui files
 780 \end_layout
 781
 782 \begin_layout Standard
 783 A change to the functionality of existing LFUNs can require a conversion
 784  of
 785 \begin_inset Flex Code
 786 status collapsed
 787
 788 \begin_layout Plain Layout
 789 .bind
 790 \end_layout
 791
 792 \end_inset
 793
 794  and
 795 \begin_inset Flex Code
 796 status collapsed
 797
 798 \begin_layout Plain Layout
 799 .ui
 800 \end_layout
 801
 802 \end_inset
 803
 804  files, and therefore an increment of the LFUN format, as well as a conversion
 805  of Info insets in
 806 \begin_inset Flex Code
 807 status collapsed
 808
 809 \begin_layout Plain Layout
 810 .lyx
 811 \end_layout
 812
 813 \end_inset
 814
 815  files for manuals.
 816  The latter cannot be done automatically and also requires an update of
 817  the \SpecialChar LyX
 818  file format.
 819  (Think e.g.
 820 \begin_inset space \space{}
 821 \end_inset
 822
 823 of someone who might have made a set of \SpecialChar LyX
 824  teaching manuals for use in their
 825  own group.)
 826 \begin_inset Foot
 827 status open
 828
 829 \begin_layout Plain Layout
 830 \begin_inset Flex URL
 831 status open
 832
 833 \begin_layout Plain Layout
 834
 835 http://www.lyx.org/trac/ticket/9794
 836 \end_layout
 837
 838 \end_inset
 839
 840
 841 \end_layout
 842
 843 \end_inset
 844
 845
 846 \end_layout
 847
 848 \begin_layout Standard
 849 To update the LFUN format:
 850 \end_layout
 851
 852 \begin_layout Enumerate
 853 Increment the LFUN file format number in
 854 \begin_inset Flex Code
 855 status collapsed
 856
 857 \begin_layout Plain Layout
 858 src/LyXAction.h
 859 \end_layout
 860
 861 \end_inset
 862
 863 .
 864 \end_layout
 865
 866 \begin_layout Enumerate
 867 Implement the LFUN conversion in
 868 \begin_inset Flex Code
 869 status collapsed
 870
 871 \begin_layout Plain Layout
 872 lib/scripts/prefs2prefs_lfuns.py
 873 \end_layout
 874
 875 \end_inset
 876
 877 .
 878 \end_layout
 879
 880 \begin_layout Enumerate
 881 See step
 882 \begin_inset CommandInset ref
 883 LatexCommand ref
 884 reference "enu:updatefiles"
 885
 886 \end_inset
 887
 888  in section
 889 \begin_inset CommandInset ref
 890 LatexCommand ref
 891 reference "subsec:update_lyx_files"
 892
 893 \end_inset
 894
 895  but instead of the
 896 \begin_inset Flex Code
 897 status collapsed
 898
 899 \begin_layout Plain Layout
 900 updatedocs.py
 901 \end_layout
 902
 903 \end_inset
 904
 905  command, use this command:
 906 \begin_inset Flex Code
 907 status collapsed
 908
 909 \begin_layout Plain Layout
 910 bash development/tools/updatelfuns.sh
 911 \end_layout
 912
 913 \end_inset
 914
 915 .
 916
 917 \begin_inset Note Note
 918 status open
 919
 920 \begin_layout Plain Layout
 921 This file should really be converted to python.
 922 \end_layout
 923
 924 \end_inset
 925
 926
 927 \end_layout
 928
 929 \begin_layout Enumerate
 930 Update Info insets in
 931 \begin_inset Flex Code
 932 status collapsed
 933
 934 \begin_layout Plain Layout
 935 .lyx
 936 \end_layout
 937
 938 \end_inset
 939
 940  files.
 941  To do so, increment the \SpecialChar LyX
 942  format and proceed as in
 943 \begin_inset CommandInset ref
 944 LatexCommand ref
 945 reference "subsec:update_lyx_files"
 946
 947 \end_inset
 948
 949 , steps
 950 \begin_inset CommandInset ref
 951 LatexCommand ref
 952 reference "enu:Describe_format"
 953
 954 \end_inset
 955
 956 –
 957 \begin_inset CommandInset ref
 958 LatexCommand ref
 959 reference "enu:updatefiles"
 960
 961 \end_inset
 962
 963 .
 964  In the lyx2lyx implementation (step
 965 \begin_inset CommandInset ref
 966 LatexCommand ref
 967 reference "enu:Add-an-entry"
 968
 969 \end_inset
 970
 971 ), implement a conversion similar to the one in
 972 \begin_inset Flex Code
 973 status collapsed
 974
 975 \begin_layout Plain Layout
 976 prefs2prefs_lfuns.py
 977 \end_layout
 978
 979 \end_inset
 980
 981  above, as well as a corresponding reversion; for this one can use
 982 \begin_inset Flex Code
 983 status collapsed
 984
 985 \begin_layout Plain Layout
 986 convert_info_insets
 987 \end_layout
 988
 989 \end_inset
 990
 991  from
 992 \begin_inset Flex Code
 993 status collapsed
 994
 995 \begin_layout Plain Layout
 996 lib/lyx2lyx/lyx2lyx_tools.py
 997 \end_layout
 998
 999 \end_inset
1000
1001 .
1002
1003 \end_layout
1004
1005 \begin_layout Subsection
1006 Backporting new styles to the stable version
1007 \begin_inset CommandInset label
1008 LatexCommand label
1009 name "subsec:Backporting-new-styles"
1010
1011 \end_inset
1012
1013
1014 \end_layout
1015
1016 \begin_layout Standard
1017 Starting with the stable \SpecialChar LyX
1018  2.1 branch, there is a mechanism in place to backport
1019  new styles to the stable version without the need to update the file format.
1020  The basic idea is that the new style definition is automatically copied
1021  to the document preamble so that it can even be used by older minor versions
1022  that did not yet include the style.
1023  To backport a new style to the stable version, the following steps are
1024  needed:
1025 \end_layout
1026
1027 \begin_layout Enumerate
1028 Add the line
1029 \begin_inset Flex Code
1030 status collapsed
1031
1032 \begin_layout Plain Layout
1033 ForceLocal -1
1034 \end_layout
1035
1036 \end_inset
1037
1038  to the style definition in the development version.
1039 \end_layout
1040
1041 \begin_layout Enumerate
1042 Copy the style definition to the stable version, but use
1043 \begin_inset Flex Code
1044 status collapsed
1045
1046 \begin_layout Plain Layout
1047 ForceLocal 1
1048 \end_layout
1049
1050 \end_inset
1051
1052  instead.
1053  If needed adjust the format to the one used by the stable version (see
1054  the customization manual for details of the layout file format).
1055 \end_layout
1056
1057 \begin_layout Enumerate
1058 For each update of the style in a later stable version, increase the argument
1059  of
1060 \begin_inset Flex Code
1061 status collapsed
1062
1063 \begin_layout Plain Layout
1064 ForceLocal
1065 \end_layout
1066
1067 \end_inset
1068
1069  by one.
1070  (In the stable version, the development version should not be touched.)
1071 \end_layout
1072
1073 \begin_layout Standard
1074 For details about the
1075 \begin_inset Flex Code
1076 status collapsed
1077
1078 \begin_layout Plain Layout
1079 ForceLocal
1080 \end_layout
1081
1082 \end_inset
1083
1084  flag see the customization manual.
1085  No
1086 \begin_inset Flex Code
1087 status collapsed
1088
1089 \begin_layout Plain Layout
1090 lyx2lyx
1091 \end_layout
1092
1093 \end_inset
1094
1095  support is needed for backported styles: Since the style of the development
1096  version has an infinite version number, it will always be used.
1097  Furthermore, since its version number is less than one, the style will
1098  not be written anymore to the document header for files saved by the new
1099  version.
1100 \end_layout
1101
1102 \begin_layout Section
1103 New layouts and modules
1104 \end_layout
1105
1106 \begin_layout Subsection
1107 \begin_inset CommandInset label
1108 LatexCommand label
1109 name "subsec:New-layouts"
1110
1111 \end_inset
1112
1113 New layouts
1114 \end_layout
1115
1116 \begin_layout Standard
1117 Adding a new layout file to the \SpecialChar LyX
1118  library makes it an
1119 \begin_inset Quotes eld
1120 \end_inset
1121
1122 officially supported
1123 \begin_inset Quotes erd
1124 \end_inset
1125
1126  layout.
1127  You should therefore think carefully about whether you really want to do
1128  this and discuss it on lyx-devel, since you will need to be prepared to
1129  update and fix the layout if necessary.
1130  If the layout is experimental or for a rarely used document class, then
1131  it may be better to add it to the relevant portion of the \SpecialChar LyX
1132  wiki, as a user
1133  contribution.
1134  See
1135 \begin_inset CommandInset href
1136 LatexCommand href
1137 target "https://wiki.lyx.org/Layouts/Layouts"
1138
1139 \end_inset
1140
1141 .
1142 \end_layout
1143
1144 \begin_layout Standard
1145 In older versions of this document, it was stated that new layout files
1146  require a file format change.
1147  After some discussion, it was decided that this is not needed.
1148 \begin_inset Foot
1149 status open
1150
1151 \begin_layout Plain Layout
1152 See
1153 \begin_inset CommandInset href
1154 LatexCommand href
1155 name "the thread “Proposal for a guide on updating layouts”"
1156 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1157
1158 \end_inset
1159
1160 .
1161 \end_layout
1162
1163 \end_inset
1164
1165
1166 \end_layout
1167
1168 \begin_layout Quote
1169 For reference, here are the arguments on each side
1170 \end_layout
1171
1172 \begin_deeper
1173 \begin_layout Description
1174 Pro
1175 \begin_inset Quotes eld
1176 \end_inset
1177
1178 New layout files are a file format change
1179 \begin_inset Quotes erd
1180 \end_inset
1181
1182
1183 \end_layout
1184
1185 \begin_layout Itemize
1186 All documents produced by 2.2.
1187 \begin_inset Formula $x$
1188 \end_inset
1189
1190  can always be edited and exported even if
1191 \begin_inset Formula $x$
1192 \end_inset
1193
1194  is different.
1195  This is important for people using different machines, or exchanging work
1196  with colleagues.
1197 \end_layout
1198
1199 \begin_layout Description
1200 Con
1201 \begin_inset Quotes eld
1202 \end_inset
1203
1204 New layout files are not a file format change
1205 \begin_inset Quotes erd
1206 \end_inset
1207
1208
1209 \end_layout
1210
1211 \begin_layout Itemize
1212 No new LaTeX classes can be supported in a stable version, and stable versions
1213  have a typical lifetime of 2–3 years.
1214 \end_layout
1215
1216 \begin_layout Itemize
1217 We have the same situation already with custom layout files: If a document
1218  using a custom layout file is moved between machines or people, then the
1219  layout file needs to be exchanged as well.
1220  If that is not done, then we have a fallback implemented so that such documents
1221  can still be edited, but not exported, and the user gets a warning.
1222
1223 \end_layout
1224
1225 \begin_layout Itemize
1226 The lyx2lyx script cannot do anything useful in such a case.
1227 \end_layout
1228
1229 \end_deeper
1230 \begin_layout Standard
1231 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1232  itself,
1233  then, you should do the following:
1234 \end_layout
1235
1236 \begin_layout Enumerate
1237 Put your new layout file in
1238 \begin_inset Flex Code
1239 status collapsed
1240
1241 \begin_layout Plain Layout
1242 lib/layouts/
1243 \end_layout
1244
1245 \end_inset
1246
1247  and add it to Git (
1248 \begin_inset Flex Code
1249 status collapsed
1250
1251 \begin_layout Plain Layout
1252 git add lib/layouts/newlayout.layout
1253 \end_layout
1254
1255 \end_inset
1256
1257 ) so that it will be committed.
1258 \end_layout
1259
1260 \begin_layout Enumerate
1261 Add an entry in
1262 \begin_inset Flex Code
1263 status collapsed
1264
1265 \begin_layout Plain Layout
1266 lib/Makefile.am
1267 \end_layout
1268
1269 \end_inset
1270
1271 , so that the new layout actually gets installed.
1272 \end_layout
1273
1274 \begin_layout Enumerate
1275 Add an entry in
1276 \begin_inset Flex Code
1277 status collapsed
1278
1279 \begin_layout Plain Layout
1280 lib/doc/LaTeXConfig.lyx
1281 \end_layout
1282
1283 \end_inset
1284
1285  containing in particular a line like
1286 \end_layout
1287
1288 \begin_deeper
1289 \begin_layout Quote
1290 Found: [InsetInfo]
1291 \end_layout
1292
1293 \begin_layout Standard
1294 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1295 \begin_inset Flex Code
1296 status collapsed
1297
1298 \begin_layout Plain Layout
1299 info-insert textclass <name>
1300 \end_layout
1301
1302 \end_inset
1303
1304 .
1305  This inset will automatically display a boxed
1306 \begin_inset Quotes eld
1307 \end_inset
1308
1309 yes
1310 \begin_inset Quotes erd
1311 \end_inset
1312
1313  or
1314 \begin_inset Quotes eld
1315 \end_inset
1316
1317 no
1318 \begin_inset Quotes erd
1319 \end_inset
1320
1321  depending on the availability of the package.
1322 \end_layout
1323
1324 \end_deeper
1325 \begin_layout Enumerate
1326 A template or example is strongly encouraged (but not necessarily required).
1327  It is also possible to provide both.
1328  Add them to
1329 \begin_inset Flex Code
1330 status collapsed
1331
1332 \begin_layout Plain Layout
1333 lib/templates/
1334 \end_layout
1335
1336 \end_inset
1337
1338  or
1339 \begin_inset Flex Code
1340 status collapsed
1341
1342 \begin_layout Plain Layout
1343 lib/examples/
1344 \end_layout
1345
1346 \end_inset
1347
1348 , respectively.
1349 \end_layout
1350
1351 \begin_layout Enumerate
1352 Reconfigure \SpecialChar LyX
1353 .
1354 \end_layout
1355
1356 \begin_layout Enumerate
1357 Ensure the autotests for the new layout pass (see
1358 \begin_inset CommandInset ref
1359 LatexCommand ref
1360 reference "par:when-to-run-an-export-test"
1361
1362 \end_inset
1363
1364 ).
1365 \end_layout
1366
1367 \begin_layout Subsection
1368 New modules
1369 \end_layout
1370
1371 \begin_layout Standard
1372 Adding a new module is very similar to adding a new layout.
1373  Therefore, the previous section applies to new modules as well, with two
1374  exceptions:
1375 \end_layout
1376
1377 \begin_layout Enumerate
1378 You only need to add an entry to
1379 \begin_inset Flex Code
1380 status collapsed
1381
1382 \begin_layout Plain Layout
1383 lib/doc/LaTeXConfig.lyx
1384 \end_layout
1385
1386 \end_inset
1387
1388  if the module requires a LaTeX package.
1389  In that case, the command for entering the InsetInfo is:
1390 \begin_inset Flex Code
1391 status collapsed
1392
1393 \begin_layout Plain Layout
1394 \paragraph_spacing single
1395 info-insert package <name>
1396 \end_layout
1397
1398 \end_inset
1399
1400
1401 \end_layout
1402
1403 \begin_layout Enumerate
1404 Modules do not need a template, only an example, which is strongly encouraged
1405  but not necessarily required.
1406 \end_layout
1407
1408 \begin_layout Subsection
1409 Layouts for document classes with incompatible versions
1410 \end_layout
1411
1412 \begin_layout Standard
1413 \begin_inset Note Greyedout
1414 status open
1415
1416 \begin_layout Description
1417 Note: This section is currently only a proposal under discussion.
1418  Please correct/amend as suited.
1419  Remove this note once a consensus is found.
1420 \end_layout
1421
1422 \begin_layout Plain Layout
1423 See the thread
1424 \begin_inset Quotes eld
1425 \end_inset
1426
1427 Proposal for a guide on updating layouts
1428 \begin_inset Quotes erd
1429 \end_inset
1430
1431  for details and background
1432 \end_layout
1433
1434 \begin_layout Plain Layout
1435 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1436 \end_layout
1437
1438 \end_inset
1439
1440
1441 \end_layout
1442
1443 \begin_layout Standard
1444 Every now and then, there are changes to LaTeX document classes that break
1445  backwards compatibility.
1446 \begin_inset Foot
1447 status collapsed
1448
1449 \begin_layout Plain Layout
1450 Uwe has suggested we implement automatic detection of changes in class files.
1451  This could be done by running a script every month that checks if a document
1452  class was changed at CTAN and at the homepages of the scientific journals.
1453  If it reports a change, we can check if our template and layout file are
1454  still usable with the changed document class.
1455  (This is different from the autotests insofar, as this would also catch
1456  changes that do not result in compilation errors.)
1457 \end_layout
1458
1459 \end_inset
1460
1461  Reasons can be a new name for the
1462 \begin_inset Flex Code
1463 status collapsed
1464
1465 \begin_layout Plain Layout
1466 *.cls
1467 \end_layout
1468
1469 \end_inset
1470
1471  file, removed \SpecialChar LaTeX
1472  commands, or both.
1473  How should this best be handled in \SpecialChar LyX
1474 ?
1475 \end_layout
1476
1477 \begin_layout Standard
1478 The idea is to support the new version with a new \SpecialChar LyX
1479  layout so that:
1480 \end_layout
1481
1482 \begin_layout Itemize
1483 Existing documents can still be opened in \SpecialChar LyX
1484  and will continue to work on
1485  systems where the old version is still installed.
1486
1487 \end_layout
1488
1489 \begin_layout Itemize
1490 With differently named
1491 \begin_inset Flex Code
1492 status collapsed
1493
1494 \begin_layout Plain Layout
1495 *.cls
1496 \end_layout
1497
1498 \end_inset
1499
1500  files, \SpecialChar LyX
1501  can check for the availability of the particular version and reflect
1502  this in the GUI.
1503  Different document class versions with the same file name are currently
1504  (2.2.x) not detected by the configuration script.
1505  This is planned for 2.3.
1506 \begin_inset Foot
1507 status collapsed
1508
1509 \begin_layout Plain Layout
1510 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1511 \end_layout
1512
1513 \begin_layout Plain Layout
1514 However, what we really need is version detection for the configuration,
1515  so that the user can be warned if the required class file has the wrong
1516  version.
1517  (If the class file keeps the name over the version change, only one of
1518  the two layout files generates compilable documents.)
1519 \end_layout
1520
1521 \begin_layout Plain Layout
1522 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1523 798
1524 \end_layout
1525
1526 \end_inset
1527
1528
1529 \end_layout
1530
1531 \begin_layout Itemize
1532 The new layout can be added both to the master and the stable branches,
1533  in accord with the policy discussed in
1534 \begin_inset CommandInset ref
1535 LatexCommand formatted
1536 reference "subsec:New-layouts"
1537
1538 \end_inset
1539
1540 .
1541  No lyx2lyx conversion is then required when a new major version is released.
1542 \end_layout
1543
1544 \begin_layout Standard
1545 The user can move an existing document to the new version simply by selecting
1546  a new document class.
1547  This step is well supported by \SpecialChar LyX
1548 , with established methods for handling
1549  unsupported styles and other changes.
1550  This way, no lyx2lyx code is required.
1551 \end_layout
1552
1553 \begin_layout Standard
1554 The steps to support a new version of an existing document class are thus:
1555 \end_layout
1556
1557 \begin_layout Itemize
1558 Create a new layout file including the upstream version in the name (avoid
1559  special characters like spaces and dots), e.g.
1560
1561 \begin_inset Flex Code
1562 status collapsed
1563
1564 \begin_layout Plain Layout
1565 acmsiggraph-v0-92.layout
1566 \end_layout
1567
1568 \end_inset
1569
1570 .
1571 \end_layout
1572
1573 \begin_layout Itemize
1574 Include the name of the
1575 \begin_inset Flex Code
1576 status collapsed
1577
1578 \begin_layout Plain Layout
1579 *.cls
1580 \end_layout
1581
1582 \end_inset
1583
1584  file as an optional argument in the
1585 \begin_inset Flex Code
1586 status collapsed
1587
1588 \begin_layout Plain Layout
1589
1590 \backslash
1591 DeclareLaTeXClass
1592 \end_layout
1593
1594 \end_inset
1595
1596  line and include the version number in the GUI name:
1597 \begin_inset Newline newline
1598 \end_inset
1599
1600
1601 \begin_inset Flex Code
1602 status collapsed
1603
1604 \begin_layout Plain Layout
1605
1606 \backslash
1607 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1608 \begin_inset space ~
1609 \end_inset
1610
1611 0.92)}
1612 \end_layout
1613
1614 \end_inset
1615
1616
1617 \end_layout
1618
1619 \begin_layout Itemize
1620 Update the GUI name in the old layout file (whose name should not be changed),
1621  e.g.:
1622 \begin_inset Newline newline
1623 \end_inset
1624
1625
1626 \begin_inset Flex Code
1627 status collapsed
1628
1629 \begin_layout Plain Layout
1630
1631 \backslash
1632 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1633 \begin_inset space ~
1634 \end_inset
1635
1636 0.91, obsolete)}
1637 \end_layout
1638
1639 \end_inset
1640
1641
1642 \end_layout
1643
1644 \begin_layout Itemize
1645 To avoid duplicate definitions, the new layout can
1646 \begin_inset Flex Code
1647 status collapsed
1648
1649 \begin_layout Plain Layout
1650 Input
1651 \end_layout
1652
1653 \end_inset
1654
1655  the old layout file and add\SpecialChar breakableslash
1656 remove\SpecialChar breakableslash
1657 obsolete\SpecialChar breakableslash
1658 modify settings and styles (similar
1659  to the inclusion of
1660 \begin_inset Flex Code
1661 status collapsed
1662
1663 \begin_layout Plain Layout
1664 *.inc
1665 \end_layout
1666
1667 \end_inset
1668
1669  files).
1670 \end_layout
1671
1672 \begin_deeper
1673 \begin_layout Standard
1674 It may be tempting to let the new layout be the
1675 \begin_inset Quotes eld
1676 \end_inset
1677
1678 master version
1679 \begin_inset Quotes erd
1680 \end_inset
1681
1682  and have the old layout import it.
1683  However, this should not be done because any changes to the new layout
1684  would need undo steps in the importing old layout.
1685 \end_layout
1686
1687 \end_deeper
1688 \begin_layout Itemize
1689 If the new LaTeX document class obsoletes the old one, update the example
1690  and template files to use the new layout.
1691  Add a note about the changes (preferably with a pointer to the documentation
1692  of the changes).
1693 \end_layout
1694
1695 \begin_deeper
1696 \begin_layout Standard
1697 This way, new documents based on the template or example will use the up-to-date
1698  document class version.
1699 \end_layout
1700
1701 \end_deeper
1702 \begin_layout Standard
1703 \begin_inset Newpage newpage
1704 \end_inset
1705
1706
1707 \end_layout
1708
1709 \begin_layout Section
1710 Tests
1711 \end_layout
1712
1713 \begin_layout Standard
1714 Automated tests are an important tool to detect bugs and regressions in
1715  software development.
1716  Some projects like gcc even require each bug fix to be accompanied by a
1717  test case for the automatic test suite, that would detect this bug.
1718  Testing interactive features automatically is of course very hard, but
1719  core functionality like document import and export can be tested quite
1720  easily, and some tests of this kind exist.
1721 \end_layout
1722
1723 \begin_layout Subsection
1724 unit tests
1725 \end_layout
1726
1727 \begin_layout Standard
1728 There are attempts to set up a suite of unit tests for LyX.
1729 \end_layout
1730
1731 \begin_layout Standard
1732 TODO: describe what is done and what is still to do.
1733 \end_layout
1734
1735 \begin_layout Subsection
1736 tex2lyx tests
1737 \end_layout
1738
1739 \begin_layout Standard
1740 The tex2lyx tests are located in the
1741 \begin_inset Flex Code
1742 status collapsed
1743
1744 \begin_layout Plain Layout
1745 src/tex2lyx/test
1746 \end_layout
1747
1748 \end_inset
1749
1750  subfolder of the \SpecialChar LyX
1751  source code distribution.
1752  The actual testing is performed by the simple python script
1753 \begin_inset Flex Code
1754 status collapsed
1755
1756 \begin_layout Plain Layout
1757 src/tex2lyx/test/runtests.py
1758 \end_layout
1759
1760 \end_inset
1761
1762 .
1763  Each test consists of two files:
1764 \begin_inset Flex Code
1765 status collapsed
1766
1767 \begin_layout Plain Layout
1768 <test name>.tex
1769 \end_layout
1770
1771 \end_inset
1772
1773  contains the \SpecialChar LaTeX
1774  code that should be tested.
1775
1776 \begin_inset Flex Code
1777 status collapsed
1778
1779 \begin_layout Plain Layout
1780 <test name>.lyx.lyx
1781 \end_layout
1782
1783 \end_inset
1784
1785  contains the expected output of tex2lyx.
1786  When a test is run, the actual produced output is compared with the stored
1787  reference output.
1788  The test passes if both are identical.
1789  The test machinery is also able to generate a file
1790 \begin_inset Flex Code
1791 status collapsed
1792
1793 \begin_layout Plain Layout
1794 <test name>.lyx.tex
1795 \end_layout
1796
1797 \end_inset
1798
1799  by exporting the produced .lyx file with \SpecialChar LyX
1800  again.
1801  This may be useful for roundtrip comparisons.
1802 \end_layout
1803
1804 \begin_layout Subsubsection
1805 Running the tests
1806 \end_layout
1807
1808 \begin_layout Standard
1809 The tex2lyx tests can be run in several ways.
1810  When in the
1811 \begin_inset Flex Code
1812 status collapsed
1813
1814 \begin_layout Plain Layout
1815 src/tex2lyx
1816 \end_layout
1817
1818 \end_inset
1819
1820  subfolder of the build directory, the commands
1821 \begin_inset Flex Code
1822 status collapsed
1823
1824 \begin_layout Plain Layout
1825 ctest
1826 \end_layout
1827
1828 \end_inset
1829
1830  (cmake, all platforms),
1831 \begin_inset Flex Code
1832 status collapsed
1833
1834 \begin_layout Plain Layout
1835 make test
1836 \end_layout
1837
1838 \end_inset
1839
1840  (cmake, when using a make based build system and not MSVC) or
1841 \begin_inset Flex Code
1842 status collapsed
1843
1844 \begin_layout Plain Layout
1845 make alltests
1846 \end_layout
1847
1848 \end_inset
1849
1850  (autotools) will run the tex2lyx tests.
1851  Alternatively, in the root of the build directory, the command
1852 \begin_inset Flex Code
1853 status collapsed
1854
1855 \begin_layout Plain Layout
1856 ctest -R tex2lyx
1857 \end_layout
1858
1859 \end_inset
1860
1861  runs all tests whose names match the regex
1862 \begin_inset Quotes eld
1863 \end_inset
1864
1865 tex2lyx
1866 \begin_inset Quotes erd
1867 \end_inset
1868
1869 .
1870  Another way to run the tex2lyx tests in the root build directory is to
1871  instead use the command
1872 \begin_inset Flex Code
1873 status collapsed
1874
1875 \begin_layout Plain Layout
1876 ctest -L '(cmplyx|roundtrip)'
1877 \end_layout
1878
1879 \end_inset
1880
1881 , which runs all tests categorized with the label
1882 \begin_inset Quotes eld
1883 \end_inset
1884
1885 roundtrip
1886 \begin_inset Quotes erd
1887 \end_inset
1888
1889  or
1890 \begin_inset Quotes eld
1891 \end_inset
1892
1893 cmplyx
1894 \begin_inset Quotes erd
1895 \end_inset
1896
1897 .
1898  If a test fails, the differences between the expected and actual results
1899  are output in unified diff format.
1900 \end_layout
1901
1902 \begin_layout Subsubsection
1903 Updating test references
1904 \begin_inset CommandInset label
1905 LatexCommand label
1906 name "sec:Updating-test-references"
1907
1908 \end_inset
1909
1910
1911 \end_layout
1912
1913 \begin_layout Standard
1914 In some cases a changed tex2lyx output is not a test failure, but wanted,
1915  e.
1916 \begin_inset space \thinspace{}
1917 \end_inset
1918
1919 g.
1920 \begin_inset space \space{}
1921 \end_inset
1922
1923 if a tex2lyx bug was fixed, or a new feature was added.
1924  In these cases the stored references need to be updated.
1925  To do so if using autotools, call
1926 \begin_inset Flex Code
1927 status collapsed
1928
1929 \begin_layout Plain Layout
1930 make updatetests
1931 \end_layout
1932
1933 \end_inset
1934
1935  in the
1936 \begin_inset Flex Code
1937 status collapsed
1938
1939 \begin_layout Plain Layout
1940 src/tex2lyx
1941 \end_layout
1942
1943 \end_inset
1944
1945  subdirectory of the build directory.
1946  If instead using CMake, call
1947 \begin_inset Flex Code
1948 status collapsed
1949
1950 \begin_layout Plain Layout
1951 make updatetex2lyxtests
1952 \end_layout
1953
1954 \end_inset
1955
1956  in the build directory or in the
1957 \begin_inset Flex Code
1958 status collapsed
1959
1960 \begin_layout Plain Layout
1961 src/tex2lyx/test
1962 \end_layout
1963
1964 \end_inset
1965
1966  subdirectory of the build directory.
1967 \begin_inset Foot
1968 status collapsed
1969
1970 \begin_layout Plain Layout
1971 Note that this is a case where a make target in the build directory can
1972  affect the source directory, which might not be advisable.
1973 \end_layout
1974
1975 \end_inset
1976
1977  On Windows do the following:
1978 \end_layout
1979
1980 \begin_layout Itemize
1981 Assure that the path to the python.exe is in your system PATH variable.
1982 \end_layout
1983
1984 \begin_layout Itemize
1985 Double-click on the file
1986 \begin_inset Flex Code
1987 status collapsed
1988
1989 \begin_layout Plain Layout
1990 updatetex2lyxtests.vcxproj
1991 \end_layout
1992
1993 \end_inset
1994
1995  in the build directory or in the
1996 \begin_inset Flex Code
1997 status collapsed
1998
1999 \begin_layout Plain Layout
2000 src/tex2lyx/test
2001 \end_layout
2002
2003 \end_inset
2004
2005  subdirectory of your build directory.
2006 \end_layout
2007
2008 \begin_layout Itemize
2009 In the appearing MSVC program right-click on the project
2010 \family sans
2011 updatetex2lyxtests
2012 \family default
2013  in the project explorer and chose
2014 \family sans
2015 Create
2016 \family default
2017 .
2018 \end_layout
2019
2020 \begin_layout Standard
2021 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2022  files.
2023  Please examine the changed output carefully before committing the changed
2024  files to the repository: Since the test machinery does not do a roundtrip
2025  test .tex
2026 \begin_inset Formula $\Rightarrow$
2027 \end_inset
2028
2029  .lyx
2030 \begin_inset Formula $\Rightarrow$
2031 \end_inset
2032
2033  .tex, and does not compare the produced dvi or pdf output, it assumes that
2034  the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2035 .
2036  There is only one chance to detect wrong output: before committing a new
2037  reference.
2038  Once it is committed, it is quite difficult to verify whether it is correct.
2039 \end_layout
2040
2041 \begin_layout Standard
2042 Please
2043 \emph on
2044 do not
2045 \emph default
2046  update the test references by opening them with \SpecialChar LyX
2047  or directly running lyx2lyx
2048  on them.
2049  This would not work, since lyx2lyx and \SpecialChar LyX
2050  produce slightly different files
2051  regarding insignificant whitespace and line breaks.
2052 \end_layout
2053
2054 \begin_layout Subsubsection
2055 Adding a new test
2056 \end_layout
2057
2058 \begin_layout Standard
2059 In many cases tests for new features may be added to one of the existing
2060  test files, but sometimes this is not possible or not wanted.
2061  Then a new test file needs to be added:
2062 \end_layout
2063
2064 \begin_layout Enumerate
2065 Create the new file
2066 \begin_inset Flex Code
2067 status collapsed
2068
2069 \begin_layout Plain Layout
2070 src/tex2lyx/test/<test name>.tex
2071 \end_layout
2072
2073 \end_inset
2074
2075  and run tex2lyx in roundtrip mode to produce the file
2076 \begin_inset Flex Code
2077 status collapsed
2078
2079 \begin_layout Plain Layout
2080 src/tex2lyx/test/<test name>.lyx.lyx
2081 \end_layout
2082
2083 \end_inset
2084
2085 .
2086  This file will be the new reference.
2087 \end_layout
2088
2089 \begin_layout Enumerate
2090 Once you confirmed that the tex2lyx output is correct, add the new files
2091  to the corresponding lists in
2092 \begin_inset Flex Code
2093 status collapsed
2094
2095 \begin_layout Plain Layout
2096 src/tex2lyx/test/runtests.py
2097 \end_layout
2098
2099 \end_inset
2100
2101 ,
2102 \begin_inset Flex Code
2103 status collapsed
2104
2105 \begin_layout Plain Layout
2106 src/tex2lyx/Makefile.am
2107 \end_layout
2108
2109 \end_inset
2110
2111  and
2112 \begin_inset Flex Code
2113 status collapsed
2114
2115 \begin_layout Plain Layout
2116 src/tex2lyx/test/CMakeLists.txt
2117 \end_layout
2118
2119 \end_inset
2120
2121 .
2122 \end_layout
2123
2124 \begin_layout Enumerate
2125 Commit the changes to the repository, or send a patch to the development
2126  list and ask for committing if you do not have commit rights.
2127 \end_layout
2128
2129 \begin_layout Subsection
2130 ctest automatic tests
2131 \end_layout
2132
2133 \begin_layout Standard
2134 Some tests are located in the
2135 \begin_inset Flex Code
2136 status collapsed
2137
2138 \begin_layout Plain Layout
2139 development/autotests/
2140 \end_layout
2141
2142 \end_inset
2143
2144  subfolder of the \SpecialChar LyX
2145  source code distribution.
2146
2147 \begin_inset Foot
2148 status open
2149
2150 \begin_layout Plain Layout
2151 The README document in this folder only describes the
2152 \begin_inset Quotes eld
2153 \end_inset
2154
2155 keytests
2156 \begin_inset Quotes erd
2157 \end_inset
2158
2159  subset of autotests!
2160 \end_layout
2161
2162 \end_inset
2163
2164
2165 \end_layout
2166
2167 \begin_layout Standard
2168 These tests can be run by the commands
2169 \begin_inset Flex Code
2170 status collapsed
2171
2172 \begin_layout Plain Layout
2173 ctest
2174 \end_layout
2175
2176 \end_inset
2177
2178  in the
2179 \emph on
2180  build directory
2181 \emph default
2182  (all platforms) or (when using a make based build system and not MSVC)
2183
2184 \begin_inset Flex Code
2185 status collapsed
2186
2187 \begin_layout Plain Layout
2188 make test
2189 \end_layout
2190
2191 \end_inset
2192
2193  in the
2194 \begin_inset Flex Code
2195 status collapsed
2196
2197 \begin_layout Plain Layout
2198 autotests/
2199 \end_layout
2200
2201 \end_inset
2202
2203  subfolder of the
2204 \emph on
2205  build directory
2206 \emph default
2207 .
2208  The test logs are written to the
2209 \begin_inset Flex Code
2210 status collapsed
2211
2212 \begin_layout Plain Layout
2213 Testing/Temporary/
2214 \end_layout
2215
2216 \end_inset
2217
2218  subfolder of the
2219 \emph on
2220
2221 \emph default
2222 build directory.
2223
2224 \end_layout
2225
2226 \begin_layout Subsubsection
2227 Export tests
2228 \end_layout
2229
2230 \begin_layout Standard
2231 The export tests are integration tests.
2232  They take longer to run and are more likely to break than the tex2lyx tests.
2233  Nevertheless, they have caught many regressions and without a better alternativ
2234 e it is important to keep them up-to-date and understand how they work.
2235 \end_layout
2236
2237 \begin_layout Standard
2238 The export tests
2239 \begin_inset Quotes eld
2240 \end_inset
2241
2242 reuse
2243 \begin_inset Quotes erd
2244 \end_inset
2245
2246  documentation, template, and example documents.
2247  In addition, there are a number of dedicated sample documents in the
2248 \begin_inset Flex Code
2249 status collapsed
2250
2251 \begin_layout Plain Layout
2252 autotests/export/
2253 \end_layout
2254
2255 \end_inset
2256
2257  subfolder of the \SpecialChar LyX
2258  source code distribution.
2259  All samples are (after copying and eventual processing by scripts) exported
2260  to various output formats via the
2261 \begin_inset Flex Code
2262 status collapsed
2263
2264 \begin_layout Plain Layout
2265 —export-to
2266 \end_layout
2267
2268 \end_inset
2269
2270  command line option.
2271  The tests checks for errors reported by LyX.
2272  (However, error-free export is no guarantee for an error-free output document.)
2273 \end_layout
2274
2275 \begin_layout Paragraph
2276 \begin_inset CommandInset label
2277 LatexCommand label
2278 name "par:when-to-run-an-export-test"
2279
2280 \end_inset
2281
2282 Expectations of LyX developers
2283 \end_layout
2284
2285 \begin_layout Standard
2286 Because the export tests are integration tests and take a long time to run,
2287  LyX developers are rarely expected to run all of the tests.
2288  Here are some good practices to follow by developers:
2289 \end_layout
2290
2291 \begin_layout Itemize
2292 When making a non-trivial change to a .layout file, run the export and layout
2293  tests corresponding with that .layout file.
2294 \end_layout
2295
2296 \begin_layout Itemize
2297 When making non-trivial changes to a .lyx file, run the export tests correspondin
2298 g to that .lyx file.
2299
2300 \begin_inset Foot
2301 status collapsed
2302
2303 \begin_layout Plain Layout
2304 This rule is due to revision.
2305
2306 \end_layout
2307
2308 \begin_layout Plain Layout
2309 There is an objection from the documentation maintainer that working on
2310  the documentation must not be complicated by having to consider non-standard
2311  exports.
2312 \end_layout
2313
2314 \begin_layout Itemize
2315 successful compiling/testing an edited documentation file with pdflatex
2316  suffices to ensure it can be commited, not tests with other exports are
2317  required.
2318 \end_layout
2319
2320 \begin_layout Plain Layout
2321 If sudden failures with other exports due to “half-tested” documentation
2322  updates are a problem for the test maintainer, the test suite should use
2323  copies that are
2324 \end_layout
2325
2326 \begin_layout Itemize
2327 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2328 \end_layout
2329
2330 \begin_layout Itemize
2331 updated regularely (but on a time chosen by the test suite maintainer) from
2332  the originals in lib/doc/
2333 \end_layout
2334
2335 \begin_layout Plain Layout
2336 This way,
2337 \end_layout
2338
2339 \begin_layout Itemize
2340 no test will fail due to ongoing work on documentation,
2341 \end_layout
2342
2343 \begin_layout Itemize
2344 the documentation is still tested in full (with some delay),
2345 \end_layout
2346
2347 \begin_layout Itemize
2348 failures with non-default export can be examined and handled accordingly
2349  in one run with the cache update,
2350 \end_layout
2351
2352 \begin_layout Itemize
2353 “interesting failures” (like the nested-language+polyglossia problem in
2354  es/Customization can be separated and moved into dedicated test samples.
2355 \end_layout
2356
2357 \end_inset
2358
2359
2360 \end_layout
2361
2362 \begin_layout Itemize
2363 When making non-trivial changes to LyX's \SpecialChar LaTeX
2364  export code (e.g.
2365  touching the encoding code or package handling code that you expect will
2366  change the exported \SpecialChar LaTeX
2367  in some way):
2368 \end_layout
2369
2370 \begin_deeper
2371 \begin_layout Standard
2372 \paragraph_spacing single
2373 Consider running all of the export tests before and after your change.
2374  If there are differences, please reconcile these (i.e.
2375  fix the bug or fix the tests)
2376 \emph on
2377 before
2378 \emph default
2379  committing.
2380  Ask for help if you're not sure what to.
2381 \end_layout
2382
2383 \begin_layout Standard
2384 If you do not want to run the tests,
2385 \end_layout
2386
2387 \begin_layout Itemize
2388 post the patch on the list and others will run the tests and eventually
2389  ask for fixes, or
2390 \end_layout
2391
2392 \begin_layout Itemize
2393 commit, but be prepared to fix eventually arising problems or to revert
2394  the commit if there is no easy fix.
2395 \end_layout
2396
2397 \end_deeper
2398 \begin_layout Itemize
2399 Understand how to interpret test failures.
2400  If your commit is found to have broken a test, you should be able to interpret
2401  the test results when made aware of them.
2402  See Section
2403 \begin_inset CommandInset ref
2404 LatexCommand ref
2405 reference "subsec:Interpreting-export-tests"
2406
2407 \end_inset
2408
2409 .
2410 \end_layout
2411
2412 \begin_layout Paragraph
2413 \begin_inset CommandInset label
2414 LatexCommand label
2415 name "par:export-test-output-formats"
2416
2417 \end_inset
2418
2419 Output formats
2420 \end_layout
2421
2422 \begin_layout Standard
2423 The following output formats are currently tested for each sample document
2424  (see
2425 \begin_inset CommandInset ref
2426 LatexCommand ref
2427 reference "par:Export-test-filtering"
2428
2429 \end_inset
2430
2431  for exceptions):
2432 \end_layout
2433
2434 \begin_layout Labeling
2435 \labelwidthstring 00.00.0000
2436 LyX:
2437 \end_layout
2438
2439 \begin_deeper
2440 \begin_layout Labeling
2441 \labelwidthstring 00.00.0000
2442 lyx16 LyX 1.6 file format (lyx2lyx)
2443 \end_layout
2444
2445 \begin_layout Labeling
2446 \labelwidthstring 00.00.0000
2447 lyx21 LyX 2.1 file format (lyx2lyx)
2448 \end_layout
2449
2450 \begin_layout Labeling
2451 \labelwidthstring 00.00.0000
2452 xhtml LyXHTML (native LyX HTML export)
2453 \end_layout
2454
2455 \end_deeper
2456 \begin_layout Labeling
2457 \labelwidthstring 00.00.0000
2458 LyX
2459 \begin_inset space ~
2460 \end_inset
2461
2462 +
2463 \begin_inset space ~
2464 \end_inset
2465
2466 LaTeX:
2467 \end_layout
2468
2469 \begin_deeper
2470 \begin_layout Labeling
2471 \labelwidthstring pdf5msystemFM
2472 dvi DVI (8-bit latex)
2473 \end_layout
2474
2475 \begin_layout Labeling
2476 \labelwidthstring pdf5msystemFM
2477 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2478 \end_layout
2479
2480 \begin_layout Labeling
2481 \labelwidthstring pdf5msystemFM
2482 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2483 \end_layout
2484
2485 \begin_layout Labeling
2486 \labelwidthstring pdf5msystemFM
2487 pdf2 PDF (pdflatex)
2488 \end_layout
2489
2490 \begin_layout Labeling
2491 \labelwidthstring pdf5msystemFM
2492 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2493 \end_layout
2494
2495 \begin_layout Labeling
2496 \labelwidthstring pdf5msystemFM
2497 pdf4_systemF PDF (XeTeX with Unicode fonts)
2498 \end_layout
2499
2500 \begin_layout Labeling
2501 \labelwidthstring pdf5msystemFM
2502 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2503 \end_layout
2504
2505 \begin_layout Labeling
2506 \labelwidthstring pdf5msystemFM
2507 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2508 \end_layout
2509
2510 \end_deeper
2511 \begin_layout Labeling
2512 \labelwidthstring 00.00.0000
2513 LyX
2514 \begin_inset space ~
2515 \end_inset
2516
2517 +
2518 \begin_inset space ~
2519 \end_inset
2520
2521 LaTeX
2522 \begin_inset space ~
2523 \end_inset
2524
2525 +
2526 \begin_inset space ~
2527 \end_inset
2528
2529 postprocessing:
2530 \end_layout
2531
2532 \begin_deeper
2533 \begin_layout Labeling
2534 \labelwidthstring pdf5msystemFM
2535 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2536 \end_layout
2537
2538 \begin_layout Labeling
2539 \labelwidthstring pdf5msystemFM
2540 pdf3 DVI -> PDF (dvipdfm)
2541 \end_layout
2542
2543 \end_deeper
2544 \begin_layout Labeling
2545 \labelwidthstring 00.00.0000
2546 not
2547 \begin_inset space ~
2548 \end_inset
2549
2550 tested: (or only if set as default output format in the document source)
2551 \end_layout
2552
2553 \begin_deeper
2554 \begin_layout Labeling
2555 \labelwidthstring pdf5msystemFM
2556 latex LaTeX (plain)
2557 \end_layout
2558
2559 \begin_layout Labeling
2560 \labelwidthstring pdf5msystemFM
2561 luatex LaTeX (LuaTeX)
2562 \end_layout
2563
2564 \begin_layout Labeling
2565 \labelwidthstring pdf5msystemFM
2566 dviluatex LaTeX (dviluatex)
2567 \end_layout
2568
2569 \begin_layout Labeling
2570 \labelwidthstring pdf5msystemFM
2571 pdflatex LaTeX (pdflatex)
2572 \end_layout
2573
2574 \begin_layout Labeling
2575 \labelwidthstring pdf5msystemFM
2576 platex LaTeX (pLaTeX)
2577 \end_layout
2578
2579 \begin_layout Labeling
2580 \labelwidthstring pdf5msystemFM
2581 xetex LaTeX (XeTeX)
2582 \end_layout
2583
2584 \begin_layout Labeling
2585 \labelwidthstring pdf5msystemFM
2586 eps3 EPS (encapsulated Postscript) (cropped)
2587 \end_layout
2588
2589 \begin_layout Labeling
2590 \labelwidthstring pdf5msystemFM
2591 ps DVI -> Postscript (dvips)
2592 \end_layout
2593
2594 \begin_layout Labeling
2595 \labelwidthstring pdf5msystemFM
2596 odf
2597 \end_layout
2598
2599 \begin_layout Labeling
2600 \labelwidthstring pdf5msystemFM
2601 text (nor text2, ..., text4)
2602 \end_layout
2603
2604 \begin_layout Labeling
2605 \labelwidthstring pdf5msystemFM
2606 textparagraph
2607 \end_layout
2608
2609 \begin_layout Labeling
2610 \labelwidthstring pdf5msystemFM
2611 word
2612 \end_layout
2613
2614 \begin_layout Labeling
2615 \labelwidthstring pdf5msystemFM
2616 word2
2617 \end_layout
2618
2619 \begin_layout Labeling
2620 \labelwidthstring pdf5msystemFM
2621 wordhtml
2622 \end_layout
2623
2624 \end_deeper
2625 \begin_layout Paragraph
2626 \begin_inset CommandInset label
2627 LatexCommand label
2628 name "par:Configuring-ctests"
2629
2630 \end_inset
2631
2632 Configuring the tests
2633 \end_layout
2634
2635 \begin_layout Standard
2636 To enable the export autotests, add the
2637 \begin_inset Flex Code
2638 status collapsed
2639
2640 \begin_layout Plain Layout
2641 -DLYX_ENABLE_EXPORT_TESTS=ON
2642 \end_layout
2643
2644 \end_inset
2645
2646  flag.
2647  For example:
2648 \end_layout
2649
2650 \begin_layout Standard
2651 \begin_inset Flex Code
2652 status collapsed
2653
2654 \begin_layout Plain Layout
2655 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2656 \end_layout
2657
2658 \end_inset
2659
2660
2661 \end_layout
2662
2663 \begin_layout Standard
2664 \noindent
2665 This flag will increase the time for the cmake command by several seconds,
2666  mainly because of the process of inverting tests (see Section
2667 \begin_inset CommandInset ref
2668 LatexCommand ref
2669 reference "subsec:Interpreting-export-tests"
2670
2671 \end_inset
2672
2673 ).
2674 \end_layout
2675
2676 \begin_layout Paragraph
2677 \begin_inset CommandInset label
2678 LatexCommand label
2679 name "par:ctest-options"
2680
2681 \end_inset
2682
2683 Running the tests
2684 \end_layout
2685
2686 \begin_layout Standard
2687 To run all tests, in the build directory simply run the command
2688 \begin_inset Flex Code
2689 status collapsed
2690
2691 \begin_layout Plain Layout
2692 ctest
2693 \end_layout
2694
2695 \end_inset
2696
2697 .
2698  A full, up-to-date TeXLive installation is recommended to run the tests.
2699  Otherwise, some tests will fail.
2700  Tests with additional requirements are labeled
2701 \begin_inset Quotes eld
2702 \end_inset
2703
2704 unreliable:nonstandard
2705 \begin_inset Quotes erd
2706 \end_inset
2707
2708
2709 \change_inserted 34634807 1486630943
2710
2711 \begin_inset Foot
2712 status collapsed
2713
2714 \begin_layout Plain Layout
2715
2716 \change_inserted 34634807 1486631129
2717 With an up-to-date Texlive 2016 installation, there are standard tests which
2718  will fail because of missing packages or external applications, see below
2719  for a list of those which should be installed to avoid these failures.
2720 \change_unchanged
2721
2722 \end_layout
2723
2724 \end_inset
2725
2726
2727 \change_unchanged
2728 .
2729
2730 \end_layout
2731
2732 \begin_layout Standard
2733 To run only some of the tests, use command line options (see examples below):
2734 \end_layout
2735
2736 \begin_layout Labeling
2737 \labelwidthstring -R
2738 \begin_inset Flex Code
2739 status collapsed
2740
2741 \begin_layout Plain Layout
2742 -R <pattern>
2743 \end_layout
2744
2745 \end_inset
2746
2747  Run only the tests whose names match the given regular expression.
2748 \end_layout
2749
2750 \begin_layout Labeling
2751 \labelwidthstring -R
2752 \begin_inset Flex Code
2753 status collapsed
2754
2755 \begin_layout Plain Layout
2756 -L <pattern>
2757 \end_layout
2758
2759 \end_inset
2760
2761  Run only the tests whose labels match the given regular expression.
2762  A test may have more that one label.
2763
2764 \end_layout
2765
2766 \begin_layout Labeling
2767 \labelwidthstring -R
2768 \begin_inset Flex Code
2769 status collapsed
2770
2771 \begin_layout Plain Layout
2772 -E <pattern>
2773 \end_layout
2774
2775 \end_inset
2776
2777  Exclude the tests whose names match the given regular expression.
2778 \end_layout
2779
2780 \begin_layout Labeling
2781 \labelwidthstring -R
2782 \begin_inset Flex Code
2783 status collapsed
2784
2785 \begin_layout Plain Layout
2786 -LE <pattern>
2787 \end_layout
2788
2789 \end_inset
2790
2791  Exclude the tests whose labels match the given regular expression.
2792  Cannot be combined with
2793 \begin_inset Flex Code
2794 status collapsed
2795
2796 \begin_layout Plain Layout
2797 -L
2798 \end_layout
2799
2800 \end_inset
2801
2802 .
2803 \end_layout
2804
2805 \begin_layout Standard
2806 The following options help to find good selection patterns:
2807 \end_layout
2808
2809 \begin_layout Labeling
2810 \labelwidthstring -R
2811 \begin_inset Flex Code
2812 status collapsed
2813
2814 \begin_layout Plain Layout
2815 -N
2816 \end_layout
2817
2818 \end_inset
2819
2820  List the tests that would be run but not actually run them.
2821
2822 \end_layout
2823
2824 \begin_deeper
2825 \begin_layout Standard
2826 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2827  to know how many tests there are or whether your
2828 \begin_inset Flex Code
2829 status collapsed
2830
2831 \begin_layout Plain Layout
2832 <pattern>
2833 \end_layout
2834
2835 \end_inset
2836
2837  regular expression did what you expected.
2838 \end_layout
2839
2840 \end_deeper
2841 \begin_layout Labeling
2842 \labelwidthstring -R
2843 \begin_inset Flex Code
2844 status collapsed
2845
2846 \begin_layout Plain Layout
2847 \SpecialChar nobreakdash
2848 \SpecialChar nobreakdash
2849 print-labels
2850 \end_layout
2851
2852 \end_inset
2853
2854  print the list of all labels associated with the test set.
2855  Can also be combined with -R, -L, -E, ...
2856
2857 \end_layout
2858
2859 \begin_layout Standard
2860 Other useful options are:
2861 \end_layout
2862
2863 \begin_layout Labeling
2864 \labelwidthstring -R
2865 \begin_inset Flex Code
2866 status collapsed
2867
2868 \begin_layout Plain Layout
2869 -j <jobs>
2870 \end_layout
2871
2872 \end_inset
2873
2874  Run the tests in parallel using the given number of jobs.
2875 \end_layout
2876
2877 \begin_deeper
2878 \begin_layout Standard
2879 We are still working on getting the tests to run in parallel.
2880  However, when running the tests in parallel, sometimes tests fail that
2881  pass when run sequentially.
2882  A reasonable approach is to first run the tests in parallel and then run
2883  the failed tests sequentially.
2884 \end_layout
2885
2886 \begin_layout Standard
2887 For example, to run 8 jobs at a time:
2888 \end_layout
2889
2890 \begin_layout Standard
2891 \begin_inset Flex Code
2892 status collapsed
2893
2894 \begin_layout Plain Layout
2895 ctest -j8
2896 \end_layout
2897
2898 \end_inset
2899
2900
2901 \end_layout
2902
2903 \begin_layout Standard
2904 \begin_inset Flex Code
2905 status collapsed
2906
2907 \begin_layout Plain Layout
2908 ctest \SpecialChar nobreakdash
2909 \SpecialChar nobreakdash
2910 rerun-failed
2911 \end_layout
2912
2913 \end_inset
2914
2915
2916 \end_layout
2917
2918 \begin_layout Standard
2919 When specifying a subset of the tests (e.g.
2920  using
2921 \begin_inset Flex Code
2922 status collapsed
2923
2924 \begin_layout Plain Layout
2925 \SpecialChar nobreakdash
2926 R <pattern>
2927 \end_layout
2928
2929 \end_inset
2930
2931 ), the same subset must be specified when using the
2932 \begin_inset Flex Code
2933 status collapsed
2934
2935 \begin_layout Plain Layout
2936 \SpecialChar nobreakdash
2937 \SpecialChar nobreakdash
2938 rerun-failed
2939 \end_layout
2940
2941 \end_inset
2942
2943  option because it is the test numbers that are used to index which tests
2944  failed on the previous run.
2945 \end_layout
2946
2947 \begin_layout Standard
2948 \noindent
2949 Note that some tests cannot be run in parallel.
2950  These tests are marked in the code with the
2951 \begin_inset Flex Code
2952 status collapsed
2953
2954 \begin_layout Plain Layout
2955 \noindent
2956 RUN_SERIAL ON
2957 \end_layout
2958
2959 \end_inset
2960
2961  CMake property.
2962 \end_layout
2963
2964 \end_deeper
2965 \begin_layout Labeling
2966 \labelwidthstring -R
2967 \begin_inset Flex Code
2968 status collapsed
2969
2970 \begin_layout Plain Layout
2971 \SpecialChar nobreakdash
2972 \SpecialChar nobreakdash
2973 timeout <seconds>
2974 \end_layout
2975
2976 \end_inset
2977
2978  Set a global timeout on all tests that do not already have a timeout set
2979  on them.
2980 \end_layout
2981
2982 \begin_deeper
2983 \begin_layout Standard
2984 There have been bugs in LyX and in \SpecialChar LaTeX
2985  which cause compilation to hang, and
2986  without a timeout a test might never stop (in one case there was even a
2987  memory leak).
2988  If a test times out, the
2989 \begin_inset Flex Code
2990 status collapsed
2991
2992 \begin_layout Plain Layout
2993 ctest
2994 \end_layout
2995
2996 \end_inset
2997
2998  command exits with error, but you can distinguish between a timed out test
2999  and a failed test in the output reported at the end of the
3000 \begin_inset Flex Code
3001 status collapsed
3002
3003 \begin_layout Plain Layout
3004 ctest
3005 \end_layout
3006
3007 \end_inset
3008
3009  command.
3010 \end_layout
3011
3012 \end_deeper
3013 \begin_layout Standard
3014 See the manual (
3015 \begin_inset Flex Code
3016 status collapsed
3017
3018 \begin_layout Plain Layout
3019 man ctest
3020 \end_layout
3021
3022 \end_inset
3023
3024 ) the full list of command line options.
3025 \end_layout
3026
3027 \begin_layout Paragraph
3028 Examples
3029 \end_layout
3030
3031 \begin_layout Itemize
3032 run only the export tests:
3033 \begin_inset Flex Code
3034 status collapsed
3035
3036 \begin_layout Plain Layout
3037 ctest -L export
3038 \end_layout
3039
3040 \end_inset
3041
3042
3043 \end_layout
3044
3045 \begin_layout Itemize
3046 run inverted tests:
3047 \begin_inset Flex Code
3048 status collapsed
3049
3050 \begin_layout Plain Layout
3051 ctest -L "inverted|suspended"
3052 \end_layout
3053
3054 \end_inset
3055
3056
3057 \end_layout
3058
3059 \begin_layout Itemize
3060 list all export tests which match any of the labelling patterns:
3061 \begin_inset Flex Code
3062 status collapsed
3063
3064 \begin_layout Plain Layout
3065 ctest -N -R "
3066 \backslash
3067 ..*_export/"
3068 \end_layout
3069
3070 \end_inset
3071
3072
3073 \end_layout
3074
3075 \begin_layout Itemize
3076 exclude rarely used output formats and post-processing tests
3077 \begin_inset Flex Code
3078 status collapsed
3079
3080 \begin_layout Plain Layout
3081 ctest -L export -E "_(texF|dvi3|pdf3?)"
3082 \end_layout
3083
3084 \end_inset
3085
3086
3087 \end_layout
3088
3089 \begin_layout Paragraph
3090 \begin_inset CommandInset label
3091 LatexCommand label
3092 name "subsec:Interpreting-export-tests"
3093
3094 \end_inset
3095
3096 Interpreting the export test results
3097 \end_layout
3098
3099 \begin_layout Standard
3100 A test can fail for several reasons, not all of them bad.
3101 \end_layout
3102
3103 \begin_layout Enumerate
3104 A new or edited sample document may be incompatible with some output formats.
3105 \end_layout
3106
3107 \begin_layout Enumerate
3108 A dependency is not met (e.g.
3109  the \SpecialChar LaTeX
3110  class file).
3111  One hint that this is the case is that the corresponding
3112 \begin_inset Flex Code
3113 status collapsed
3114
3115 \begin_layout Plain Layout
3116 check_load
3117 \end_layout
3118
3119 \end_inset
3120
3121  test will likely also fail.
3122 \end_layout
3123
3124 \begin_layout Enumerate
3125 An inverted test fails to fail (i.e.
3126  export that previously failed now works).
3127 \end_layout
3128
3129 \begin_layout Enumerate
3130 An external dependency was updated (e.g.
3131  \SpecialChar TeX
3132  Live).
3133 \end_layout
3134
3135 \begin_layout Enumerate
3136 A recent code change introduced a bug.
3137 \end_layout
3138
3139 \begin_layout Enumerate
3140 \begin_inset CommandInset label
3141 LatexCommand label
3142 name "enu:exposed"
3143
3144 \end_inset
3145
3146 A change in a document exposed a previously unknown bug or an incompatibility
3147  with an export format (e.g.
3148  Lua\SpecialChar LaTeX
3149 ).
3150 \end_layout
3151
3152 \begin_layout Standard
3153 Because the .lyx files are exported in several formats, it is not surprising
3154  that many of the exports fail.
3155  This expectation of failure is addressed by
3156 \begin_inset Quotes eld
3157 \end_inset
3158
3159 inverting
3160 \begin_inset Quotes erd
3161 \end_inset
3162
3163  the tests, that is, by marking the test as
3164 \begin_inset Quotes eld
3165 \end_inset
3166
3167 passing
3168 \begin_inset Quotes erd
3169 \end_inset
3170
3171  if the export exits with error and as
3172 \begin_inset Quotes eld
3173 \end_inset
3174
3175 failing
3176 \begin_inset Quotes erd
3177 \end_inset
3178
3179  if the export succeeds
3180 \emph on
3181 .
3182
3183 \emph default
3184  It follows that these expected failures will not show up as failed tests
3185  in the test results and thus will not pollute the
3186 \begin_inset Quotes eld
3187 \end_inset
3188
3189 good
3190 \begin_inset Quotes erd
3191 \end_inset
3192
3193  tests.
3194  If the export actually succeeds, then the test will fail.
3195  The purpose of this failure is to get your attention—something has changed,
3196  possibly for the better.
3197 \end_layout
3198
3199 \begin_layout Standard
3200 We try to document why a test is inverted or ignored.
3201  See the comment (prefixed with
3202 \begin_inset Flex Code
3203 status collapsed
3204
3205 \begin_layout Plain Layout
3206 #
3207 \end_layout
3208
3209 \end_inset
3210
3211 ) above the block in which the test is listed as inverted or ignored in
3212  the files
3213 \begin_inset Flex Code
3214 status collapsed
3215
3216 \begin_layout Plain Layout
3217 development/autotests/invertedTests
3218 \end_layout
3219
3220 \end_inset
3221
3222 ,
3223 \begin_inset Flex Code
3224 status collapsed
3225
3226 \begin_layout Plain Layout
3227 development/autotests/unreliableTests
3228 \end_layout
3229
3230 \end_inset
3231
3232  and
3233 \begin_inset Flex Code
3234 status collapsed
3235
3236 \begin_layout Plain Layout
3237 development/autotests/ignoredTests
3238 \end_layout
3239
3240 \end_inset
3241
3242 .
3243
3244 \end_layout
3245
3246 \begin_layout Standard
3247 A good question is why do we enable the tests for non-default formats? The
3248  answer is that if a non-default route is broken it is often because a bug
3249  was introduced in LyX and not because a document-specific change was made
3250  that is not supported by the route.
3251  In other words, there is a high signal/noise ratio in the export tests
3252  for some non-default formats.
3253
3254 \end_layout
3255
3256 \begin_layout Standard
3257 When a test or several tests fail, consider checking the files in the
3258 \begin_inset Flex Code
3259 status collapsed
3260
3261 \begin_layout Plain Layout
3262 Testing/Temporary/
3263 \end_layout
3264
3265 \end_inset
3266
3267  subdirectory of your build directory.
3268  In this subdirectory are three files: the file
3269 \begin_inset Flex Code
3270 status collapsed
3271
3272 \begin_layout Plain Layout
3273 LastTestsFailed.log
3274 \end_layout
3275
3276 \end_inset
3277
3278  simply lists the tests that failed on your last
3279 \begin_inset Flex Code
3280 status collapsed
3281
3282 \begin_layout Plain Layout
3283 ctest
3284 \end_layout
3285
3286 \end_inset
3287
3288  command; the
3289 \begin_inset Flex Code
3290 status collapsed
3291
3292 \begin_layout Plain Layout
3293 LastTest.log
3294 \end_layout
3295
3296 \end_inset
3297
3298  file contains the output from the tests (and often has details explaining
3299  why a test failed); and the
3300 \begin_inset Flex Code
3301 status collapsed
3302
3303 \begin_layout Plain Layout
3304 CTestCostData.txt
3305 \end_layout
3306
3307 \end_inset
3308
3309  file lists the times that it took to run the tests.
3310 \end_layout
3311
3312 \begin_layout Paragraph
3313 What action should you take if a test fails?
3314 \end_layout
3315
3316 \begin_layout Standard
3317 \paragraph_spacing single
3318 It is always good to check manually why something fails and if it passes
3319  if the PDF output is good.
3320 \end_layout
3321
3322 \begin_layout Itemize
3323 Generally, if a change breaks compilation for the target format (for the
3324  manuals pdf2) without solving some important other issue,
3325 \emph on
3326 fix or revert the commit
3327 \emph default
3328  that led to failure.
3329 \end_layout
3330
3331 \begin_layout Itemize
3332 If it is not possible to (immediately) fix the failure but there are reasons
3333  not to revert the commit (e.g.
3334  it fixes another more important issue),
3335 \emph on
3336 invert
3337 \emph default
3338  the failing test case (see
3339 \begin_inset CommandInset ref
3340 LatexCommand ref
3341 reference "par:Inverted-tests"
3342
3343 \end_inset
3344
3345 ).
3346 \end_layout
3347
3348 \begin_layout Itemize
3349 If an
3350 \emph on
3351 inverted
3352 \emph default
3353  test case fails because the export now works,
3354 \emph on
3355 uninvert
3356 \emph default
3357  the test by removing the pattern from the
3358 \begin_inset Quotes eld
3359 \end_inset
3360
3361 invertedTests
3362 \begin_inset Quotes erd
3363 \end_inset
3364
3365  file) (see
3366 \begin_inset CommandInset ref
3367 LatexCommand ref
3368 reference "par:Inverted-tests"
3369
3370 \end_inset
3371
3372 ).
3373 \end_layout
3374
3375 \begin_layout Itemize
3376 If the export did not fail previously but led to wrong output (PDF, say),
3377 \begin_inset Foot
3378 status collapsed
3379
3380 \begin_layout Plain Layout
3381 Non-failing test with wrong output should be labeledas
3382 \begin_inset Quotes eld
3383 \end_inset
3384
3385 unreliable:wrong_output
3386 \begin_inset Quotes erd
3387 \end_inset
3388
3389  (
3390 \begin_inset CommandInset ref
3391 LatexCommand ref
3392 reference "par:Unreliable-tests"
3393
3394 \end_inset
3395
3396 ).
3397 \end_layout
3398
3399 \end_inset
3400
3401  it is in fact an improvement when the test now fails.
3402
3403 \emph on
3404 Invert
3405 \emph default
3406  the failing test case (see
3407 \begin_inset CommandInset ref
3408 LatexCommand ref
3409 reference "par:Inverted-tests"
3410
3411 \end_inset
3412
3413 ).
3414 \end_layout
3415
3416 \begin_layout Itemize
3417 In case of tests failing due to missing requirements (tests labeled
3418 \begin_inset Quotes eld
3419 \end_inset
3420
3421 unreliable:nonstandard
3422 \begin_inset Quotes erd
3423 \end_inset
3424
3425  or testing on a system withonly a subset of TeXLive installed), ignore
3426  the failure, ask for someone else to run the test, or install the missing
3427  ressources and try again.
3428 \change_inserted 34634807 1486631183
3429
3430 \end_layout
3431
3432 \begin_layout Standard
3433
3434 \change_inserted 34634807 1486631268
3435 With TeXLive 2016, here are the resources which should be installed to avoid
3436  standard tests failure:
3437 \end_layout
3438
3439 \begin_layout Itemize
3440
3441 \change_inserted 34634807 1486631544
3442
3443 \family typewriter
3444 Rscript
3445 \family default
3446  is needed for literate programming, so
3447 \begin_inset CommandInset href
3448 LatexCommand href
3449 name "R"
3450 target "http://www.r-project.org"
3451
3452 \end_inset
3453
3454  should be installed;
3455 \end_layout
3456
3457 \begin_layout Itemize
3458
3459 \change_inserted 34634807 1487083795
3460
3461 \family typewriter
3462 \begin_inset CommandInset href
3463 LatexCommand href
3464 name "gnuplot"
3465 target "http://www.gnuplot.info/download.html"
3466
3467 \end_inset
3468
3469
3470 \family default
3471 scripts are needed for spreadsheet export;
3472 \end_layout
3473
3474 \begin_layout Itemize
3475
3476 \change_inserted 34634807 1487083980
3477
3478 \family typewriter
3479 lilypond-book
3480 \family default
3481  script should be installed, see the lilypond
3482 \begin_inset CommandInset href
3483 LatexCommand href
3484 name "download page"
3485 target "http://lilypond.org/download.html"
3486
3487 \end_inset
3488
3489 ;
3490 \end_layout
3491
3492 \begin_layout Itemize
3493
3494 \change_inserted 34634807 1486634133
3495
3496 \family typewriter
3497 \begin_inset CommandInset href
3498 LatexCommand href
3499 name "foiltex"
3500 target "https://www.ctan.org/pkg/foiltex"
3501
3502 \end_inset
3503
3504
3505 \family default
3506 is not part of the TeXLive distribution;
3507 \end_layout
3508
3509 \begin_layout Itemize
3510
3511 \change_inserted 34634807 1486631975
3512 LaTeX packages which are not in the
3513 \begin_inset Quotes eld
3514 \end_inset
3515
3516 collection-publishers
3517 \begin_inset Quotes erd
3518 \end_inset
3519
3520  TeXLive set are needed from editors of various papers and books:
3521 \end_layout
3522
3523 \begin_deeper
3524 \begin_layout Itemize
3525
3526 \change_inserted 34634807 1486634149
3527 Springer packages, see
3528 \begin_inset Flex URL
3529 status collapsed
3530
3531 \begin_layout Plain Layout
3532
3533 \change_inserted 34634807 1486633436
3534
3535 http://wiki.lyx.org/Examples/Springer
3536 \change_unchanged
3537
3538 \end_layout
3539
3540 \end_inset
3541
3542 ;
3543 \end_layout
3544
3545 \begin_layout Itemize
3546
3547 \change_inserted 34634807 1486634154
3548 Astronomy & Astrophysics, see
3549 \begin_inset Flex URL
3550 status collapsed
3551
3552 \begin_layout Plain Layout
3553
3554 \change_inserted 34634807 1486632086
3555
3556 http://www.aanda.org/author-information/latex-issues/texnical-background-informati
3557 on
3558 \change_unchanged
3559
3560 \end_layout
3561
3562 \end_inset
3563
3564 ;
3565 \end_layout
3566
3567 \begin_layout Itemize
3568
3569 \change_inserted 34634807 1486721678
3570 ACM files for
3571 \begin_inset CommandInset href
3572 LatexCommand href
3573 name "ACM-SIGS"
3574 target "http://www.acm.org/sigs/publications/acm_proc_article-sp.cls"
3575
3576 \end_inset
3577
3578 ,
3579 \begin_inset CommandInset href
3580 LatexCommand href
3581 name "ACM-sigplan"
3582 target "http://drupal.sigplan.org/sites/default/files/sigplanconf.cls"
3583
3584 \end_inset
3585
3586  and
3587 \begin_inset CommandInset href
3588 LatexCommand href
3589 name "ACM-siggraph"
3590 target "http://www.siggraph.org/sites/default/files/acmsiggraph.zip"
3591
3592 \end_inset
3593
3594  template files;
3595 \end_layout
3596
3597 \begin_layout Itemize
3598
3599 \change_inserted 34634807 1486721793
3600 American Economic Association, see
3601 \begin_inset CommandInset href
3602 LatexCommand href
3603 name "AEA"
3604 target "https://wiki.lyx.org/Examples/AEA"
3605
3606 \end_inset
3607
3608 ;
3609 \end_layout
3610
3611 \begin_layout Itemize
3612
3613 \change_inserted 34634807 1486735769
3614 American Geophysical Union, the template changed in 2016, see
3615 \begin_inset CommandInset href
3616 LatexCommand href
3617 name "AGU2015"
3618 target "http://publications.agu.org/files/2015/10/agutex2015.zip"
3619
3620 \end_inset
3621
3622  and
3623 \begin_inset CommandInset href
3624 LatexCommand href
3625 name "AGU2016"
3626 target "https://publications.agu.org/files/2016/03/AGUJournal_Feb18_2016.zip"
3627
3628 \end_inset
3629
3630 ;
3631 \end_layout
3632
3633 \begin_layout Itemize
3634
3635 \change_inserted 34634807 1486735844
3636 Institute of Optics, see
3637 \begin_inset CommandInset href
3638 LatexCommand href
3639 name "IOP"
3640 target "ftp://ftp.iop.org/pub/journals/ioplatexguidelines.tar.gz"
3641
3642 \end_inset
3643
3644 ;
3645 \end_layout
3646
3647 \begin_layout Itemize
3648
3649 \change_inserted 34634807 1486747241
3650 International Union of Cristallography, see
3651 \begin_inset CommandInset href
3652 LatexCommand href
3653 name "IUCr"
3654 target "http://wiki.lyx.org/Layouts/IUCr"
3655
3656 \end_inset
3657
3658 ;
3659 \end_layout
3660
3661 \begin_layout Itemize
3662
3663 \change_inserted 34634807 1486748022
3664 Journal of the Acoustical Society of America, see
3665 \begin_inset CommandInset href
3666 LatexCommand href
3667 name "JASA"
3668 target "http://wiki.lyx.org/Layouts/JASATeX"
3669
3670 \end_inset
3671
3672 ;
3673 \end_layout
3674
3675 \begin_layout Itemize
3676
3677 \change_inserted 34634807 1486748960
3678 RJournal, see
3679 \begin_inset CommandInset href
3680 LatexCommand href
3681 name "RJournal"
3682 target "https://journal.r-project.org/submissions.html"
3683
3684 \end_inset
3685
3686 ;
3687 \end_layout
3688
3689 \begin_layout Itemize
3690
3691 \change_inserted 34634807 1486749098
3692 Econometrica, see
3693 \begin_inset CommandInset href
3694 LatexCommand href
3695 name "ecta"
3696 target "https://wiki.lyx.org/Examples/Econometrica"
3697
3698 \end_inset
3699
3700 .
3701 \end_layout
3702
3703 \end_deeper
3704 \begin_layout Paragraph
3705 \begin_inset CommandInset label
3706 LatexCommand label
3707 name "par:Inverted-tests"
3708
3709 \end_inset
3710
3711 Inverted tests
3712 \end_layout
3713
3714 \begin_layout Standard
3715 Test cases whose name matches a pattern in the file
3716 \begin_inset Flex Code
3717 status collapsed
3718
3719 \begin_layout Plain Layout
3720 development/autotests/invertedTests
3721 \end_layout
3722
3723 \end_inset
3724
3725  get the label
3726 \emph on
3727 inverted
3728 \emph default
3729 .
3730  They get also the test property
3731 \begin_inset Flex Code
3732 status collapsed
3733
3734 \begin_layout Plain Layout
3735 WILL_FAIL
3736 \end_layout
3737
3738 \end_inset
3739
3740 , i.e.
3741  they are reported as failing if the export works without error
3742 \begin_inset Flex URL
3743 status collapsed
3744
3745 \begin_layout Plain Layout
3746
3747 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3748 \end_layout
3749
3750 \end_inset
3751
3752 .
3753 \end_layout
3754
3755 \begin_layout Standard
3756 Add failing cases to this file, if they cannot be solved
3757 \begin_inset Quotes eld
3758 \end_inset
3759
3760 immediately
3761 \begin_inset Quotes erd
3762 \end_inset
3763
3764  but it is expected that the export will work in a foreseeable future, e.g.
3765  low priority issues like failures to export to a non-target format (for
3766  the manuals everything except pdf2).
3767 \end_layout
3768
3769 \begin_layout Standard
3770 The following sublabels are currently present in
3771 \begin_inset Flex Code
3772 status collapsed
3773
3774 \begin_layout Plain Layout
3775 invertedTests
3776 \end_layout
3777
3778 \end_inset
3779
3780 :
3781 \end_layout
3782
3783 \begin_layout Description
3784 todo test failures that require attention:
3785 \end_layout
3786
3787 \begin_deeper
3788 \begin_layout Itemize
3789 minor issues to explore and properly sort later,
3790 \end_layout
3791
3792 \begin_layout Itemize
3793 easyfix issues,
3794 \end_layout
3795
3796 \begin_layout Itemize
3797 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3798 \end_layout
3799
3800 \end_deeper
3801 \begin_layout Description
3802 lyxbugs LyX bugs with a Trac number.
3803 \end_layout
3804
3805 \begin_layout Description
3806 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3807 \end_layout
3808
3809 \begin_deeper
3810 \begin_layout Standard
3811 "Wontfix" if demonstrating correct use and OK in the default output format.
3812 \end_layout
3813
3814 \end_deeper
3815 \begin_layout Description
3816 texissues Export fails due to LaTeX limitations like non-ASCII characters
3817  in verbatim or listings, incompatible packages, ...
3818 \end_layout
3819
3820 \begin_deeper
3821 \begin_layout Standard
3822 "Wontfix" if documents demonstrate correct use in the default output format:
3823 \end_layout
3824
3825 \begin_layout Itemize
3826 If the source can be made more robust without becoming "hackish", fix the
3827  source,
3828 \end_layout
3829
3830 \begin_layout Itemize
3831 if LyX could be enhanced to care for a permanent TeX limitation, file a
3832  ticket at trac and add a pattern under lyxbugs,
3833 \end_layout
3834
3835 \begin_layout Itemize
3836 otherwise, add a pattern here.
3837 \end_layout
3838
3839 \end_deeper
3840 \begin_layout Description
3841 attic Documents in the attic (kept for reference and format conversion test).
3842  Usually
3843 \begin_inset Quotes eld
3844 \end_inset
3845
3846 Wontfix
3847 \begin_inset Quotes erd
3848 \end_inset
3849
3850 .
3851 \end_layout
3852
3853 \begin_layout Subparagraph
3854 suspended tests
3855 \end_layout
3856
3857 \begin_layout Standard
3858 Test cases whose name additionally matches a pattern in the file
3859 \begin_inset Flex Code
3860 status collapsed
3861
3862 \begin_layout Plain Layout
3863 development/autotests/suspendedTests
3864 \end_layout
3865
3866 \end_inset
3867
3868  get the label
3869 \emph on
3870 suspended
3871 \emph default
3872 (instead of
3873 \emph on
3874 export
3875 \emph default
3876 and
3877 \emph on
3878  inverted
3879 \emph default
3880 ).
3881  This means they are not executed using
3882 \begin_inset Flex Code
3883 status collapsed
3884
3885 \begin_layout Plain Layout
3886 ctest -L export
3887 \end_layout
3888
3889 \end_inset
3890
3891  or
3892 \begin_inset Flex Code
3893 status collapsed
3894
3895 \begin_layout Plain Layout
3896 ctest -L inverted
3897 \end_layout
3898
3899 \end_inset
3900
3901 .
3902  However, they also get the test property
3903 \begin_inset Flex Code
3904 status collapsed
3905
3906 \begin_layout Plain Layout
3907 WILL_FAIL
3908 \end_layout
3909
3910 \end_inset
3911
3912 , i.e.
3913  they are reported as failing if the export works without error.
3914  From time to time they still have to be checked using
3915 \begin_inset Flex Code
3916 status collapsed
3917
3918 \begin_layout Plain Layout
3919 ctest -L suspended
3920 \end_layout
3921
3922 \end_inset
3923
3924 .
3925 \end_layout
3926
3927 \begin_layout Standard
3928 These tests are suspended, because the export fails for known reasons which
3929  cannot ATM be resolved.
3930  But it is expected the reason might disappear in the future.
3931  Be it new TL or better handling in \SpecialChar LyX
3932 .
3933 \end_layout
3934
3935 \begin_layout Standard
3936 For ctest commands without the
3937 \begin_inset Flex Code
3938 status collapsed
3939
3940 \begin_layout Plain Layout
3941 -L
3942 \end_layout
3943
3944 \end_inset
3945
3946  parameter nothing changes.
3947  Suspended or not, tests will be executed depending only on the selecting
3948  regular expression given to the ctest command (see
3949 \begin_inset CommandInset ref
3950 LatexCommand ref
3951 reference "par:ctest-options"
3952
3953 \end_inset
3954
3955 ).
3956 \end_layout
3957
3958 \begin_layout Paragraph
3959 \begin_inset CommandInset label
3960 LatexCommand label
3961 name "par:Unreliable-tests"
3962
3963 \end_inset
3964
3965 Unreliable tests
3966 \end_layout
3967
3968 \begin_layout Standard
3969 Test cases whose name matches a pattern in the file
3970 \begin_inset Flex Code
3971 status collapsed
3972
3973 \begin_layout Plain Layout
3974 development/autotests/unreliableTests
3975 \end_layout
3976
3977 \end_inset
3978
3979  get the label
3980 \emph on
3981 unreliable
3982 \emph default
3983 .
3984 \end_layout
3985
3986 \begin_layout Standard
3987 These tests are not executed using
3988 \begin_inset Flex Code
3989 status collapsed
3990
3991 \begin_layout Plain Layout
3992 ctest -L export
3993 \end_layout
3994
3995 \end_inset
3996
3997  or
3998 \begin_inset Flex Code
3999 status collapsed
4000
4001 \begin_layout Plain Layout
4002 ctest -L inverted
4003 \end_layout
4004
4005 \end_inset
4006
4007 .
4008
4009 \end_layout
4010
4011 \begin_layout Standard
4012 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
4013  or pass but should rather fail (wrong output).
4014
4015 \begin_inset Note Note
4016 status collapsed
4017
4018 \begin_layout Plain Layout
4019 *invalid* tests (wrong output) are not *unreliable*.
4020  # Use "unfit" or "unapplicable" as better label and name of pattern file?
4021
4022 \end_layout
4023
4024 \end_inset
4025
4026
4027 \end_layout
4028
4029 \begin_layout Standard
4030 The following sublabels are currently present in
4031 \begin_inset Flex Code
4032 status collapsed
4033
4034 \begin_layout Plain Layout
4035 unreliableTests
4036 \end_layout
4037
4038 \end_inset
4039
4040 :
4041 \end_layout
4042
4043 \begin_layout Description
4044 nonstandard Documents with additional requirements, e.g.
4045  a class or package file not in TeXLive.
4046
4047 \begin_inset Note Note
4048 status open
4049
4050 \begin_layout Plain Layout
4051 TODO: rename to
4052 \begin_inset Quotes eld
4053 \end_inset
4054
4055 extra
4056 \begin_inset Quotes erd
4057 \end_inset
4058
4059  or
4060 \begin_inset Quotes eld
4061 \end_inset
4062
4063 exotic
4064 \begin_inset Quotes erd
4065 \end_inset
4066
4067 ?
4068 \end_layout
4069
4070 \end_inset
4071
4072
4073 \end_layout
4074
4075 \begin_layout Description
4076 erratic Tests depending on local configuration or the phase of the moon.
4077
4078 \end_layout
4079
4080 \begin_layout Description
4081 varying_versions Test depending on TeX distribution, package versions or
4082  OS.
4083 \end_layout
4084
4085 \begin_layout Description
4086 wrong
4087 \begin_inset space ~
4088 \end_inset
4089
4090 output Export does not fail but the resulting document has (undetected)
4091  errors.
4092 \end_layout
4093
4094 \begin_deeper
4095 \begin_layout Standard
4096 \paragraph_spacing single
4097 \begin_inset Note Note
4098 status open
4099
4100 \begin_layout Plain Layout
4101 \paragraph_spacing single
4102 These tests are in a strict sense not unreliable but
4103 \emph on
4104 invalid
4105 \emph default
4106  (not measuring what they should measure).
4107 \end_layout
4108
4109 \end_inset
4110
4111
4112 \end_layout
4113
4114 \end_deeper
4115 \begin_layout Paragraph
4116 \begin_inset CommandInset label
4117 LatexCommand label
4118 name "par:Export-test-filtering"
4119
4120 \end_inset
4121
4122 Export test filtering
4123 \end_layout
4124
4125 \begin_layout Standard
4126 The assignment of a label to a test is controlled by a set of files with
4127  regular expressions that are matched against the test names.
4128 \end_layout
4129
4130 \begin_layout Description
4131 ignoredTests (small file)
4132 \begin_inset Newline newline
4133 \end_inset
4134
4135 Tests selected here are withdrawn in the configuration step (cf.
4136
4137 \begin_inset CommandInset ref
4138 LatexCommand ref
4139 reference "par:Configuring-ctests"
4140
4141 \end_inset
4142
4143 ).
4144 \end_layout
4145
4146 \begin_deeper
4147 \begin_layout Labeling
4148 \labelwidthstring 00.00.0000
4149 Input Test of any export combination
4150 \end_layout
4151
4152 \begin_layout Labeling
4153 \labelwidthstring 00.00.0000
4154 Output Stop if tests not selected here
4155 \end_layout
4156
4157 \end_deeper
4158 \begin_layout Description
4159 unreliableTests: Tests selected pass or fail dependent on the system where
4160  the test is run.
4161  Selected tests gain the label 'unreliable'.
4162 \end_layout
4163
4164 \begin_deeper
4165 \begin_layout Labeling
4166 \labelwidthstring 00.00.0000
4167 Input Each test which passed 'ignoredTests'
4168 \end_layout
4169
4170 \begin_layout Labeling
4171 \labelwidthstring 00.00.0000
4172 Output Stop if test selected, gain label 'unreliable'.
4173 \end_layout
4174
4175 \end_deeper
4176 \begin_layout Description
4177 invertedTests
4178 \begin_inset space \space{}
4179 \end_inset
4180
4181
4182 \end_layout
4183
4184 \begin_deeper
4185 \begin_layout Labeling
4186 \labelwidthstring 00.00.0000
4187 Input Each test which passed 'unreliableTests'
4188 \end_layout
4189
4190 \begin_layout Labeling
4191 \labelwidthstring 00.00.0000
4192 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
4193  tests are reported as failing if the export works without error.) If no
4194  subselection applies, gain labels 'export' and 'inverted'.
4195 \end_layout
4196
4197 \begin_layout Standard
4198 The following filter perfoms a subselection of 'invertedTests':
4199 \end_layout
4200
4201 \begin_layout Description
4202 suspendedTests Tests selected here gain the label 'suspended' but _not_
4203  'export' or 'inverted', although in ctest they remain inverted.
4204  ('ctest' knows only 'inverted' or not, labels are used only for test selection)
4205 \end_layout
4206
4207 \begin_deeper
4208 \begin_layout Labeling
4209 \labelwidthstring 00.00.0000
4210 Input Each test selected by 'invertedTests'
4211 \end_layout
4212
4213 \begin_layout Labeling
4214 \labelwidthstring 00.00.0000
4215 Output Selected test gains label 'suspended'.
4216
4217 \end_layout
4218
4219 \end_deeper
4220 \end_deeper
4221 \begin_layout Standard
4222 The following table may clarify label assignement
4223 \end_layout
4224
4225 \begin_layout Standard
4226 \begin_inset Tabular
4227 <lyxtabular version="3" rows="7" columns="9">
4228 <features tabularvalignment="middle">
4229 <column alignment="left" valignment="top" width="0pt">
4230 <column alignment="left" valignment="top" width="0pt">
4231 <column alignment="left" valignment="top" width="0pt">
4232 <column alignment="left" valignment="top" width="0pt">
4233 <column alignment="center" valignment="top">
4234 <column alignment="center" valignment="top">
4235 <column alignment="center" valignment="top">
4236 <column alignment="center" valignment="top">
4237 <column alignment="center" valignment="top">
4238 <row>
4239 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4240 \begin_inset Text
4241
4242 \begin_layout Plain Layout
4243 Test matching pattern in file:
4244 \end_layout
4245
4246 \end_inset
4247 </cell>
4248 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4249 \begin_inset Text
4250
4251 \begin_layout Plain Layout
4252
4253 \end_layout
4254
4255 \end_inset
4256 </cell>
4257 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4258 \begin_inset Text
4259
4260 \begin_layout Plain Layout
4261
4262 \end_layout
4263
4264 \end_inset
4265 </cell>
4266 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4267 \begin_inset Text
4268
4269 \begin_layout Plain Layout
4270
4271 \end_layout
4272
4273 \end_inset
4274 </cell>
4275 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4276 \begin_inset Text
4277
4278 \begin_layout Plain Layout
4279 Assigned label
4280 \end_layout
4281
4282 \end_inset
4283 </cell>
4284 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4285 \begin_inset Text
4286
4287 \begin_layout Plain Layout
4288
4289 \end_layout
4290
4291 \end_inset
4292 </cell>
4293 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4294 \begin_inset Text
4295
4296 \begin_layout Plain Layout
4297
4298 \end_layout
4299
4300 \end_inset
4301 </cell>
4302 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4303 \begin_inset Text
4304
4305 \begin_layout Plain Layout
4306
4307 \end_layout
4308
4309 \end_inset
4310 </cell>
4311 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4312 \begin_inset Text
4313
4314 \begin_layout Plain Layout
4315 test property
4316 \end_layout
4317
4318 \end_inset
4319 </cell>
4320 </row>
4321 <row>
4322 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4323 \begin_inset Text
4324
4325 \begin_layout Plain Layout
4326 ignoredTests
4327 \end_layout
4328
4329 \end_inset
4330 </cell>
4331 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4332 \begin_inset Text
4333
4334 \begin_layout Plain Layout
4335 unreliableTests
4336 \end_layout
4337
4338 \end_inset
4339 </cell>
4340 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4341 \begin_inset Text
4342
4343 \begin_layout Plain Layout
4344 invertedTests
4345 \end_layout
4346
4347 \end_inset
4348 </cell>
4349 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4350 \begin_inset Text
4351
4352 \begin_layout Plain Layout
4353 suspendedTests
4354 \end_layout
4355
4356 \end_inset
4357 </cell>
4358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4359 \begin_inset Text
4360
4361 \begin_layout Plain Layout
4362 export
4363 \end_layout
4364
4365 \end_inset
4366 </cell>
4367 <cell alignment="center" valignment="top" topline="true" usebox="none">
4368 \begin_inset Text
4369
4370 \begin_layout Plain Layout
4371 unreliable
4372 \end_layout
4373
4374 \end_inset
4375 </cell>
4376 <cell alignment="center" valignment="top" topline="true" usebox="none">
4377 \begin_inset Text
4378
4379 \begin_layout Plain Layout
4380 inverted
4381 \end_layout
4382
4383 \end_inset
4384 </cell>
4385 <cell alignment="center" valignment="top" topline="true" usebox="none">
4386 \begin_inset Text
4387
4388 \begin_layout Plain Layout
4389 suspended
4390 \end_layout
4391
4392 \end_inset
4393 </cell>
4394 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4395 \begin_inset Text
4396
4397 \begin_layout Plain Layout
4398
4399 \end_layout
4400
4401 \end_inset
4402 </cell>
4403 </row>
4404 <row>
4405 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4406 \begin_inset Text
4407
4408 \begin_layout Plain Layout
4409 Yes
4410 \end_layout
4411
4412 \end_inset
4413 </cell>
4414 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4415 \begin_inset Text
4416
4417 \begin_layout Plain Layout
4418 -
4419 \end_layout
4420
4421 \end_inset
4422 </cell>
4423 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4424 \begin_inset Text
4425
4426 \begin_layout Plain Layout
4427 -
4428 \end_layout
4429
4430 \end_inset
4431 </cell>
4432 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4433 \begin_inset Text
4434
4435 \begin_layout Plain Layout
4436 -
4437 \end_layout
4438
4439 \end_inset
4440 </cell>
4441 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4442 \begin_inset Text
4443
4444 \begin_layout Plain Layout
4445 -
4446 \end_layout
4447
4448 \end_inset
4449 </cell>
4450 <cell alignment="center" valignment="top" topline="true" usebox="none">
4451 \begin_inset Text
4452
4453 \begin_layout Plain Layout
4454
4455 \end_layout
4456
4457 \end_inset
4458 </cell>
4459 <cell alignment="center" valignment="top" topline="true" usebox="none">
4460 \begin_inset Text
4461
4462 \begin_layout Plain Layout
4463 -
4464 \end_layout
4465
4466 \end_inset
4467 </cell>
4468 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4469 \begin_inset Text
4470
4471 \begin_layout Plain Layout
4472 -
4473 \end_layout
4474
4475 \end_inset
4476 </cell>
4477 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4478 \begin_inset Text
4479
4480 \begin_layout Plain Layout
4481
4482 \end_layout
4483
4484 \end_inset
4485 </cell>
4486 </row>
4487 <row>
4488 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4489 \begin_inset Text
4490
4491 \begin_layout Plain Layout
4492 No
4493 \end_layout
4494
4495 \end_inset
4496 </cell>
4497 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4498 \begin_inset Text
4499
4500 \begin_layout Plain Layout
4501 Yes
4502 \end_layout
4503
4504 \end_inset
4505 </cell>
4506 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4507 \begin_inset Text
4508
4509 \begin_layout Plain Layout
4510 -
4511 \end_layout
4512
4513 \end_inset
4514 </cell>
4515 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4516 \begin_inset Text
4517
4518 \begin_layout Plain Layout
4519 -
4520 \end_layout
4521
4522 \end_inset
4523 </cell>
4524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4525 \begin_inset Text
4526
4527 \begin_layout Plain Layout
4528 -
4529 \end_layout
4530
4531 \end_inset
4532 </cell>
4533 <cell alignment="center" valignment="top" topline="true" usebox="none">
4534 \begin_inset Text
4535
4536 \begin_layout Plain Layout
4537 +
4538 \end_layout
4539
4540 \end_inset
4541 </cell>
4542 <cell alignment="center" valignment="top" topline="true" usebox="none">
4543 \begin_inset Text
4544
4545 \begin_layout Plain Layout
4546 -
4547 \end_layout
4548
4549 \end_inset
4550 </cell>
4551 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4552 \begin_inset Text
4553
4554 \begin_layout Plain Layout
4555 -
4556 \end_layout
4557
4558 \end_inset
4559 </cell>
4560 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4561 \begin_inset Text
4562
4563 \begin_layout Plain Layout
4564
4565 \end_layout
4566
4567 \end_inset
4568 </cell>
4569 </row>
4570 <row>
4571 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4572 \begin_inset Text
4573
4574 \begin_layout Plain Layout
4575
4576 \end_layout
4577
4578 \end_inset
4579 </cell>
4580 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4581 \begin_inset Text
4582
4583 \begin_layout Plain Layout
4584 No
4585 \end_layout
4586
4587 \end_inset
4588 </cell>
4589 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4590 \begin_inset Text
4591
4592 \begin_layout Plain Layout
4593 Yes
4594 \end_layout
4595
4596 \end_inset
4597 </cell>
4598 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4599 \begin_inset Text
4600
4601 \begin_layout Plain Layout
4602 Yes
4603 \end_layout
4604
4605 \end_inset
4606 </cell>
4607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4608 \begin_inset Text
4609
4610 \begin_layout Plain Layout
4611 -
4612 \end_layout
4613
4614 \end_inset
4615 </cell>
4616 <cell alignment="center" valignment="top" topline="true" usebox="none">
4617 \begin_inset Text
4618
4619 \begin_layout Plain Layout
4620 -
4621 \end_layout
4622
4623 \end_inset
4624 </cell>
4625 <cell alignment="center" valignment="top" topline="true" usebox="none">
4626 \begin_inset Text
4627
4628 \begin_layout Plain Layout
4629 -
4630 \end_layout
4631
4632 \end_inset
4633 </cell>
4634 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4635 \begin_inset Text
4636
4637 \begin_layout Plain Layout
4638 +
4639 \end_layout
4640
4641 \end_inset
4642 </cell>
4643 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4644 \begin_inset Text
4645
4646 \begin_layout Plain Layout
4647 WILL_FAIL
4648 \end_layout
4649
4650 \end_inset
4651 </cell>
4652 </row>
4653 <row>
4654 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4655 \begin_inset Text
4656
4657 \begin_layout Plain Layout
4658
4659 \end_layout
4660
4661 \end_inset
4662 </cell>
4663 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4664 \begin_inset Text
4665
4666 \begin_layout Plain Layout
4667
4668 \end_layout
4669
4670 \end_inset
4671 </cell>
4672 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4673 \begin_inset Text
4674
4675 \begin_layout Plain Layout
4676
4677 \end_layout
4678
4679 \end_inset
4680 </cell>
4681 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4682 \begin_inset Text
4683
4684 \begin_layout Plain Layout
4685 No
4686 \end_layout
4687
4688 \end_inset
4689 </cell>
4690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4691 \begin_inset Text
4692
4693 \begin_layout Plain Layout
4694 +
4695 \end_layout
4696
4697 \end_inset
4698 </cell>
4699 <cell alignment="center" valignment="top" topline="true" usebox="none">
4700 \begin_inset Text
4701
4702 \begin_layout Plain Layout
4703 -
4704 \end_layout
4705
4706 \end_inset
4707 </cell>
4708 <cell alignment="center" valignment="top" topline="true" usebox="none">
4709 \begin_inset Text
4710
4711 \begin_layout Plain Layout
4712 +
4713 \end_layout
4714
4715 \end_inset
4716 </cell>
4717 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4718 \begin_inset Text
4719
4720 \begin_layout Plain Layout
4721 -
4722 \end_layout
4723
4724 \end_inset
4725 </cell>
4726 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4727 \begin_inset Text
4728
4729 \begin_layout Plain Layout
4730 WILL_FAIL
4731 \end_layout
4732
4733 \end_inset
4734 </cell>
4735 </row>
4736 <row>
4737 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4738 \begin_inset Text
4739
4740 \begin_layout Plain Layout
4741
4742 \end_layout
4743
4744 \end_inset
4745 </cell>
4746 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4747 \begin_inset Text
4748
4749 \begin_layout Plain Layout
4750
4751 \end_layout
4752
4753 \end_inset
4754 </cell>
4755 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4756 \begin_inset Text
4757
4758 \begin_layout Plain Layout
4759 No
4760 \end_layout
4761
4762 \end_inset
4763 </cell>
4764 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4765 \begin_inset Text
4766
4767 \begin_layout Plain Layout
4768 -
4769 \end_layout
4770
4771 \end_inset
4772 </cell>
4773 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4774 \begin_inset Text
4775
4776 \begin_layout Plain Layout
4777 +
4778 \end_layout
4779
4780 \end_inset
4781 </cell>
4782 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4783 \begin_inset Text
4784
4785 \begin_layout Plain Layout
4786 -
4787 \end_layout
4788
4789 \end_inset
4790 </cell>
4791 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4792 \begin_inset Text
4793
4794 \begin_layout Plain Layout
4795 -
4796 \end_layout
4797
4798 \end_inset
4799 </cell>
4800 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4801 \begin_inset Text
4802
4803 \begin_layout Plain Layout
4804 -
4805 \end_layout
4806
4807 \end_inset
4808 </cell>
4809 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4810 \begin_inset Text
4811
4812 \begin_layout Plain Layout
4813
4814 \end_layout
4815
4816 \end_inset
4817 </cell>
4818 </row>
4819 </lyxtabular>
4820
4821 \end_inset
4822
4823
4824 \end_layout
4825
4826 \begin_layout Standard
4827 \begin_inset Note Note
4828 status open
4829
4830 \begin_layout Plain Layout
4831 Without the
4832 \begin_inset Quotes eld
4833 \end_inset
4834
4835 suspendedTests
4836 \begin_inset Quotes erd
4837 \end_inset
4838
4839  filter, this would be far less complicated:
4840 \end_layout
4841
4842 \begin_layout Plain Layout
4843 \begin_inset Tabular
4844 <lyxtabular version="3" rows="6" columns="7">
4845 <features tabularvalignment="middle">
4846 <column alignment="left" valignment="top" width="0pt">
4847 <column alignment="left" valignment="top" width="0pt">
4848 <column alignment="left" valignment="top" width="0pt">
4849 <column alignment="center" valignment="top">
4850 <column alignment="center" valignment="top">
4851 <column alignment="center" valignment="top">
4852 <column alignment="center" valignment="top">
4853 <row>
4854 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4855 \begin_inset Text
4856
4857 \begin_layout Plain Layout
4858 Test matching pattern in file:
4859 \end_layout
4860
4861 \end_inset
4862 </cell>
4863 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4864 \begin_inset Text
4865
4866 \begin_layout Plain Layout
4867
4868 \end_layout
4869
4870 \end_inset
4871 </cell>
4872 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4873 \begin_inset Text
4874
4875 \begin_layout Plain Layout
4876
4877 \end_layout
4878
4879 \end_inset
4880 </cell>
4881 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4882 \begin_inset Text
4883
4884 \begin_layout Plain Layout
4885 Label
4886 \end_layout
4887
4888 \end_inset
4889 </cell>
4890 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4891 \begin_inset Text
4892
4893 \begin_layout Plain Layout
4894
4895 \end_layout
4896
4897 \end_inset
4898 </cell>
4899 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4900 \begin_inset Text
4901
4902 \begin_layout Plain Layout
4903
4904 \end_layout
4905
4906 \end_inset
4907 </cell>
4908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4909 \begin_inset Text
4910
4911 \begin_layout Plain Layout
4912 test property
4913 \end_layout
4914
4915 \end_inset
4916 </cell>
4917 </row>
4918 <row>
4919 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4920 \begin_inset Text
4921
4922 \begin_layout Plain Layout
4923 ignoredTests
4924 \end_layout
4925
4926 \end_inset
4927 </cell>
4928 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4929 \begin_inset Text
4930
4931 \begin_layout Plain Layout
4932 unreliableTests
4933 \end_layout
4934
4935 \end_inset
4936 </cell>
4937 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4938 \begin_inset Text
4939
4940 \begin_layout Plain Layout
4941 invertedTests
4942 \end_layout
4943
4944 \end_inset
4945 </cell>
4946 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4947 \begin_inset Text
4948
4949 \begin_layout Plain Layout
4950 export
4951 \end_layout
4952
4953 \end_inset
4954 </cell>
4955 <cell alignment="center" valignment="top" topline="true" usebox="none">
4956 \begin_inset Text
4957
4958 \begin_layout Plain Layout
4959 unreliable
4960 \end_layout
4961
4962 \end_inset
4963 </cell>
4964 <cell alignment="center" valignment="top" topline="true" usebox="none">
4965 \begin_inset Text
4966
4967 \begin_layout Plain Layout
4968 inverted
4969 \end_layout
4970
4971 \end_inset
4972 </cell>
4973 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4974 \begin_inset Text
4975
4976 \begin_layout Plain Layout
4977
4978 \end_layout
4979
4980 \end_inset
4981 </cell>
4982 </row>
4983 <row>
4984 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4985 \begin_inset Text
4986
4987 \begin_layout Plain Layout
4988 Yes
4989 \end_layout
4990
4991 \end_inset
4992 </cell>
4993 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4994 \begin_inset Text
4995
4996 \begin_layout Plain Layout
4997 -
4998 \end_layout
4999
5000 \end_inset
5001 </cell>
5002 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
5003 \begin_inset Text
5004
5005 \begin_layout Plain Layout
5006 -
5007 \end_layout
5008
5009 \end_inset
5010 </cell>
5011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5012 \begin_inset Text
5013
5014 \begin_layout Plain Layout
5015 -
5016 \end_layout
5017
5018 \end_inset
5019 </cell>
5020 <cell alignment="center" valignment="top" topline="true" usebox="none">
5021 \begin_inset Text
5022
5023 \begin_layout Plain Layout
5024
5025 \end_layout
5026
5027 \end_inset
5028 </cell>
5029 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
5030 \begin_inset Text
5031
5032 \begin_layout Plain Layout
5033 -
5034 \end_layout
5035
5036 \end_inset
5037 </cell>
5038 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
5039 \begin_inset Text
5040
5041 \begin_layout Plain Layout
5042
5043 \end_layout
5044
5045 \end_inset
5046 </cell>
5047 </row>
5048 <row>
5049 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
5050 \begin_inset Text
5051
5052 \begin_layout Plain Layout
5053 No
5054 \end_layout
5055
5056 \end_inset
5057 </cell>
5058 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
5059 \begin_inset Text
5060
5061 \begin_layout Plain Layout
5062 Yes
5063 \end_layout
5064
5065 \end_inset
5066 </cell>
5067 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
5068 \begin_inset Text
5069
5070 \begin_layout Plain Layout
5071 -
5072 \end_layout
5073
5074 \end_inset
5075 </cell>
5076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5077 \begin_inset Text
5078
5079 \begin_layout Plain Layout
5080 -
5081 \end_layout
5082
5083 \end_inset
5084 </cell>
5085 <cell alignment="center" valignment="top" topline="true" usebox="none">
5086 \begin_inset Text
5087
5088 \begin_layout Plain Layout
5089 +
5090 \end_layout
5091
5092 \end_inset
5093 </cell>
5094 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
5095 \begin_inset Text
5096
5097 \begin_layout Plain Layout
5098 -
5099 \end_layout
5100
5101 \end_inset
5102 </cell>
5103 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
5104 \begin_inset Text
5105
5106 \begin_layout Plain Layout
5107
5108 \end_layout
5109
5110 \end_inset
5111 </cell>
5112 </row>
5113 <row>
5114 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
5115 \begin_inset Text
5116
5117 \begin_layout Plain Layout
5118
5119 \end_layout
5120
5121 \end_inset
5122 </cell>
5123 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
5124 \begin_inset Text
5125
5126 \begin_layout Plain Layout
5127 No
5128 \end_layout
5129
5130 \end_inset
5131 </cell>
5132 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
5133 \begin_inset Text
5134
5135 \begin_layout Plain Layout
5136 Yes
5137 \end_layout
5138
5139 \end_inset
5140 </cell>
5141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5142 \begin_inset Text
5143
5144 \begin_layout Plain Layout
5145 +
5146 \end_layout
5147
5148 \end_inset
5149 </cell>
5150 <cell alignment="center" valignment="top" topline="true" usebox="none">
5151 \begin_inset Text
5152
5153 \begin_layout Plain Layout
5154 -
5155 \end_layout
5156
5157 \end_inset
5158 </cell>
5159 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
5160 \begin_inset Text
5161
5162 \begin_layout Plain Layout
5163 +
5164 \end_layout
5165
5166 \end_inset
5167 </cell>
5168 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
5169 \begin_inset Text
5170
5171 \begin_layout Plain Layout
5172 WILL_FAIL
5173 \end_layout
5174
5175 \end_inset
5176 </cell>
5177 </row>
5178 <row>
5179 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
5180 \begin_inset Text
5181
5182 \begin_layout Plain Layout
5183
5184 \end_layout
5185
5186 \end_inset
5187 </cell>
5188 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
5189 \begin_inset Text
5190
5191 \begin_layout Plain Layout
5192
5193 \end_layout
5194
5195 \end_inset
5196 </cell>
5197 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
5198 \begin_inset Text
5199
5200 \begin_layout Plain Layout
5201 No
5202 \end_layout
5203
5204 \end_inset
5205 </cell>
5206 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
5207 \begin_inset Text
5208
5209 \begin_layout Plain Layout
5210 +
5211 \end_layout
5212
5213 \end_inset
5214 </cell>
5215 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
5216 \begin_inset Text
5217
5218 \begin_layout Plain Layout
5219 -
5220 \end_layout
5221
5222 \end_inset
5223 </cell>
5224 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
5225 \begin_inset Text
5226
5227 \begin_layout Plain Layout
5228 -
5229 \end_layout
5230
5231 \end_inset
5232 </cell>
5233 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
5234 \begin_inset Text
5235
5236 \begin_layout Plain Layout
5237
5238 \end_layout
5239
5240 \end_inset
5241 </cell>
5242 </row>
5243 </lyxtabular>
5244
5245 \end_inset
5246
5247
5248 \end_layout
5249
5250 \end_inset
5251
5252
5253 \end_layout
5254
5255 \begin_layout Subsubsection
5256 check_load tests
5257 \end_layout
5258
5259 \begin_layout Standard
5260 These tests check whether a .lyx file loads without any terminal messages.
5261  They correspond to the manual operations of simply opening a .lyx file on
5262  the terminal, exiting LyX once the file is loaded, and then checking whether
5263  there is any output from the terminal.
5264  These tests are useful for catching malformed .lyx files and parsing bugs.
5265  They can also be used to find a .lyx file in which an instance of something
5266  happens.
5267  To do this, compile LyX with a local patch that outputs something to the
5268  terminal when an instance is found, and then run the check_load tests to
5269  see if any fail, which would mean that the situation occurs in the LyX
5270  documentation files corresponding to the failed tests.
5271  These tests are expectedly fragile: any LyX diagnostic message, which is
5272  not necessarily an error, would cause the tests to fail.
5273  Similarly, any message output by a library (e.g.
5274  Qt) would also cause failure.
5275  There are some messages that the check_load tests are instructed to ignore,
5276  which are stored in the file
5277 \begin_inset Flex Code
5278 status collapsed
5279
5280 \begin_layout Plain Layout
5281 development/autotests/filterCheckWarnings
5282 \end_layout
5283
5284 \end_inset
5285
5286 .
5287 \end_layout
5288
5289 \begin_layout Standard
5290 Under cmake, the tests are labeled as 'load'.
5291 \end_layout
5292
5293 \begin_layout Subsubsection
5294 Keytests
5295 \end_layout
5296
5297 \begin_layout Standard
5298 Automated tests based on the "MonKey Testing" keytest program are enabled
5299  if the necessary dependencies are found and if the CMake flag
5300 \begin_inset Flex Code
5301 status collapsed
5302
5303 \begin_layout Plain Layout
5304 -DLYX_ENABLE_KEYTESTS=ON
5305 \end_layout
5306
5307 \end_inset
5308
5309  is used.
5310  They are documented in the README document in
5311 \begin_inset Flex Code
5312 status collapsed
5313
5314 \begin_layout Plain Layout
5315 development/autotests
5316 \end_layout
5317
5318 \end_inset
5319
5320  subfolder of the \SpecialChar LyX
5321  source code distribution.
5322 \end_layout
5323
5324 \begin_layout Subsubsection
5325 lyx21 tests
5326 \end_layout
5327
5328 \begin_layout Standard
5329 These tests combine lyx2lyx tests with check_load tests.
5330  They fail if either fails.
5331 \end_layout
5332
5333 \begin_layout Subsubsection
5334 URL tests
5335 \end_layout
5336
5337 \begin_layout Standard
5338 The URL tests are enabled with the
5339 \begin_inset Flex Code
5340 status collapsed
5341
5342 \begin_layout Plain Layout
5343 -DLYX_ENABLE_URLTESTS=ON
5344 \end_layout
5345
5346 \end_inset
5347
5348  CMake flag and are useful for finding broken links in our documentation
5349  files.
5350  If a URL test fails, to see which link in particular was reported as broken,
5351  see the output in
5352 \begin_inset Flex Code
5353 status collapsed
5354
5355 \begin_layout Plain Layout
5356 LastTest.log
5357 \end_layout
5358
5359 \end_inset
5360
5361 .
5362  These tests are extremely fragile (e.g.
5363  a test can depend on your Internet connection) and a failed URL test should
5364  not be taken too seriously.
5365  URL tests are labeled as
5366 \family typewriter
5367 'url'.
5368 \end_layout
5369
5370 \begin_layout Paragraph
5371 Running URL tests
5372 \end_layout
5373
5374 \begin_layout Standard
5375 cmake is required to run the \SpecialChar LyX
5376  tests, running them is not implemented for
5377  autotools.
5378 \end_layout
5379
5380 \begin_layout Standard
5381 The appropriate commands are:
5382 \end_layout
5383
5384 \begin_layout Itemize
5385
5386 \family typewriter
5387 ctest -L url
5388 \family default
5389
5390 \begin_inset Newline newline
5391 \end_inset
5392
5393 runs all tests with label
5394 \family typewriter
5395 'url'
5396 \end_layout
5397
5398 \begin_layout Itemize
5399
5400 \family typewriter
5401 ctest -R 'check_.*urls'
5402 \family default
5403
5404 \begin_inset Newline newline
5405 \end_inset
5406
5407 runs the tests 'check_accessible_urls'
5408 \end_layout
5409
5410 \begin_layout Standard
5411 Associated test results can be examined in ctest-log directory in files
5412  of the form 'LastFailed.*URLS.log'
5413 \end_layout
5414
5415 \begin_layout Section
5416 Development policies
5417 \end_layout
5418
5419 \begin_layout Standard
5420 This chapter lists some guidelines that should be followed.
5421  This list is not complete, and many guidelines are in separate chapters,
5422  such as
5423 \begin_inset Quotes eld
5424 \end_inset
5425
5426 When is an update of the .lyx file format number needed?
5427 \begin_inset Quotes erd
5428 \end_inset
5429
5430  in Section
5431 \begin_inset CommandInset ref
5432 LatexCommand ref
5433 reference "sec:When-is-an"
5434
5435 \end_inset
5436
5437 .
5438 \end_layout
5439
5440 \begin_layout Subsection
5441 When to set a fixed milestone?
5442 \end_layout
5443
5444 \begin_layout Standard
5445 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5446  holds:
5447 \end_layout
5448
5449 \begin_layout Enumerate
5450 Somebody is actively working on a fix.
5451 \end_layout
5452
5453 \begin_layout Enumerate
5454 The bug is so severe that it would block the release if it is not fixed.
5455 \end_layout
5456
5457 \begin_layout Standard
5458 If a bug is important, but nobody is working on it, and it is no showstopper,
5459  use a milestone like 2.1.x or 2.2.x.
5460  For all other bugs, do not set a milestone at all.
5461 \end_layout
5462
5463 \begin_layout Subsection
5464 Can we add rc entries in stable branch?
5465 \end_layout
5466
5467 \begin_layout Standard
5468 No.
5469  We are supposed to increase the prefs2prefs version number with such things.
5470 \end_layout
5471
5472 \begin_layout Section
5473 Documentation policies
5474 \end_layout
5475
5476 \begin_layout Subsection
5477 Rules
5478 \end_layout
5479
5480 \begin_layout Standard
5481 There are 6
5482 \begin_inset space ~
5483 \end_inset
5484
5485 rules in editing the docs:
5486 \end_layout
5487
5488 \begin_layout Enumerate
5489 \begin_inset CommandInset label
5490 LatexCommand label
5491 name "enu:If-you-are"
5492
5493 \end_inset
5494
5495 If you are not the maintainer of a doc file or a chapter/section, you MUST
5496  use change tracking so that the maintainer could review your changes
5497 \end_layout
5498
5499 \begin_layout Enumerate
5500 Respect the formatting of the document.
5501  The different files use different formatting styles.
5502  That is OK and has historic reasons nobody fully knows ;-).
5503  But it is important to be consistent within one file.
5504 \end_layout
5505
5506 \begin_layout Enumerate
5507 All changes you make to a file in one language MUST also go the file in
5508  the other actively maintained languages.
5509  Normally the maintainer does this for you, if you are the maintainer, you
5510  must do this by copying or changing the changed or added text to the other
5511  files so that the translators sees the blue underlined text and know what
5512  they have to translate and what was changed.
5513 \end_layout
5514
5515 \begin_layout Enumerate
5516 You MUST assure that the document is compilable as
5517 \begin_inset Quotes eld
5518 \end_inset
5519
5520 PDF (pdflatex)
5521 \begin_inset Quotes erd
5522 \end_inset
5523
5524  or the document's default output format after your changes.
5525 \end_layout
5526
5527 \begin_layout Enumerate
5528 All fixes (typos, compilation fixes, updates info etc.) go at first into
5529  the current GIT branch because the user should benefit from all fixes with
5530  every minor release.
5531  Feel free to commit directly to branch as long as you follow rule
5532 \begin_inset space ~
5533 \end_inset
5534
5535
5536 \begin_inset CommandInset ref
5537 LatexCommand ref
5538 reference "enu:If-you-are"
5539
5540 \end_inset
5541
5542 .
5543  You can immediately commit to master as well.
5544 \end_layout
5545
5546 \begin_layout Enumerate
5547 The fileformat of a file must not be changed unless you document a new feature
5548  in LyX that requires a new fileformat.
5549  The reason for this rule is to keep it easy for the doc maintainers to
5550  port/backport changes to from master/branch.
5551 \end_layout
5552
5553 \begin_layout Standard
5554 The main documentation consists of these files:
5555 \end_layout
5556
5557 \begin_layout Description
5558 splash.lyx it is the first file you see after an installation.
5559  We assume that a new user sees this.
5560  It is therefore designed to be as simple as possible.
5561  Therefore please don't add any new formatting, only fix typos etc.
5562  Splash.lyx is up to date for \SpecialChar LyX
5563  2.1.x, currently maintained by Uwe Stöhr.
5564 \end_layout
5565
5566 \begin_layout Description
5567 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5568 .
5569  It therefore uses a limited set of formatting.
5570  For example a standard document class.
5571  Since new users will first learn about the formatting possibilities of
5572  \SpecialChar LyX
5573  please keep this file that simple.
5574  Intro.lyx is up to date for \SpecialChar LyX
5575  2.1.x, currently maintained by Uwe Stöhr.
5576 \end_layout
5577
5578 \begin_layout Description
5579 Tutorial.lyx our tutorial.
5580  It must be always up to date.
5581  Normally there is nothing to add since we don't want to overwhelm new users
5582  with too much details.
5583  The will learn these details while using \SpecialChar LyX
5584  and we have special manuals.
5585  Tutorial.lyx is up to date for \SpecialChar LyX
5586  2.1.x, currently maintained by Uwe Stöhr.
5587 \end_layout
5588
5589 \begin_layout Description
5590 UserGuide.lyx our main user guide.
5591  It covers a mixture of basic and detailed information.
5592  Some information is also in the Math and EmbeddedObjects manual so that
5593  the UserGuide refers to these files.
5594  UserGuide.lyx is up to date for \SpecialChar LyX
5595  2.1.x, currently maintained by Uwe Stöhr.
5596 \end_layout
5597
5598 \begin_layout Description
5599 EmbeddedObjects.lyx a special manual to explain things like tables floats
5600  boxes etc.
5601  in all detail.
5602  EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5603  2.1.x, currently maintained by Uwe
5604  Stöhr.
5605 \end_layout
5606
5607 \begin_layout Description
5608 Math.lyx a special manual to explain everything regarding math in all detail.
5609  Math.lyx is up to date for \SpecialChar LyX
5610  2.1.x, currently maintained by Uwe Stöhr.
5611 \end_layout
5612
5613 \begin_layout Description
5614 Additional.lyx this manual covers information that would be too much detail
5615  for the UserGuide or would make the UserGuide uncompilable or only compilable
5616  when installing a lot of special \SpecialChar LaTeX
5617 -packages.
5618  What should be in the UserGuide or better in Additional is a matter of
5619  taste.
5620  it is up to you to decide that.
5621  Additional.lyx is not completely up to date for \SpecialChar LyX
5622  2.1.x.
5623  Only chapter
5624 \begin_inset space ~
5625 \end_inset
5626
5627 8 is up to date and currently maintained by Uwe Stöhr.
5628  It certainly needs a rewrite and update.
5629  For example many info in chapter
5630 \begin_inset space ~
5631 \end_inset
5632
5633 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5634  manual.
5635 \end_layout
5636
5637 \begin_layout Description
5638 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5639  for certain
5640  output formats, operating systems, languages etc.
5641  It is currently completely out of date and needs a major rewrite and update.
5642  If you do this please assure that your information are given for all OSes
5643  and \SpecialChar LaTeX
5644  distributions (meaning be as objective as possible).
5645 \end_layout
5646
5647 \end_body
5648 \end_document