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 with only a subset of TeXLive installed), ignore
3406  the failure, ask for someone else to run the test, or install the missing
3407  resources and try again.
3408 \end_layout
3409
3410 \begin_layout Itemize
3411 Check the log file Testing/Temporary/LastTest.log.
3412  In case of latex-errors rerun the failing test with environment variable
3413  'LAX_DEBUG_LATEX' set to '1'.
3414  This will include latex messages in LastTest.log, so it should be easier
3415  to interpret the fail-reason.
3416 \end_layout
3417
3418 \begin_layout Paragraph
3419 \begin_inset CommandInset label
3420 LatexCommand label
3421 name "par:Inverted-tests"
3422
3423 \end_inset
3424
3425 Inverted tests
3426 \end_layout
3427
3428 \begin_layout Standard
3429 Test cases whose name matches a pattern in the file
3430 \begin_inset Flex Code
3431 status collapsed
3432
3433 \begin_layout Plain Layout
3434 development/autotests/invertedTests
3435 \end_layout
3436
3437 \end_inset
3438
3439  get the label
3440 \emph on
3441 inverted
3442 \emph default
3443 .
3444  They get also the test property
3445 \begin_inset Flex Code
3446 status collapsed
3447
3448 \begin_layout Plain Layout
3449 WILL_FAIL
3450 \end_layout
3451
3452 \end_inset
3453
3454 , i.e.
3455  they are reported as failing if the export works without error
3456 \begin_inset Flex URL
3457 status collapsed
3458
3459 \begin_layout Plain Layout
3460
3461 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3462 \end_layout
3463
3464 \end_inset
3465
3466 .
3467 \end_layout
3468
3469 \begin_layout Standard
3470 Add failing cases to this file, if they cannot be solved
3471 \begin_inset Quotes eld
3472 \end_inset
3473
3474 immediately
3475 \begin_inset Quotes erd
3476 \end_inset
3477
3478  but it is expected that the export will work in a foreseeable future, e.g.
3479  low priority issues like failures to export to a non-target format (for
3480  the manuals everything except pdf2).
3481 \end_layout
3482
3483 \begin_layout Standard
3484 The following sublabels are currently present in
3485 \begin_inset Flex Code
3486 status collapsed
3487
3488 \begin_layout Plain Layout
3489 invertedTests
3490 \end_layout
3491
3492 \end_inset
3493
3494 :
3495 \end_layout
3496
3497 \begin_layout Description
3498 todo test failures that require attention:
3499 \end_layout
3500
3501 \begin_deeper
3502 \begin_layout Itemize
3503 minor issues to explore and properly sort later,
3504 \end_layout
3505
3506 \begin_layout Itemize
3507 easyfix issues,
3508 \end_layout
3509
3510 \begin_layout Itemize
3511 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3512 \end_layout
3513
3514 \end_deeper
3515 \begin_layout Description
3516 lyxbugs LyX bugs with a Trac number.
3517 \end_layout
3518
3519 \begin_layout Description
3520 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3521 \end_layout
3522
3523 \begin_deeper
3524 \begin_layout Standard
3525 "Wontfix" if demonstrating correct use and OK in the default output format.
3526 \end_layout
3527
3528 \end_deeper
3529 \begin_layout Description
3530 texissues Export fails due to LaTeX limitations like non-ASCII characters
3531  in verbatim or listings, incompatible packages, ...
3532 \end_layout
3533
3534 \begin_deeper
3535 \begin_layout Standard
3536 "Wontfix" if documents demonstrate correct use in the default output format:
3537 \end_layout
3538
3539 \begin_layout Itemize
3540 If the source can be made more robust without becoming "hackish", fix the
3541  source,
3542 \end_layout
3543
3544 \begin_layout Itemize
3545 if LyX could be enhanced to care for a permanent TeX limitation, file a
3546  ticket at trac and add a pattern under lyxbugs,
3547 \end_layout
3548
3549 \begin_layout Itemize
3550 otherwise, add a pattern here.
3551 \end_layout
3552
3553 \end_deeper
3554 \begin_layout Description
3555 attic Documents in the attic (kept for reference and format conversion test).
3556  Usually
3557 \begin_inset Quotes eld
3558 \end_inset
3559
3560 Wontfix
3561 \begin_inset Quotes erd
3562 \end_inset
3563
3564 .
3565 \end_layout
3566
3567 \begin_layout Subparagraph
3568 suspended tests
3569 \end_layout
3570
3571 \begin_layout Standard
3572 Test cases whose name additionally matches a pattern in the file
3573 \begin_inset Flex Code
3574 status collapsed
3575
3576 \begin_layout Plain Layout
3577 development/autotests/suspendedTests
3578 \end_layout
3579
3580 \end_inset
3581
3582  get the label
3583 \emph on
3584 suspended
3585 \emph default
3586 (instead of
3587 \emph on
3588 export
3589 \emph default
3590 and
3591 \emph on
3592  inverted
3593 \emph default
3594 ).
3595  This means they are not executed using
3596 \begin_inset Flex Code
3597 status collapsed
3598
3599 \begin_layout Plain Layout
3600 ctest -L export
3601 \end_layout
3602
3603 \end_inset
3604
3605  or
3606 \begin_inset Flex Code
3607 status collapsed
3608
3609 \begin_layout Plain Layout
3610 ctest -L inverted
3611 \end_layout
3612
3613 \end_inset
3614
3615 .
3616  However, they also get the test property
3617 \begin_inset Flex Code
3618 status collapsed
3619
3620 \begin_layout Plain Layout
3621 WILL_FAIL
3622 \end_layout
3623
3624 \end_inset
3625
3626 , i.e.
3627  they are reported as failing if the export works without error.
3628  From time to time they still have to be checked using
3629 \begin_inset Flex Code
3630 status collapsed
3631
3632 \begin_layout Plain Layout
3633 ctest -L suspended
3634 \end_layout
3635
3636 \end_inset
3637
3638 .
3639 \end_layout
3640
3641 \begin_layout Standard
3642 These tests are suspended, because the export fails for known reasons which
3643  cannot ATM be resolved.
3644  But it is expected the reason might disappear in the future.
3645  Be it new TL or better handling in \SpecialChar LyX
3646 .
3647 \end_layout
3648
3649 \begin_layout Standard
3650 For ctest commands without the
3651 \begin_inset Flex Code
3652 status collapsed
3653
3654 \begin_layout Plain Layout
3655 -L
3656 \end_layout
3657
3658 \end_inset
3659
3660  parameter nothing changes.
3661  Suspended or not, tests will be executed depending only on the selecting
3662  regular expression given to the ctest command (see
3663 \begin_inset CommandInset ref
3664 LatexCommand ref
3665 reference "par:ctest-options"
3666
3667 \end_inset
3668
3669 ).
3670 \end_layout
3671
3672 \begin_layout Paragraph
3673 \begin_inset CommandInset label
3674 LatexCommand label
3675 name "par:Unreliable-tests"
3676
3677 \end_inset
3678
3679 Unreliable tests
3680 \end_layout
3681
3682 \begin_layout Standard
3683 Test cases whose name matches a pattern in the file
3684 \begin_inset Flex Code
3685 status collapsed
3686
3687 \begin_layout Plain Layout
3688 development/autotests/unreliableTests
3689 \end_layout
3690
3691 \end_inset
3692
3693  get the label
3694 \emph on
3695 unreliable
3696 \emph default
3697 .
3698 \end_layout
3699
3700 \begin_layout Standard
3701 These tests are not executed using
3702 \begin_inset Flex Code
3703 status collapsed
3704
3705 \begin_layout Plain Layout
3706 ctest -L export
3707 \end_layout
3708
3709 \end_inset
3710
3711  or
3712 \begin_inset Flex Code
3713 status collapsed
3714
3715 \begin_layout Plain Layout
3716 ctest -L inverted
3717 \end_layout
3718
3719 \end_inset
3720
3721 .
3722
3723 \end_layout
3724
3725 \begin_layout Standard
3726 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3727  or pass but should rather fail (wrong output).
3728
3729 \begin_inset Note Note
3730 status collapsed
3731
3732 \begin_layout Plain Layout
3733 *invalid* tests (wrong output) are not *unreliable*.
3734  # Use "unfit" or "unapplicable" as better label and name of pattern file?
3735
3736 \end_layout
3737
3738 \end_inset
3739
3740
3741 \end_layout
3742
3743 \begin_layout Standard
3744 The following sublabels are currently present in
3745 \begin_inset Flex Code
3746 status collapsed
3747
3748 \begin_layout Plain Layout
3749 unreliableTests
3750 \end_layout
3751
3752 \end_inset
3753
3754 :
3755 \end_layout
3756
3757 \begin_layout Description
3758 nonstandard Documents with additional requirements, e.g.
3759  a class or package file not in TeXLive.
3760
3761 \begin_inset Note Note
3762 status open
3763
3764 \begin_layout Plain Layout
3765 TODO: rename to
3766 \begin_inset Quotes eld
3767 \end_inset
3768
3769 extra
3770 \begin_inset Quotes erd
3771 \end_inset
3772
3773  or
3774 \begin_inset Quotes eld
3775 \end_inset
3776
3777 exotic
3778 \begin_inset Quotes erd
3779 \end_inset
3780
3781 ?
3782 \end_layout
3783
3784 \end_inset
3785
3786
3787 \end_layout
3788
3789 \begin_layout Description
3790 erratic Tests depending on local configuration or the phase of the moon.
3791
3792 \end_layout
3793
3794 \begin_layout Description
3795 varying_versions Test depending on TeX distribution, package versions or
3796  OS.
3797 \end_layout
3798
3799 \begin_layout Description
3800 wrong
3801 \begin_inset space ~
3802 \end_inset
3803
3804 output Export does not fail but the resulting document has (undetected)
3805  errors.
3806 \end_layout
3807
3808 \begin_deeper
3809 \begin_layout Standard
3810 \paragraph_spacing single
3811 \begin_inset Note Note
3812 status open
3813
3814 \begin_layout Plain Layout
3815 \paragraph_spacing single
3816 These tests are in a strict sense not unreliable but
3817 \emph on
3818 invalid
3819 \emph default
3820  (not measuring what they should measure).
3821 \end_layout
3822
3823 \end_inset
3824
3825
3826 \end_layout
3827
3828 \end_deeper
3829 \begin_layout Paragraph
3830 \begin_inset CommandInset label
3831 LatexCommand label
3832 name "par:Export-test-filtering"
3833
3834 \end_inset
3835
3836 Export test filtering
3837 \end_layout
3838
3839 \begin_layout Standard
3840 The assignment of a label to a test is controlled by a set of files with
3841  regular expressions that are matched against the test names.
3842 \end_layout
3843
3844 \begin_layout Description
3845 ignoredTests (small file)
3846 \begin_inset Newline newline
3847 \end_inset
3848
3849 Tests selected here are withdrawn in the configuration step (cf.
3850
3851 \begin_inset CommandInset ref
3852 LatexCommand ref
3853 reference "par:Configuring-ctests"
3854
3855 \end_inset
3856
3857 ).
3858 \end_layout
3859
3860 \begin_deeper
3861 \begin_layout Labeling
3862 \labelwidthstring 00.00.0000
3863 Input Test of any export combination
3864 \end_layout
3865
3866 \begin_layout Labeling
3867 \labelwidthstring 00.00.0000
3868 Output Stop if tests not selected here
3869 \end_layout
3870
3871 \end_deeper
3872 \begin_layout Description
3873 unreliableTests: Tests selected pass or fail dependent on the system where
3874  the test is run.
3875  Selected tests gain the label 'unreliable'.
3876 \end_layout
3877
3878 \begin_deeper
3879 \begin_layout Labeling
3880 \labelwidthstring 00.00.0000
3881 Input Each test which passed 'ignoredTests'
3882 \end_layout
3883
3884 \begin_layout Labeling
3885 \labelwidthstring 00.00.0000
3886 Output Stop if test selected, gain label 'unreliable'.
3887 \end_layout
3888
3889 \end_deeper
3890 \begin_layout Description
3891 invertedTests
3892 \begin_inset space \space{}
3893 \end_inset
3894
3895
3896 \end_layout
3897
3898 \begin_deeper
3899 \begin_layout Labeling
3900 \labelwidthstring 00.00.0000
3901 Input Each test which passed 'unreliableTests'
3902 \end_layout
3903
3904 \begin_layout Labeling
3905 \labelwidthstring 00.00.0000
3906 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3907  tests are reported as failing if the export works without error.) If no
3908  subselection applies, gain labels 'export' and 'inverted'.
3909 \end_layout
3910
3911 \begin_layout Standard
3912 The following filter perfoms a subselection of 'invertedTests':
3913 \end_layout
3914
3915 \begin_layout Description
3916 suspendedTests Tests selected here gain the label 'suspended' but _not_
3917  'export' or 'inverted', although in ctest they remain inverted.
3918  ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3919 \end_layout
3920
3921 \begin_deeper
3922 \begin_layout Labeling
3923 \labelwidthstring 00.00.0000
3924 Input Each test selected by 'invertedTests'
3925 \end_layout
3926
3927 \begin_layout Labeling
3928 \labelwidthstring 00.00.0000
3929 Output Selected test gains label 'suspended'.
3930
3931 \end_layout
3932
3933 \end_deeper
3934 \end_deeper
3935 \begin_layout Standard
3936 The following table may clarify label assignement
3937 \end_layout
3938
3939 \begin_layout Standard
3940 \begin_inset Tabular
3941 <lyxtabular version="3" rows="7" columns="9">
3942 <features tabularvalignment="middle">
3943 <column alignment="left" valignment="top" width="0pt">
3944 <column alignment="left" valignment="top" width="0pt">
3945 <column alignment="left" valignment="top" width="0pt">
3946 <column alignment="left" valignment="top" width="0pt">
3947 <column alignment="center" valignment="top">
3948 <column alignment="center" valignment="top">
3949 <column alignment="center" valignment="top">
3950 <column alignment="center" valignment="top">
3951 <column alignment="center" valignment="top">
3952 <row>
3953 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3954 \begin_inset Text
3955
3956 \begin_layout Plain Layout
3957 Test matching pattern in file:
3958 \end_layout
3959
3960 \end_inset
3961 </cell>
3962 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3963 \begin_inset Text
3964
3965 \begin_layout Plain Layout
3966
3967 \end_layout
3968
3969 \end_inset
3970 </cell>
3971 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3972 \begin_inset Text
3973
3974 \begin_layout Plain Layout
3975
3976 \end_layout
3977
3978 \end_inset
3979 </cell>
3980 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3981 \begin_inset Text
3982
3983 \begin_layout Plain Layout
3984
3985 \end_layout
3986
3987 \end_inset
3988 </cell>
3989 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3990 \begin_inset Text
3991
3992 \begin_layout Plain Layout
3993 Assigned label
3994 \end_layout
3995
3996 \end_inset
3997 </cell>
3998 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3999 \begin_inset Text
4000
4001 \begin_layout Plain Layout
4002
4003 \end_layout
4004
4005 \end_inset
4006 </cell>
4007 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4008 \begin_inset Text
4009
4010 \begin_layout Plain Layout
4011
4012 \end_layout
4013
4014 \end_inset
4015 </cell>
4016 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4017 \begin_inset Text
4018
4019 \begin_layout Plain Layout
4020
4021 \end_layout
4022
4023 \end_inset
4024 </cell>
4025 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4026 \begin_inset Text
4027
4028 \begin_layout Plain Layout
4029 test property
4030 \end_layout
4031
4032 \end_inset
4033 </cell>
4034 </row>
4035 <row>
4036 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4037 \begin_inset Text
4038
4039 \begin_layout Plain Layout
4040 ignoredTests
4041 \end_layout
4042
4043 \end_inset
4044 </cell>
4045 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4046 \begin_inset Text
4047
4048 \begin_layout Plain Layout
4049 unreliableTests
4050 \end_layout
4051
4052 \end_inset
4053 </cell>
4054 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4055 \begin_inset Text
4056
4057 \begin_layout Plain Layout
4058 invertedTests
4059 \end_layout
4060
4061 \end_inset
4062 </cell>
4063 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4064 \begin_inset Text
4065
4066 \begin_layout Plain Layout
4067 suspendedTests
4068 \end_layout
4069
4070 \end_inset
4071 </cell>
4072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4073 \begin_inset Text
4074
4075 \begin_layout Plain Layout
4076 export
4077 \end_layout
4078
4079 \end_inset
4080 </cell>
4081 <cell alignment="center" valignment="top" topline="true" usebox="none">
4082 \begin_inset Text
4083
4084 \begin_layout Plain Layout
4085 unreliable
4086 \end_layout
4087
4088 \end_inset
4089 </cell>
4090 <cell alignment="center" valignment="top" topline="true" usebox="none">
4091 \begin_inset Text
4092
4093 \begin_layout Plain Layout
4094 inverted
4095 \end_layout
4096
4097 \end_inset
4098 </cell>
4099 <cell alignment="center" valignment="top" topline="true" usebox="none">
4100 \begin_inset Text
4101
4102 \begin_layout Plain Layout
4103 suspended
4104 \end_layout
4105
4106 \end_inset
4107 </cell>
4108 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4109 \begin_inset Text
4110
4111 \begin_layout Plain Layout
4112
4113 \end_layout
4114
4115 \end_inset
4116 </cell>
4117 </row>
4118 <row>
4119 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4120 \begin_inset Text
4121
4122 \begin_layout Plain Layout
4123 Yes
4124 \end_layout
4125
4126 \end_inset
4127 </cell>
4128 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4129 \begin_inset Text
4130
4131 \begin_layout Plain Layout
4132 -
4133 \end_layout
4134
4135 \end_inset
4136 </cell>
4137 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4138 \begin_inset Text
4139
4140 \begin_layout Plain Layout
4141 -
4142 \end_layout
4143
4144 \end_inset
4145 </cell>
4146 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4147 \begin_inset Text
4148
4149 \begin_layout Plain Layout
4150 -
4151 \end_layout
4152
4153 \end_inset
4154 </cell>
4155 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4156 \begin_inset Text
4157
4158 \begin_layout Plain Layout
4159 -
4160 \end_layout
4161
4162 \end_inset
4163 </cell>
4164 <cell alignment="center" valignment="top" topline="true" usebox="none">
4165 \begin_inset Text
4166
4167 \begin_layout Plain Layout
4168
4169 \end_layout
4170
4171 \end_inset
4172 </cell>
4173 <cell alignment="center" valignment="top" topline="true" usebox="none">
4174 \begin_inset Text
4175
4176 \begin_layout Plain Layout
4177 -
4178 \end_layout
4179
4180 \end_inset
4181 </cell>
4182 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4183 \begin_inset Text
4184
4185 \begin_layout Plain Layout
4186 -
4187 \end_layout
4188
4189 \end_inset
4190 </cell>
4191 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4192 \begin_inset Text
4193
4194 \begin_layout Plain Layout
4195
4196 \end_layout
4197
4198 \end_inset
4199 </cell>
4200 </row>
4201 <row>
4202 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4203 \begin_inset Text
4204
4205 \begin_layout Plain Layout
4206 No
4207 \end_layout
4208
4209 \end_inset
4210 </cell>
4211 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4212 \begin_inset Text
4213
4214 \begin_layout Plain Layout
4215 Yes
4216 \end_layout
4217
4218 \end_inset
4219 </cell>
4220 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4221 \begin_inset Text
4222
4223 \begin_layout Plain Layout
4224 -
4225 \end_layout
4226
4227 \end_inset
4228 </cell>
4229 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4230 \begin_inset Text
4231
4232 \begin_layout Plain Layout
4233 -
4234 \end_layout
4235
4236 \end_inset
4237 </cell>
4238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4239 \begin_inset Text
4240
4241 \begin_layout Plain Layout
4242 -
4243 \end_layout
4244
4245 \end_inset
4246 </cell>
4247 <cell alignment="center" valignment="top" topline="true" usebox="none">
4248 \begin_inset Text
4249
4250 \begin_layout Plain Layout
4251 +
4252 \end_layout
4253
4254 \end_inset
4255 </cell>
4256 <cell alignment="center" valignment="top" topline="true" usebox="none">
4257 \begin_inset Text
4258
4259 \begin_layout Plain Layout
4260 -
4261 \end_layout
4262
4263 \end_inset
4264 </cell>
4265 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4266 \begin_inset Text
4267
4268 \begin_layout Plain Layout
4269 -
4270 \end_layout
4271
4272 \end_inset
4273 </cell>
4274 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4275 \begin_inset Text
4276
4277 \begin_layout Plain Layout
4278
4279 \end_layout
4280
4281 \end_inset
4282 </cell>
4283 </row>
4284 <row>
4285 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4286 \begin_inset Text
4287
4288 \begin_layout Plain Layout
4289
4290 \end_layout
4291
4292 \end_inset
4293 </cell>
4294 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4295 \begin_inset Text
4296
4297 \begin_layout Plain Layout
4298 No
4299 \end_layout
4300
4301 \end_inset
4302 </cell>
4303 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4304 \begin_inset Text
4305
4306 \begin_layout Plain Layout
4307 Yes
4308 \end_layout
4309
4310 \end_inset
4311 </cell>
4312 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4313 \begin_inset Text
4314
4315 \begin_layout Plain Layout
4316 Yes
4317 \end_layout
4318
4319 \end_inset
4320 </cell>
4321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4322 \begin_inset Text
4323
4324 \begin_layout Plain Layout
4325 -
4326 \end_layout
4327
4328 \end_inset
4329 </cell>
4330 <cell alignment="center" valignment="top" topline="true" usebox="none">
4331 \begin_inset Text
4332
4333 \begin_layout Plain Layout
4334 -
4335 \end_layout
4336
4337 \end_inset
4338 </cell>
4339 <cell alignment="center" valignment="top" topline="true" usebox="none">
4340 \begin_inset Text
4341
4342 \begin_layout Plain Layout
4343 -
4344 \end_layout
4345
4346 \end_inset
4347 </cell>
4348 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4349 \begin_inset Text
4350
4351 \begin_layout Plain Layout
4352 +
4353 \end_layout
4354
4355 \end_inset
4356 </cell>
4357 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4358 \begin_inset Text
4359
4360 \begin_layout Plain Layout
4361 WILL_FAIL
4362 \end_layout
4363
4364 \end_inset
4365 </cell>
4366 </row>
4367 <row>
4368 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4369 \begin_inset Text
4370
4371 \begin_layout Plain Layout
4372
4373 \end_layout
4374
4375 \end_inset
4376 </cell>
4377 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4378 \begin_inset Text
4379
4380 \begin_layout Plain Layout
4381
4382 \end_layout
4383
4384 \end_inset
4385 </cell>
4386 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4387 \begin_inset Text
4388
4389 \begin_layout Plain Layout
4390
4391 \end_layout
4392
4393 \end_inset
4394 </cell>
4395 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4396 \begin_inset Text
4397
4398 \begin_layout Plain Layout
4399 No
4400 \end_layout
4401
4402 \end_inset
4403 </cell>
4404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4405 \begin_inset Text
4406
4407 \begin_layout Plain Layout
4408 +
4409 \end_layout
4410
4411 \end_inset
4412 </cell>
4413 <cell alignment="center" valignment="top" topline="true" usebox="none">
4414 \begin_inset Text
4415
4416 \begin_layout Plain Layout
4417 -
4418 \end_layout
4419
4420 \end_inset
4421 </cell>
4422 <cell alignment="center" valignment="top" topline="true" usebox="none">
4423 \begin_inset Text
4424
4425 \begin_layout Plain Layout
4426 +
4427 \end_layout
4428
4429 \end_inset
4430 </cell>
4431 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4432 \begin_inset Text
4433
4434 \begin_layout Plain Layout
4435 -
4436 \end_layout
4437
4438 \end_inset
4439 </cell>
4440 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4441 \begin_inset Text
4442
4443 \begin_layout Plain Layout
4444 WILL_FAIL
4445 \end_layout
4446
4447 \end_inset
4448 </cell>
4449 </row>
4450 <row>
4451 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4452 \begin_inset Text
4453
4454 \begin_layout Plain Layout
4455
4456 \end_layout
4457
4458 \end_inset
4459 </cell>
4460 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4461 \begin_inset Text
4462
4463 \begin_layout Plain Layout
4464
4465 \end_layout
4466
4467 \end_inset
4468 </cell>
4469 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4470 \begin_inset Text
4471
4472 \begin_layout Plain Layout
4473 No
4474 \end_layout
4475
4476 \end_inset
4477 </cell>
4478 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4479 \begin_inset Text
4480
4481 \begin_layout Plain Layout
4482 -
4483 \end_layout
4484
4485 \end_inset
4486 </cell>
4487 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4488 \begin_inset Text
4489
4490 \begin_layout Plain Layout
4491 +
4492 \end_layout
4493
4494 \end_inset
4495 </cell>
4496 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4497 \begin_inset Text
4498
4499 \begin_layout Plain Layout
4500 -
4501 \end_layout
4502
4503 \end_inset
4504 </cell>
4505 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4506 \begin_inset Text
4507
4508 \begin_layout Plain Layout
4509 -
4510 \end_layout
4511
4512 \end_inset
4513 </cell>
4514 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4515 \begin_inset Text
4516
4517 \begin_layout Plain Layout
4518 -
4519 \end_layout
4520
4521 \end_inset
4522 </cell>
4523 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4524 \begin_inset Text
4525
4526 \begin_layout Plain Layout
4527
4528 \end_layout
4529
4530 \end_inset
4531 </cell>
4532 </row>
4533 </lyxtabular>
4534
4535 \end_inset
4536
4537
4538 \end_layout
4539
4540 \begin_layout Standard
4541 \begin_inset Note Note
4542 status open
4543
4544 \begin_layout Plain Layout
4545 Without the
4546 \begin_inset Quotes eld
4547 \end_inset
4548
4549 suspendedTests
4550 \begin_inset Quotes erd
4551 \end_inset
4552
4553  filter, this would be far less complicated:
4554 \end_layout
4555
4556 \begin_layout Plain Layout
4557 \begin_inset Tabular
4558 <lyxtabular version="3" rows="6" columns="7">
4559 <features tabularvalignment="middle">
4560 <column alignment="left" valignment="top" width="0pt">
4561 <column alignment="left" valignment="top" width="0pt">
4562 <column alignment="left" valignment="top" width="0pt">
4563 <column alignment="center" valignment="top">
4564 <column alignment="center" valignment="top">
4565 <column alignment="center" valignment="top">
4566 <column alignment="center" valignment="top">
4567 <row>
4568 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4569 \begin_inset Text
4570
4571 \begin_layout Plain Layout
4572 Test matching pattern in file:
4573 \end_layout
4574
4575 \end_inset
4576 </cell>
4577 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4578 \begin_inset Text
4579
4580 \begin_layout Plain Layout
4581
4582 \end_layout
4583
4584 \end_inset
4585 </cell>
4586 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4587 \begin_inset Text
4588
4589 \begin_layout Plain Layout
4590
4591 \end_layout
4592
4593 \end_inset
4594 </cell>
4595 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4596 \begin_inset Text
4597
4598 \begin_layout Plain Layout
4599 Label
4600 \end_layout
4601
4602 \end_inset
4603 </cell>
4604 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4605 \begin_inset Text
4606
4607 \begin_layout Plain Layout
4608
4609 \end_layout
4610
4611 \end_inset
4612 </cell>
4613 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4614 \begin_inset Text
4615
4616 \begin_layout Plain Layout
4617
4618 \end_layout
4619
4620 \end_inset
4621 </cell>
4622 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4623 \begin_inset Text
4624
4625 \begin_layout Plain Layout
4626 test property
4627 \end_layout
4628
4629 \end_inset
4630 </cell>
4631 </row>
4632 <row>
4633 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4634 \begin_inset Text
4635
4636 \begin_layout Plain Layout
4637 ignoredTests
4638 \end_layout
4639
4640 \end_inset
4641 </cell>
4642 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4643 \begin_inset Text
4644
4645 \begin_layout Plain Layout
4646 unreliableTests
4647 \end_layout
4648
4649 \end_inset
4650 </cell>
4651 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4652 \begin_inset Text
4653
4654 \begin_layout Plain Layout
4655 invertedTests
4656 \end_layout
4657
4658 \end_inset
4659 </cell>
4660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4661 \begin_inset Text
4662
4663 \begin_layout Plain Layout
4664 export
4665 \end_layout
4666
4667 \end_inset
4668 </cell>
4669 <cell alignment="center" valignment="top" topline="true" usebox="none">
4670 \begin_inset Text
4671
4672 \begin_layout Plain Layout
4673 unreliable
4674 \end_layout
4675
4676 \end_inset
4677 </cell>
4678 <cell alignment="center" valignment="top" topline="true" usebox="none">
4679 \begin_inset Text
4680
4681 \begin_layout Plain Layout
4682 inverted
4683 \end_layout
4684
4685 \end_inset
4686 </cell>
4687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4688 \begin_inset Text
4689
4690 \begin_layout Plain Layout
4691
4692 \end_layout
4693
4694 \end_inset
4695 </cell>
4696 </row>
4697 <row>
4698 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4699 \begin_inset Text
4700
4701 \begin_layout Plain Layout
4702 Yes
4703 \end_layout
4704
4705 \end_inset
4706 </cell>
4707 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4708 \begin_inset Text
4709
4710 \begin_layout Plain Layout
4711 -
4712 \end_layout
4713
4714 \end_inset
4715 </cell>
4716 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4717 \begin_inset Text
4718
4719 \begin_layout Plain Layout
4720 -
4721 \end_layout
4722
4723 \end_inset
4724 </cell>
4725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4726 \begin_inset Text
4727
4728 \begin_layout Plain Layout
4729 -
4730 \end_layout
4731
4732 \end_inset
4733 </cell>
4734 <cell alignment="center" valignment="top" topline="true" usebox="none">
4735 \begin_inset Text
4736
4737 \begin_layout Plain Layout
4738
4739 \end_layout
4740
4741 \end_inset
4742 </cell>
4743 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4744 \begin_inset Text
4745
4746 \begin_layout Plain Layout
4747 -
4748 \end_layout
4749
4750 \end_inset
4751 </cell>
4752 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4753 \begin_inset Text
4754
4755 \begin_layout Plain Layout
4756
4757 \end_layout
4758
4759 \end_inset
4760 </cell>
4761 </row>
4762 <row>
4763 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4764 \begin_inset Text
4765
4766 \begin_layout Plain Layout
4767 No
4768 \end_layout
4769
4770 \end_inset
4771 </cell>
4772 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4773 \begin_inset Text
4774
4775 \begin_layout Plain Layout
4776 Yes
4777 \end_layout
4778
4779 \end_inset
4780 </cell>
4781 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4782 \begin_inset Text
4783
4784 \begin_layout Plain Layout
4785 -
4786 \end_layout
4787
4788 \end_inset
4789 </cell>
4790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4791 \begin_inset Text
4792
4793 \begin_layout Plain Layout
4794 -
4795 \end_layout
4796
4797 \end_inset
4798 </cell>
4799 <cell alignment="center" valignment="top" topline="true" usebox="none">
4800 \begin_inset Text
4801
4802 \begin_layout Plain Layout
4803 +
4804 \end_layout
4805
4806 \end_inset
4807 </cell>
4808 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4809 \begin_inset Text
4810
4811 \begin_layout Plain Layout
4812 -
4813 \end_layout
4814
4815 \end_inset
4816 </cell>
4817 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4818 \begin_inset Text
4819
4820 \begin_layout Plain Layout
4821
4822 \end_layout
4823
4824 \end_inset
4825 </cell>
4826 </row>
4827 <row>
4828 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4829 \begin_inset Text
4830
4831 \begin_layout Plain Layout
4832
4833 \end_layout
4834
4835 \end_inset
4836 </cell>
4837 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4838 \begin_inset Text
4839
4840 \begin_layout Plain Layout
4841 No
4842 \end_layout
4843
4844 \end_inset
4845 </cell>
4846 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4847 \begin_inset Text
4848
4849 \begin_layout Plain Layout
4850 Yes
4851 \end_layout
4852
4853 \end_inset
4854 </cell>
4855 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4856 \begin_inset Text
4857
4858 \begin_layout Plain Layout
4859 +
4860 \end_layout
4861
4862 \end_inset
4863 </cell>
4864 <cell alignment="center" valignment="top" topline="true" usebox="none">
4865 \begin_inset Text
4866
4867 \begin_layout Plain Layout
4868 -
4869 \end_layout
4870
4871 \end_inset
4872 </cell>
4873 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4874 \begin_inset Text
4875
4876 \begin_layout Plain Layout
4877 +
4878 \end_layout
4879
4880 \end_inset
4881 </cell>
4882 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4883 \begin_inset Text
4884
4885 \begin_layout Plain Layout
4886 WILL_FAIL
4887 \end_layout
4888
4889 \end_inset
4890 </cell>
4891 </row>
4892 <row>
4893 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4894 \begin_inset Text
4895
4896 \begin_layout Plain Layout
4897
4898 \end_layout
4899
4900 \end_inset
4901 </cell>
4902 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4903 \begin_inset Text
4904
4905 \begin_layout Plain Layout
4906
4907 \end_layout
4908
4909 \end_inset
4910 </cell>
4911 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4912 \begin_inset Text
4913
4914 \begin_layout Plain Layout
4915 No
4916 \end_layout
4917
4918 \end_inset
4919 </cell>
4920 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4921 \begin_inset Text
4922
4923 \begin_layout Plain Layout
4924 +
4925 \end_layout
4926
4927 \end_inset
4928 </cell>
4929 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4930 \begin_inset Text
4931
4932 \begin_layout Plain Layout
4933 -
4934 \end_layout
4935
4936 \end_inset
4937 </cell>
4938 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4939 \begin_inset Text
4940
4941 \begin_layout Plain Layout
4942 -
4943 \end_layout
4944
4945 \end_inset
4946 </cell>
4947 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4948 \begin_inset Text
4949
4950 \begin_layout Plain Layout
4951
4952 \end_layout
4953
4954 \end_inset
4955 </cell>
4956 </row>
4957 </lyxtabular>
4958
4959 \end_inset
4960
4961
4962 \end_layout
4963
4964 \end_inset
4965
4966
4967 \end_layout
4968
4969 \begin_layout Subsubsection
4970 check_load tests
4971 \end_layout
4972
4973 \begin_layout Standard
4974 These tests check whether a .lyx file loads without any terminal messages.
4975  They correspond to the manual operations of simply opening a .lyx file on
4976  the terminal, exiting LyX once the file is loaded, and then checking whether
4977  there is any output from the terminal.
4978  These tests are useful for catching malformed .lyx files and parsing bugs.
4979  They can also be used to find a .lyx file in which an instance of something
4980  happens.
4981  To do this, compile LyX with a local patch that outputs something to the
4982  terminal when an instance is found, and then run the check_load tests to
4983  see if any fail, which would mean that the situation occurs in the LyX
4984  documentation files corresponding to the failed tests.
4985  These tests are expectedly fragile: any LyX diagnostic message, which is
4986  not necessarily an error, would cause the tests to fail.
4987  Similarly, any message output by a library (e.g.
4988  Qt) would also cause failure.
4989  There are some messages that the check_load tests are instructed to ignore,
4990  which are stored in the file
4991 \begin_inset Flex Code
4992 status collapsed
4993
4994 \begin_layout Plain Layout
4995 development/autotests/filterCheckWarnings
4996 \end_layout
4997
4998 \end_inset
4999
5000 .
5001 \end_layout
5002
5003 \begin_layout Standard
5004 Under cmake, the tests are labeled as 'load'.
5005 \end_layout
5006
5007 \begin_layout Subsubsection
5008 Keytests
5009 \end_layout
5010
5011 \begin_layout Standard
5012 Automated tests based on the "MonKey Testing" keytest program are enabled
5013  if the necessary dependencies are found and if the CMake flag
5014 \begin_inset Flex Code
5015 status collapsed
5016
5017 \begin_layout Plain Layout
5018 -DLYX_ENABLE_KEYTESTS=ON
5019 \end_layout
5020
5021 \end_inset
5022
5023  is used.
5024  They are documented in the README document in
5025 \begin_inset Flex Code
5026 status collapsed
5027
5028 \begin_layout Plain Layout
5029 development/autotests
5030 \end_layout
5031
5032 \end_inset
5033
5034  subfolder of the \SpecialChar LyX
5035  source code distribution.
5036 \end_layout
5037
5038 \begin_layout Subsubsection
5039 lyx21 tests
5040 \end_layout
5041
5042 \begin_layout Standard
5043 These tests combine lyx2lyx tests with check_load tests.
5044  They fail if either fails.
5045 \end_layout
5046
5047 \begin_layout Subsubsection
5048 URL tests
5049 \end_layout
5050
5051 \begin_layout Standard
5052 The URL tests are enabled with the
5053 \begin_inset Flex Code
5054 status collapsed
5055
5056 \begin_layout Plain Layout
5057 -DLYX_ENABLE_URLTESTS=ON
5058 \end_layout
5059
5060 \end_inset
5061
5062  CMake flag and are useful for finding broken links in our documentation
5063  files.
5064  If a URL test fails, to see which link in particular was reported as broken,
5065  see the output in
5066 \begin_inset Flex Code
5067 status collapsed
5068
5069 \begin_layout Plain Layout
5070 LastTest.log
5071 \end_layout
5072
5073 \end_inset
5074
5075 .
5076  These tests are extremely fragile (e.g.
5077  a test can depend on your Internet connection) and a failed URL test should
5078  not be taken too seriously.
5079  URL tests are labeled as
5080 \family typewriter
5081 'url'.
5082 \end_layout
5083
5084 \begin_layout Paragraph
5085 Running URL tests
5086 \end_layout
5087
5088 \begin_layout Standard
5089 cmake is required to run the \SpecialChar LyX
5090  tests, running them is not implemented for
5091  autotools.
5092 \end_layout
5093
5094 \begin_layout Standard
5095 The appropriate commands are:
5096 \end_layout
5097
5098 \begin_layout Itemize
5099
5100 \family typewriter
5101 ctest -L url
5102 \family default
5103
5104 \begin_inset Newline newline
5105 \end_inset
5106
5107 runs all tests with label
5108 \family typewriter
5109 'url'
5110 \end_layout
5111
5112 \begin_layout Itemize
5113
5114 \family typewriter
5115 ctest -R 'check_.*urls'
5116 \family default
5117
5118 \begin_inset Newline newline
5119 \end_inset
5120
5121 runs the tests 'check_accessible_urls'
5122 \end_layout
5123
5124 \begin_layout Standard
5125 Associated test results can be examined in ctest-log directory in files
5126  of the form 'LastFailed.*URLS.log'
5127 \end_layout
5128
5129 \begin_layout Section
5130 Development policies
5131 \end_layout
5132
5133 \begin_layout Standard
5134 This chapter lists some guidelines that should be followed.
5135  This list is not complete, and many guidelines are in separate chapters,
5136  such as
5137 \begin_inset Quotes eld
5138 \end_inset
5139
5140 When is an update of the .lyx file format number needed?
5141 \begin_inset Quotes erd
5142 \end_inset
5143
5144  in Section
5145 \begin_inset CommandInset ref
5146 LatexCommand ref
5147 reference "sec:When-is-an"
5148
5149 \end_inset
5150
5151 .
5152 \end_layout
5153
5154 \begin_layout Subsection
5155 When to set a fixed milestone?
5156 \end_layout
5157
5158 \begin_layout Standard
5159 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5160  holds:
5161 \end_layout
5162
5163 \begin_layout Enumerate
5164 Somebody is actively working on a fix.
5165 \end_layout
5166
5167 \begin_layout Enumerate
5168 The bug is so severe that it would block the release if it is not fixed.
5169 \end_layout
5170
5171 \begin_layout Standard
5172 If a bug is important, but nobody is working on it, and it is no showstopper,
5173  use a milestone like 2.1.x or 2.2.x.
5174  For all other bugs, do not set a milestone at all.
5175 \end_layout
5176
5177 \begin_layout Subsection
5178 Can we add rc entries in stable branch?
5179 \end_layout
5180
5181 \begin_layout Standard
5182 No.
5183  We are supposed to increase the prefs2prefs version number with such things.
5184 \end_layout
5185
5186 \begin_layout Section
5187 Documentation policies
5188 \end_layout
5189
5190 \begin_layout Subsection
5191 Rules
5192 \end_layout
5193
5194 \begin_layout Standard
5195 There are 6
5196 \begin_inset space ~
5197 \end_inset
5198
5199 rules in editing the docs:
5200 \end_layout
5201
5202 \begin_layout Enumerate
5203 \begin_inset CommandInset label
5204 LatexCommand label
5205 name "enu:If-you-are"
5206
5207 \end_inset
5208
5209 If you are not the maintainer of a doc file or a chapter/section, you MUST
5210  use change tracking so that the maintainer could review your changes
5211 \end_layout
5212
5213 \begin_layout Enumerate
5214 Respect the formatting of the document.
5215  The different files use different formatting styles.
5216  That is OK and has historic reasons nobody fully knows ;-).
5217  But it is important to be consistent within one file.
5218 \end_layout
5219
5220 \begin_layout Enumerate
5221 All changes you make to a file in one language MUST also go the file in
5222  the other actively maintained languages.
5223  Normally the maintainer does this for you, if you are the maintainer, you
5224  must do this by copying or changing the changed or added text to the other
5225  files so that the translators sees the blue underlined text and know what
5226  they have to translate and what was changed.
5227 \end_layout
5228
5229 \begin_layout Enumerate
5230 You MUST assure that the document is compilable as
5231 \begin_inset Quotes eld
5232 \end_inset
5233
5234 PDF (pdflatex)
5235 \begin_inset Quotes erd
5236 \end_inset
5237
5238  or the document's default output format after your changes.
5239 \end_layout
5240
5241 \begin_layout Enumerate
5242 All fixes (typos, compilation fixes, updates info etc.) go at first into
5243  the current GIT branch because the user should benefit from all fixes with
5244  every minor release.
5245  Feel free to commit directly to branch as long as you follow rule
5246 \begin_inset space ~
5247 \end_inset
5248
5249
5250 \begin_inset CommandInset ref
5251 LatexCommand ref
5252 reference "enu:If-you-are"
5253
5254 \end_inset
5255
5256 .
5257  You can immediately commit to master as well.
5258 \end_layout
5259
5260 \begin_layout Enumerate
5261 The fileformat of a file must not be changed unless you document a new feature
5262  in LyX that requires a new fileformat.
5263  The reason for this rule is to keep it easy for the doc maintainers to
5264  port/backport changes to from master/branch.
5265 \end_layout
5266
5267 \begin_layout Standard
5268 The main documentation consists of these files:
5269 \end_layout
5270
5271 \begin_layout Description
5272 splash.lyx it is the first file you see after an installation.
5273  We assume that a new user sees this.
5274  It is therefore designed to be as simple as possible.
5275  Therefore please don't add any new formatting, only fix typos etc.
5276  Splash.lyx is up to date for \SpecialChar LyX
5277  2.1.x, currently maintained by Uwe Stöhr.
5278 \end_layout
5279
5280 \begin_layout Description
5281 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5282 .
5283  It therefore uses a limited set of formatting.
5284  For example a standard document class.
5285  Since new users will first learn about the formatting possibilities of
5286  \SpecialChar LyX
5287  please keep this file that simple.
5288  Intro.lyx is up to date for \SpecialChar LyX
5289  2.1.x, currently maintained by Uwe Stöhr.
5290 \end_layout
5291
5292 \begin_layout Description
5293 Tutorial.lyx our tutorial.
5294  It must be always up to date.
5295  Normally there is nothing to add since we don't want to overwhelm new users
5296  with too much details.
5297  The will learn these details while using \SpecialChar LyX
5298  and we have special manuals.
5299  Tutorial.lyx is up to date for \SpecialChar LyX
5300  2.1.x, currently maintained by Uwe Stöhr.
5301 \end_layout
5302
5303 \begin_layout Description
5304 UserGuide.lyx our main user guide.
5305  It covers a mixture of basic and detailed information.
5306  Some information is also in the Math and EmbeddedObjects manual so that
5307  the UserGuide refers to these files.
5308  UserGuide.lyx is up to date for \SpecialChar LyX
5309  2.1.x, currently maintained by Uwe Stöhr.
5310 \end_layout
5311
5312 \begin_layout Description
5313 EmbeddedObjects.lyx a special manual to explain things like tables floats
5314  boxes etc.
5315  in all detail.
5316  EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5317  2.1.x, currently maintained by Uwe
5318  Stöhr.
5319 \end_layout
5320
5321 \begin_layout Description
5322 Math.lyx a special manual to explain everything regarding math in all detail.
5323  Math.lyx is up to date for \SpecialChar LyX
5324  2.1.x, currently maintained by Uwe Stöhr.
5325 \end_layout
5326
5327 \begin_layout Description
5328 Additional.lyx this manual covers information that would be too much detail
5329  for the UserGuide or would make the UserGuide uncompilable or only compilable
5330  when installing a lot of special \SpecialChar LaTeX
5331 -packages.
5332  What should be in the UserGuide or better in Additional is a matter of
5333  taste.
5334  it is up to you to decide that.
5335  Additional.lyx is not completely up to date for \SpecialChar LyX
5336  2.1.x.
5337  Only chapter
5338 \begin_inset space ~
5339 \end_inset
5340
5341 8 is up to date and currently maintained by Uwe Stöhr.
5342  It certainly needs a rewrite and update.
5343  For example many info in chapter
5344 \begin_inset space ~
5345 \end_inset
5346
5347 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5348  manual.
5349 \end_layout
5350
5351 \begin_layout Description
5352 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5353  for certain
5354  output formats, operating systems, languages etc.
5355  It is currently completely out of date and needs a major rewrite and update.
5356  If you do this please assure that your information are given for all OSes
5357  and \SpecialChar LaTeX
5358  distributions (meaning be as objective as possible).
5359 \end_layout
5360
5361 \end_body
5362 \end_document