lib/doc/Development.lyx

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