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