lib/doc/Development.lyx

   1 #LyX 2.2 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 506
   3 \begin_document
   4 \begin_header
   5 \save_transient_properties true
   6 \origin /systemlyxdir/doc/
   7 \textclass scrartcl
   8 \options BCOR8mm,captions=tableheading
   9 \use_default_options false
  10 \begin_modules
  11 logicalmkup
  12 \end_modules
  13 \maintain_unincluded_children false
  14 \language english
  15 \language_package default
  16 \inputencoding auto
  17 \fontencoding global
  18 \font_roman "lmodern" "default"
  19 \font_sans "lmss" "default"
  20 \font_typewriter "lmtt" "default"
  21 \font_math "auto" "auto"
  22 \font_default_family default
  23 \use_non_tex_fonts false
  24 \font_sc false
  25 \font_osf false
  26 \font_sf_scale 100 100
  27 \font_tt_scale 100 100
  28 \graphics default
  29 \default_output_format pdf2
  30 \output_sync 1
  31 \bibtex_command default
  32 \index_command default
  33 \paperfontsize 12
  34 \spacing single
  35 \use_hyperref true
  36 \pdf_title "LyX's Development manual"
  37 \pdf_author "LyX Team"
  38 \pdf_subject "LyX's development documentation"
  39 \pdf_keywords "LyX, Documentation, Development"
  40 \pdf_bookmarks true
  41 \pdf_bookmarksnumbered true
  42 \pdf_bookmarksopen true
  43 \pdf_bookmarksopenlevel 1
  44 \pdf_breaklinks false
  45 \pdf_pdfborder false
  46 \pdf_colorlinks true
  47 \pdf_backref false
  48 \pdf_pdfusetitle false
  49 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
  50 \papersize a4paper
  51 \use_geometry false
  52 \use_package amsmath 1
  53 \use_package amssymb 1
  54 \use_package cancel 0
  55 \use_package esint 0
  56 \use_package mathdots 1
  57 \use_package mathtools 0
  58 \use_package mhchem 1
  59 \use_package stackrel 0
  60 \use_package stmaryrd 0
  61 \use_package undertilde 0
  62 \cite_engine basic
  63 \cite_engine_type default
  64 \biblio_style plain
  65 \use_bibtopic false
  66 \use_indices false
  67 \paperorientation portrait
  68 \suppress_date false
  69 \justification true
  70 \use_refstyle 0
  71 \notefontcolor #0000ff
  72 \index Index
  73 \shortcut idx
  74 \color #008000
  75 \end_index
  76 \secnumdepth 4
  77 \tocdepth 4
  78 \paragraph_separation indent
  79 \paragraph_indentation default
  80 \quotes_language english
  81 \papercolumns 1
  82 \papersides 2
  83 \paperpagestyle headings
  84 \tracking_changes false
  85 \output_changes false
  86 \html_math_output 0
  87 \html_css_as_file 0
  88 \html_be_strict true
  89 \end_header
  90
  91 \begin_body
  92
  93 \begin_layout Title
  94 Developing \SpecialChar LyX
  95
  96 \end_layout
  97
  98 \begin_layout Subtitle
  99 Version 2.2.x
 100 \end_layout
 101
 102 \begin_layout Author
 103 by the \SpecialChar LyX
 104  Team
 105 \begin_inset Foot
 106 status collapsed
 107
 108 \begin_layout Plain Layout
 109 \noindent
 110 If you have comments or error corrections, please send them to the \SpecialChar LyX
 111  Documentatio
 112 n mailing list,
 113 \begin_inset Flex Code
 114 status collapsed
 115
 116 \begin_layout Plain Layout
 117 \noindent
 118 <lyx-docs@lists.lyx.org>
 119 \end_layout
 120
 121 \end_inset
 122
 123 .
 124 \end_layout
 125
 126 \end_inset
 127
 128
 129 \end_layout
 130
 131 \begin_layout Standard
 132 \begin_inset CommandInset toc
 133 LatexCommand tableofcontents
 134
 135 \end_inset
 136
 137
 138 \end_layout
 139
 140 \begin_layout Section
 141 Introduction
 142 \end_layout
 143
 144 \begin_layout Standard
 145 This manual documents some aspects of \SpecialChar LyX
 146  development.
 147  It is currently rather incomplete, but will hopefully be extended in the
 148  future.
 149  Meanwhile, additional information can be found in the
 150 \begin_inset Flex Code
 151 status collapsed
 152
 153 \begin_layout Plain Layout
 154 development
 155 \end_layout
 156
 157 \end_inset
 158
 159  subfolder of the \SpecialChar LyX
 160  source code distribution.
 161  This document is not translated, since the development language of \SpecialChar LyX
 162  is
 163  English.
 164  If you want to use \SpecialChar LyX
 165  you don't need to read this manual.
 166  However, if you want to learn more about how \SpecialChar LyX
 167  is developed, or even want
 168  to participate in \SpecialChar LyX
 169  development, you may find some interesting information.
 170 \end_layout
 171
 172 \begin_layout Section
 173 File formats
 174 \end_layout
 175
 176 \begin_layout Standard
 177 \SpecialChar LyX
 178  uses several custom file formats for configuration files and documents.
 179  This chapter contains some background concerning these file formats.
 180  Several file formats are also described in detail in the regular user documenta
 181 tion.
 182 \end_layout
 183
 184 \begin_layout Subsection
 185 File Format Numbers
 186 \end_layout
 187
 188 \begin_layout Subsection
 189 When is an update of the .lyx file format number needed?
 190 \begin_inset CommandInset label
 191 LatexCommand label
 192 name "sec:When-is-an"
 193
 194 \end_inset
 195
 196
 197 \end_layout
 198
 199 \begin_layout Standard
 200 When you are working on a new feature you may ask yourself whether it needs
 201  an update of the .lyx file format number.
 202  Whether an update is needed or not is not always obvious.
 203  Below you can find a list of reasons for file format updates with explanations:
 204 \end_layout
 205
 206 \begin_layout Description
 207 New
 208 \begin_inset space ~
 209 \end_inset
 210
 211 document
 212 \begin_inset space ~
 213 \end_inset
 214
 215 setting Whenever you introduce a new setting that is stored in the document
 216  header, a file format update is needed.
 217  This is also true if you add a new valid value to an existing setting,
 218  e.
 219 \begin_inset space \thinspace{}
 220 \end_inset
 221
 222 g.
 223 \begin_inset space \space{}
 224 \end_inset
 225
 226 a new language that is stored in
 227 \begin_inset Flex Code
 228 status collapsed
 229
 230 \begin_layout Plain Layout
 231
 232 \backslash
 233 language
 234 \end_layout
 235
 236 \end_inset
 237
 238 .
 239 \end_layout
 240
 241 \begin_layout Description
 242 Removed
 243 \begin_inset space ~
 244 \end_inset
 245
 246 document
 247 \begin_inset space ~
 248 \end_inset
 249
 250 setting If a certain setting becomes obsolete and gets removed, a file format
 251  update is needed.
 252 \end_layout
 253
 254 \begin_layout Description
 255 New
 256 \begin_inset space ~
 257 \end_inset
 258
 259 inset Of course a new inset requires a file format update.
 260 \end_layout
 261
 262 \begin_layout Description
 263 New
 264 \begin_inset space ~
 265 \end_inset
 266
 267 style in any layout file or module shipped with \SpecialChar LyX
 268 , or new shipped layout
 269  file or module.
 270  These requirements are currently under discussion and might change in the
 271  future.
 272 \end_layout
 273
 274 \begin_layout Description
 275 Automatically
 276 \begin_inset space ~
 277 \end_inset
 278
 279 loaded
 280 \begin_inset space ~
 281 \end_inset
 282
 283 math
 284 \begin_inset space ~
 285 \end_inset
 286
 287 package Any new math package that is automatically loaded needs a file format
 288  update.
 289  The reason for this is that there is no true ERT inset for math formulas:
 290  Each command is parsed, and if a user happens to define a local command
 291  with the same name as a command that triggers an automatic load of a package,
 292  he needs to be able to switch off the automatic loading of that package.
 293  This switch is stored by the
 294 \begin_inset Flex Code
 295 status collapsed
 296
 297 \begin_layout Plain Layout
 298 use_package
 299 \end_layout
 300
 301 \end_inset
 302
 303  header setting.
 304 \end_layout
 305
 306 \begin_layout Standard
 307 If you are still unsure, please ask on the development list.
 308 \end_layout
 309
 310 \begin_layout Subsection
 311 How to update the file format number of .lyx files
 312 \begin_inset CommandInset label
 313 LatexCommand label
 314 name "subsec:update_lyx_files"
 315
 316 \end_inset
 317
 318
 319 \end_layout
 320
 321 \begin_layout Standard
 322 Once you came to the conclusion that a file format update is needed you
 323  should use the following procedure to perform the update:
 324 \end_layout
 325
 326 \begin_layout Enumerate
 327 Implement and test the new feature, including the reading and writing of
 328  .lyx files.
 329  Note that any file produced at this stage does not use a valid format,
 330  so do not use this version of \SpecialChar LyX
 331  for working on any important documents.
 332 \end_layout
 333
 334 \begin_layout Enumerate
 335 \begin_inset CommandInset label
 336 LatexCommand label
 337 name "enu:Describe_format"
 338
 339 \end_inset
 340
 341 Describe the new format in
 342 \begin_inset Flex Code
 343 status collapsed
 344
 345 \begin_layout Plain Layout
 346 development/FORMAT
 347 \end_layout
 348
 349 \end_inset
 350
 351 .
 352 \end_layout
 353
 354 \begin_layout Enumerate
 355 Update the \SpecialChar LyX
 356  file format number in
 357 \begin_inset Flex Code
 358 status collapsed
 359
 360 \begin_layout Plain Layout
 361 src/version.h
 362 \end_layout
 363
 364 \end_inset
 365
 366 .
 367 \end_layout
 368
 369 \begin_layout Enumerate
 370 Update the range of file formats in the array
 371 \begin_inset Flex Code
 372 status collapsed
 373
 374 \begin_layout Plain Layout
 375 format_relation
 376 \end_layout
 377
 378 \end_inset
 379
 380  in
 381 \begin_inset Flex Code
 382 status collapsed
 383
 384 \begin_layout Plain Layout
 385 lib/lyx2lyx/LyX.py
 386 \end_layout
 387
 388 \end_inset
 389
 390 .
 391 \end_layout
 392
 393 \begin_layout Enumerate
 394 \begin_inset CommandInset label
 395 LatexCommand label
 396 name "enu:Add-an-entry"
 397
 398 \end_inset
 399
 400 Add an entry to both format lists (for conversion and reversion) in
 401 \begin_inset Newline newline
 402 \end_inset
 403
 404
 405 \begin_inset Flex Code
 406 status collapsed
 407
 408 \begin_layout Plain Layout
 409 lib/lyx2lyx/lyx_2_2.py
 410 \end_layout
 411
 412 \end_inset
 413
 414 .
 415  Add a conversion routine if needed (e.
 416 \begin_inset space \thinspace{}
 417 \end_inset
 418
 419 g.
 420 \begin_inset space \space{}
 421 \end_inset
 422
 423 a new header setting always needs a conversion that adds the new setting,
 424  a new document language does not need one).
 425  Add a reversion routine if needed.
 426  While the conversion routine is required to produce a document that is
 427  equivalent to the old version, the requirements of the reversion are not
 428  that strict.
 429  If possible, try to produce a proper reversion, using ERT if needed, but
 430  for some features this might be too complicated.
 431  In this case, the minimum requirement of the reversion routine is that
 432  it produces a valid document which can be read by an older \SpecialChar LyX
 433 .
 434  If absolutely needed, even data loss is allowed for the reversion.
 435 \end_layout
 436
 437 \begin_layout Enumerate
 438 Since tex2lyx has several implicit file format dependencies caused by sharing
 439  code with \SpecialChar LyX
 440 , updating the file format of .lyx files produced by tex2lyx at
 441  the same time as updating the main .lyx file format is strongly recommended.
 442  Therefore, a compiler warning will be issued if the \SpecialChar LyX
 443  and tex2lyx .lyx file
 444  format numbers differ.
 445  In many cases the tex2lyx update requires only the first and last item
 446  of the list below:
 447 \begin_inset Separator parbreak
 448 \end_inset
 449
 450
 451 \end_layout
 452
 453 \begin_deeper
 454 \begin_layout Enumerate
 455 Update the tex2lyx file format number in
 456 \begin_inset Flex Code
 457 status collapsed
 458
 459 \begin_layout Plain Layout
 460 src/version.h
 461 \end_layout
 462
 463 \end_inset
 464
 465 .
 466 \end_layout
 467
 468 \begin_layout Enumerate
 469 If the lyx2lyx conversion from the old to the new format is empty, or if
 470  tex2lyx does not yet output the changed feature, you do not need any further
 471  tex2lyx changes.
 472  Otherwise, search for the changed feature in tex2lyx, and adjust the output
 473  according to the lyx2lyx changes.
 474 \end_layout
 475
 476 \begin_layout Enumerate
 477 Update the tex2lyx test references as described in
 478 \begin_inset CommandInset ref
 479 LatexCommand formatted
 480 reference "sec:Updating-test-references"
 481
 482 \end_inset
 483
 484 .
 485 \end_layout
 486
 487 \end_deeper
 488 \begin_layout Enumerate
 489 If you did not implement full tex2lyx support of the new feature, add a
 490  line to
 491 \begin_inset Flex Code
 492 status collapsed
 493
 494 \begin_layout Plain Layout
 495 src/tex2lyx/TODO.txt
 496 \end_layout
 497
 498 \end_inset
 499
 500  describing the missing bits.
 501  Note that it is perfectly fine if you do not add full tex2lyx support for
 502  a new feature: The updating recommendation above is only issued for the
 503  syntax of the produced .lyx file.
 504  It is no problem if some features supported by \SpecialChar LyX
 505  are still output as ERT
 506  by tex2lyx, since the problems in the past that resulted in the update
 507  recommendation were related to mixed version syntax, not ERT.
 508 \end_layout
 509
 510 \begin_layout Enumerate
 511 It would be nice if you could create a .lyx test file which contains instances
 512  of all changed or added features.
 513  This could then be used to test lyx2lyx and tex2lyx.
 514  Unfortunately it has not yet been decided how to collect such examples,
 515  so please ask on the development list if you want to create one.
 516 \end_layout
 517
 518 \begin_layout Enumerate
 519 \begin_inset CommandInset label
 520 LatexCommand label
 521 name "enu:updatefiles"
 522
 523 \end_inset
 524
 525 Update LyX's .lyx documentation files to the new format.
 526  The developer who makes the change knows best what changes to expect when
 527  inspecting the resulting diff.
 528  Because of this, you might be able to catch a bug in the lyx2lyx code that
 529  updates the format just by taking a quick scan through the large diff that
 530  is the result
 531 \begin_inset Note Note
 532 status collapsed
 533
 534 \begin_layout Plain Layout
 535 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
 536  see which layout update made an unexpected change by looking at the git
 537  log of a .lyx file that suffers the problem.
 538 \end_layout
 539
 540 \end_inset
 541
 542 .
 543  To do this, first make sure that there are no changes to the git repository
 544  that you will not want to commit (this is needed because it will be convenient
 545  to commit with the command
 546 \begin_inset Flex Code
 547 status collapsed
 548
 549 \begin_layout Plain Layout
 550 git commit -a
 551 \end_layout
 552
 553 \end_inset
 554
 555 ).
 556  Then run the following command in the root folder of the source:
 557 \begin_inset Flex Code
 558 status collapsed
 559
 560 \begin_layout Plain Layout
 561 python development/tools/updatedocs.py
 562 \end_layout
 563
 564 \end_inset
 565
 566 .
 567  Look at the resulting changes using the command
 568 \begin_inset Flex Code
 569 status collapsed
 570
 571 \begin_layout Plain Layout
 572 git diff
 573 \end_layout
 574
 575 \end_inset
 576
 577 .
 578  If anything looks surprising, please investigate.
 579  Keep in mind that the case of
 580 \begin_inset Flex Code
 581 status collapsed
 582
 583 \begin_layout Plain Layout
 584 LFUNs.lyx
 585 \end_layout
 586
 587 \end_inset
 588
 589  is special, because it is first generated with
 590 \begin_inset Flex Code
 591 status collapsed
 592
 593 \begin_layout Plain Layout
 594 gen_lfuns.py
 595 \end_layout
 596
 597 \end_inset
 598
 599  before being converted to the latest format.
 600  Finally, commit using
 601 \begin_inset Flex Code
 602 status collapsed
 603
 604 \begin_layout Plain Layout
 605 git commit -a
 606 \end_layout
 607
 608 \end_inset
 609
 610 .
 611 \end_layout
 612
 613 \begin_layout Subsection
 614 Updating the file format number of layout files
 615 \end_layout
 616
 617 \begin_layout Standard
 618 See step
 619 \begin_inset CommandInset ref
 620 LatexCommand ref
 621 reference "enu:updatefiles"
 622
 623 \end_inset
 624
 625  in section
 626 \begin_inset CommandInset ref
 627 LatexCommand ref
 628 reference "subsec:update_lyx_files"
 629
 630 \end_inset
 631
 632  but instead of the
 633 \begin_inset Flex Code
 634 status collapsed
 635
 636 \begin_layout Plain Layout
 637 updatedocs.py
 638 \end_layout
 639
 640 \end_inset
 641
 642  command, use this command:
 643 \begin_inset Flex Code
 644 status collapsed
 645
 646 \begin_layout Plain Layout
 647 python development/tools/updatelayouts.py
 648 \end_layout
 649
 650 \end_inset
 651
 652 .
 653 \end_layout
 654
 655 \begin_layout Standard
 656 Note that we do not update the local layout of our
 657 \begin_inset Flex Code
 658 status collapsed
 659
 660 \begin_layout Plain Layout
 661 .lyx
 662 \end_layout
 663
 664 \end_inset
 665
 666  files because users would then not be able to export to older formats.
 667  For example, if a 2.2.0 user exported a template to 2.1.x format and tried
 668  to open the file in LyX 2.1.x, there would be an error because the file would
 669  contain a local layout whose format is too new.
 670  The root reason for this is that we do not support converting layouts to
 671  older layout formats, as we do for the
 672 \begin_inset Flex Code
 673 status collapsed
 674
 675 \begin_layout Plain Layout
 676 .lyx
 677 \end_layout
 678
 679 \end_inset
 680
 681  file format.
 682 \end_layout
 683
 684 \begin_layout Subsection
 685 Updating the file format number of bind/ui files
 686 \end_layout
 687
 688 \begin_layout Standard
 689 A change to the functionality of existing LFUNs can require a conversion
 690  of
 691 \begin_inset Flex Code
 692 status collapsed
 693
 694 \begin_layout Plain Layout
 695 .bind
 696 \end_layout
 697
 698 \end_inset
 699
 700  and
 701 \begin_inset Flex Code
 702 status collapsed
 703
 704 \begin_layout Plain Layout
 705 .ui
 706 \end_layout
 707
 708 \end_inset
 709
 710  files, and therefore an increment of the LFUN format, as well as a conversion
 711  of Info insets in
 712 \begin_inset Flex Code
 713 status collapsed
 714
 715 \begin_layout Plain Layout
 716 .lyx
 717 \end_layout
 718
 719 \end_inset
 720
 721  files for manuals.
 722  The latter cannot be done automatically and requires also a \SpecialChar LyX
 723  format increase
 724  (think of e.g.
 725  someone who might have made a set of \SpecialChar LyX
 726  teaching manuals for use in their
 727  own group)
 728 \begin_inset Foot
 729 status open
 730
 731 \begin_layout Plain Layout
 732 \begin_inset Flex URL
 733 status open
 734
 735 \begin_layout Plain Layout
 736
 737 http://www.lyx.org/trac/ticket/9794
 738 \end_layout
 739
 740 \end_inset
 741
 742
 743 \end_layout
 744
 745 \end_inset
 746
 747 .
 748 \end_layout
 749
 750 \begin_layout Enumerate
 751 Increment the LFUN file format number in
 752 \begin_inset Flex Code
 753 status collapsed
 754
 755 \begin_layout Plain Layout
 756 src/LyXAction.h
 757 \end_layout
 758
 759 \end_inset
 760
 761 .
 762 \end_layout
 763
 764 \begin_layout Enumerate
 765 Implement the LFUN conversion in
 766 \begin_inset Flex Code
 767 status collapsed
 768
 769 \begin_layout Plain Layout
 770 lib/scripts/prefs2prefs_lfuns.py
 771 \end_layout
 772
 773 \end_inset
 774
 775
 776 \end_layout
 777
 778 \begin_layout Enumerate
 779 See step
 780 \begin_inset CommandInset ref
 781 LatexCommand ref
 782 reference "enu:updatefiles"
 783
 784 \end_inset
 785
 786  in section
 787 \begin_inset CommandInset ref
 788 LatexCommand ref
 789 reference "subsec:update_lyx_files"
 790
 791 \end_inset
 792
 793  but instead of the
 794 \begin_inset Flex Code
 795 status collapsed
 796
 797 \begin_layout Plain Layout
 798 updatedocs.py
 799 \end_layout
 800
 801 \end_inset
 802
 803  command, use this command:
 804 \begin_inset Flex Code
 805 status collapsed
 806
 807 \begin_layout Plain Layout
 808 bash development/tools/updatelfuns.sh
 809 \end_layout
 810
 811 \end_inset
 812
 813 .
 814 \end_layout
 815
 816 \begin_layout Enumerate
 817 Update Info insets in
 818 \begin_inset Flex Code
 819 status collapsed
 820
 821 \begin_layout Plain Layout
 822 .lyx
 823 \end_layout
 824
 825 \end_inset
 826
 827  files.
 828  To do so, increment the \SpecialChar LyX
 829  format and proceed as in
 830 \begin_inset CommandInset ref
 831 LatexCommand ref
 832 reference "subsec:update_lyx_files"
 833
 834 \end_inset
 835
 836 , steps
 837 \begin_inset CommandInset ref
 838 LatexCommand ref
 839 reference "enu:Describe_format"
 840
 841 \end_inset
 842
 843 -
 844 \begin_inset CommandInset ref
 845 LatexCommand ref
 846 reference "enu:updatefiles"
 847
 848 \end_inset
 849
 850 .
 851  In the lyx2lyx implementation (
 852 \begin_inset CommandInset ref
 853 LatexCommand ref
 854 reference "enu:Add-an-entry"
 855
 856 \end_inset
 857
 858 th step), implement a conversion similar to the one in
 859 \begin_inset Flex Code
 860 status collapsed
 861
 862 \begin_layout Plain Layout
 863 prefs2prefs_lfuns.py
 864 \end_layout
 865
 866 \end_inset
 867
 868  above, as well as a corresponding reversion; for this one can use
 869 \begin_inset Flex Code
 870 status collapsed
 871
 872 \begin_layout Plain Layout
 873 convert_info_insets
 874 \end_layout
 875
 876 \end_inset
 877
 878  from
 879 \begin_inset Flex Code
 880 status collapsed
 881
 882 \begin_layout Plain Layout
 883 lib/lyx2lyx/lyx2lyx_tools.py
 884 \end_layout
 885
 886 \end_inset
 887
 888 .
 889
 890 \end_layout
 891
 892 \begin_layout Subsection
 893 Backporting new styles to the stable version
 894 \end_layout
 895
 896 \begin_layout Standard
 897 Starting with the stable \SpecialChar LyX
 898  2.1 branch, there is a mechanism in place to backport
 899  new styles to the stable version without the need to update the file format.
 900  The basic idea is that the new style definition is automatically copied
 901  to the document preamble, so that it can even be used by older minor revisions
 902  that did not yet include the style.
 903  To backport a new style to the stable version, the following steps are
 904  needed:
 905 \end_layout
 906
 907 \begin_layout Enumerate
 908 Add the line
 909 \begin_inset Flex Code
 910 status collapsed
 911
 912 \begin_layout Plain Layout
 913 ForceLocal -1
 914 \end_layout
 915
 916 \end_inset
 917
 918  to the style definition in the development version.
 919 \end_layout
 920
 921 \begin_layout Enumerate
 922 Copy the style definition to the stable version, but use
 923 \begin_inset Flex Code
 924 status collapsed
 925
 926 \begin_layout Plain Layout
 927 ForceLocal 1
 928 \end_layout
 929
 930 \end_inset
 931
 932  instead.
 933  If needed adjust the format to the one used by the stable version (see
 934  the customization manual for details of the layout file format).
 935 \end_layout
 936
 937 \begin_layout Enumerate
 938 For each update of the style in a later stable version, increase the argument
 939  of
 940 \begin_inset Flex Code
 941 status collapsed
 942
 943 \begin_layout Plain Layout
 944 ForceLocal
 945 \end_layout
 946
 947 \end_inset
 948
 949  by one (in the stable version, the development version should not be touched).
 950 \end_layout
 951
 952 \begin_layout Standard
 953 For details about the
 954 \begin_inset Flex Code
 955 status collapsed
 956
 957 \begin_layout Plain Layout
 958 ForceLocal
 959 \end_layout
 960
 961 \end_inset
 962
 963  flag see the customization manual.
 964  No
 965 \begin_inset Flex Code
 966 status collapsed
 967
 968 \begin_layout Plain Layout
 969 lyx2lyx
 970 \end_layout
 971
 972 \end_inset
 973
 974  support is needed for backported styles: Since the style of the development
 975  version has an infinite version number, it will always be used.
 976  Furthermore, since its version number is less than one, the style will
 977  not be written anymore to the document header for files saved by the new
 978  version.
 979 \end_layout
 980
 981 \begin_layout Standard
 982 \begin_inset Newpage newpage
 983 \end_inset
 984
 985
 986 \end_layout
 987
 988 \begin_layout Section
 989 Tests
 990 \end_layout
 991
 992 \begin_layout Standard
 993 Automated tests are an important tool to detect bugs and regressions in
 994  software development.
 995  Some projects like gcc even require each bug fix to be accompanied by a
 996  test case for the automatic test suite, that would detect this bug.
 997  Testing interactive features automatically is of course very hard, but
 998  core functionality like document import and export can be tested quite
 999  easily, and some tests of this kind exist.
1000 \end_layout
1001
1002 \begin_layout Subsection
1003 unit tests
1004 \end_layout
1005
1006 \begin_layout Standard
1007 There are attempts to set up a suite of unit tests for LyX.
1008 \end_layout
1009
1010 \begin_layout Standard
1011 TODO: describe what is done and what is still to do.
1012 \end_layout
1013
1014 \begin_layout Subsection
1015 tex2lyx tests
1016 \end_layout
1017
1018 \begin_layout Standard
1019 The tex2lyx tests are located in the
1020 \begin_inset Flex Code
1021 status collapsed
1022
1023 \begin_layout Plain Layout
1024 src/tex2lyx/test
1025 \end_layout
1026
1027 \end_inset
1028
1029  subfolder of the \SpecialChar LyX
1030  source code distribution.
1031  The actual testing is performed by the simple python script
1032 \begin_inset Flex Code
1033 status collapsed
1034
1035 \begin_layout Plain Layout
1036 src/tex2lyx/test/runtests.py
1037 \end_layout
1038
1039 \end_inset
1040
1041 .
1042  Each test consists of two files:
1043 \begin_inset Flex Code
1044 status collapsed
1045
1046 \begin_layout Plain Layout
1047 <test name>.tex
1048 \end_layout
1049
1050 \end_inset
1051
1052  contains the \SpecialChar LaTeX
1053  code that should be tested.
1054
1055 \begin_inset Flex Code
1056 status collapsed
1057
1058 \begin_layout Plain Layout
1059 <test name>.lyx.lyx
1060 \end_layout
1061
1062 \end_inset
1063
1064  contains the expected output of tex2lyx.
1065  When a test is run, the actual produced output is compared with the stored
1066  reference output.
1067  The test passes if both are identical.
1068  The test machinery is also able to generate a file
1069 \begin_inset Flex Code
1070 status collapsed
1071
1072 \begin_layout Plain Layout
1073 <test name>.lyx.tex
1074 \end_layout
1075
1076 \end_inset
1077
1078  by exporting the produced .lyx file with \SpecialChar LyX
1079  again.
1080  This may be useful for roundtrip comparisons.
1081 \end_layout
1082
1083 \begin_layout Subsubsection
1084 Running the tests
1085 \end_layout
1086
1087 \begin_layout Standard
1088 The tex2lyx tests can be run in several ways.
1089  When in the
1090 \begin_inset Flex Code
1091 status collapsed
1092
1093 \begin_layout Plain Layout
1094 src/tex2lyx
1095 \end_layout
1096
1097 \end_inset
1098
1099  subfolder of the build directory, the commands
1100 \begin_inset Flex Code
1101 status collapsed
1102
1103 \begin_layout Plain Layout
1104 ctest
1105 \end_layout
1106
1107 \end_inset
1108
1109  (cmake, all platforms),
1110 \begin_inset Flex Code
1111 status collapsed
1112
1113 \begin_layout Plain Layout
1114 make test
1115 \end_layout
1116
1117 \end_inset
1118
1119  (cmake, when using a make based build system and not MSVC) or
1120 \begin_inset Flex Code
1121 status collapsed
1122
1123 \begin_layout Plain Layout
1124 make alltests
1125 \end_layout
1126
1127 \end_inset
1128
1129  (autotools) will run the tex2lyx tests.
1130  Alternatively, in the root of the build directory, the command
1131 \begin_inset Flex Code
1132 status collapsed
1133
1134 \begin_layout Plain Layout
1135 ctest -R tex2lyx
1136 \end_layout
1137
1138 \end_inset
1139
1140  runs all tests whose names match the regex
1141 \begin_inset Quotes eld
1142 \end_inset
1143
1144 tex2lyx
1145 \begin_inset Quotes erd
1146 \end_inset
1147
1148 .
1149  Another way to run the tex2lyx tests in the root build directory is to
1150  instead use the command
1151 \begin_inset Flex Code
1152 status collapsed
1153
1154 \begin_layout Plain Layout
1155 ctest -L '(cmplyx|roundtrip)'
1156 \end_layout
1157
1158 \end_inset
1159
1160 , which runs all tests categorized with the label
1161 \begin_inset Quotes eld
1162 \end_inset
1163
1164 roundtrip
1165 \begin_inset Quotes erd
1166 \end_inset
1167
1168  or
1169 \begin_inset Quotes eld
1170 \end_inset
1171
1172 cmplyx
1173 \begin_inset Quotes erd
1174 \end_inset
1175
1176 .
1177  If a test fails, the differences between the expected and actual results
1178  are output in unified diff format.
1179 \end_layout
1180
1181 \begin_layout Subsubsection
1182 Updating test references
1183 \begin_inset CommandInset label
1184 LatexCommand label
1185 name "sec:Updating-test-references"
1186
1187 \end_inset
1188
1189
1190 \end_layout
1191
1192 \begin_layout Standard
1193 In some cases a changed tex2lyx output is not a test failure, but wanted,
1194  e.
1195 \begin_inset space \thinspace{}
1196 \end_inset
1197
1198 g.
1199 \begin_inset space \space{}
1200 \end_inset
1201
1202 if a tex2lyx bug was fixed, or a new feature was added.
1203  In these cases the stored references need to be updated.
1204  To do so if using autotools, call
1205 \begin_inset Flex Code
1206 status collapsed
1207
1208 \begin_layout Plain Layout
1209 make updatetests
1210 \end_layout
1211
1212 \end_inset
1213
1214  in the
1215 \begin_inset Flex Code
1216 status collapsed
1217
1218 \begin_layout Plain Layout
1219 src/tex2lyx
1220 \end_layout
1221
1222 \end_inset
1223
1224  subdirectory of the build directory.
1225  If instead using CMake, call
1226 \begin_inset Flex Code
1227 status collapsed
1228
1229 \begin_layout Plain Layout
1230 make updatetex2lyxtests
1231 \end_layout
1232
1233 \end_inset
1234
1235  in the build directory or in the
1236 \begin_inset Flex Code
1237 status collapsed
1238
1239 \begin_layout Plain Layout
1240 src/tex2lyx/test
1241 \end_layout
1242
1243 \end_inset
1244
1245  subdirectory of the build directory.
1246 \begin_inset Foot
1247 status collapsed
1248
1249 \begin_layout Plain Layout
1250 Note that this is a case where a make target in the build directory can
1251  affect the source directory, which might not be advisable.
1252 \end_layout
1253
1254 \end_inset
1255
1256  On Windows do the following:
1257 \end_layout
1258
1259 \begin_layout Itemize
1260 Assure that the path to the python.exe is in your system PATH variable.
1261 \end_layout
1262
1263 \begin_layout Itemize
1264 Double-click on the file
1265 \begin_inset Flex Code
1266 status collapsed
1267
1268 \begin_layout Plain Layout
1269 updatetex2lyxtests.vcxproj
1270 \end_layout
1271
1272 \end_inset
1273
1274  in the build directory or in the
1275 \begin_inset Flex Code
1276 status collapsed
1277
1278 \begin_layout Plain Layout
1279 src/tex2lyx/test
1280 \end_layout
1281
1282 \end_inset
1283
1284  subdirectory of your build directory.
1285 \end_layout
1286
1287 \begin_layout Itemize
1288 In the appearing MSVC program right-click on the project
1289 \family sans
1290 updatetex2lyxtests
1291 \family default
1292  in the project explorer and chose
1293 \family sans
1294 Create
1295 \family default
1296 .
1297 \end_layout
1298
1299 \begin_layout Standard
1300 For convenience, these commands also produce re-exported roundtrip .lyx.tex
1301  files.
1302  Please examine the changed output carefully before committing the changed
1303  files to the repository: Since the test machinery does not do a roundtrip
1304  test .tex
1305 \begin_inset Formula $\Rightarrow$
1306 \end_inset
1307
1308  .lyx
1309 \begin_inset Formula $\Rightarrow$
1310 \end_inset
1311
1312  .tex, and does not compare the produced dvi or pdf output, it assumes that
1313  the stored .lyx reference produces correct output if processed by \SpecialChar LyX
1314 .
1315  There is only one chance to detect wrong output: before committing a new
1316  reference.
1317  Once it is committed, it is quite difficult to verify whether it is correct.
1318 \end_layout
1319
1320 \begin_layout Standard
1321 Please
1322 \emph on
1323 do not
1324 \emph default
1325  update the test references by opening them with \SpecialChar LyX
1326  or directly running lyx2lyx
1327  on them.
1328  This would not work, since lyx2lyx and \SpecialChar LyX
1329  produce slightly different files
1330  regarding insignificant whitespace and line breaks.
1331 \end_layout
1332
1333 \begin_layout Subsubsection
1334 Adding a new test
1335 \end_layout
1336
1337 \begin_layout Standard
1338 In many cases tests for new features may be added to one of the existing
1339  test files, but sometimes this is not possible or not wanted.
1340  Then a new test file needs to be added:
1341 \end_layout
1342
1343 \begin_layout Enumerate
1344 Create the new file
1345 \begin_inset Flex Code
1346 status collapsed
1347
1348 \begin_layout Plain Layout
1349 src/tex2lyx/test/<test name>.tex
1350 \end_layout
1351
1352 \end_inset
1353
1354  and run tex2lyx in roundtrip mode to produce the file
1355 \begin_inset Flex Code
1356 status collapsed
1357
1358 \begin_layout Plain Layout
1359 src/tex2lyx/test/<test name>.lyx.lyx
1360 \end_layout
1361
1362 \end_inset
1363
1364 .
1365  This file will be the new reference.
1366 \end_layout
1367
1368 \begin_layout Enumerate
1369 Once you confirmed that the tex2lyx output is correct, add the new files
1370  to the corresponding lists in
1371 \begin_inset Flex Code
1372 status collapsed
1373
1374 \begin_layout Plain Layout
1375 src/tex2lyx/test/runtests.py
1376 \end_layout
1377
1378 \end_inset
1379
1380 ,
1381 \begin_inset Flex Code
1382 status collapsed
1383
1384 \begin_layout Plain Layout
1385 src/tex2lyx/Makefile.am
1386 \end_layout
1387
1388 \end_inset
1389
1390  and
1391 \begin_inset Flex Code
1392 status collapsed
1393
1394 \begin_layout Plain Layout
1395 src/tex2lyx/test/CMakeLists.txt
1396 \end_layout
1397
1398 \end_inset
1399
1400 .
1401 \end_layout
1402
1403 \begin_layout Enumerate
1404 Commit the changes to the repository, or send a patch to the development
1405  list and ask for committing if you do not have commit rights.
1406 \end_layout
1407
1408 \begin_layout Subsection
1409 ctest automatic tests
1410 \end_layout
1411
1412 \begin_layout Standard
1413 Some tests are located in the
1414 \begin_inset Flex Code
1415 status collapsed
1416
1417 \begin_layout Plain Layout
1418 development/autotests/
1419 \end_layout
1420
1421 \end_inset
1422
1423  subfolder of the \SpecialChar LyX
1424  source code distribution.
1425
1426 \begin_inset Foot
1427 status open
1428
1429 \begin_layout Plain Layout
1430 The README document in this folder only describes the
1431 \begin_inset Quotes eld
1432 \end_inset
1433
1434 keytests
1435 \begin_inset Quotes erd
1436 \end_inset
1437
1438  subset of autotests!
1439 \end_layout
1440
1441 \end_inset
1442
1443
1444 \end_layout
1445
1446 \begin_layout Standard
1447 These tests can be run by the commands
1448 \begin_inset Flex Code
1449 status collapsed
1450
1451 \begin_layout Plain Layout
1452 ctest
1453 \end_layout
1454
1455 \end_inset
1456
1457  in the
1458 \emph on
1459  build directory
1460 \emph default
1461  (all platforms) or (when using a make based build system and not MSVC)
1462
1463 \begin_inset Flex Code
1464 status collapsed
1465
1466 \begin_layout Plain Layout
1467 make test
1468 \end_layout
1469
1470 \end_inset
1471
1472  in the
1473 \begin_inset Flex Code
1474 status collapsed
1475
1476 \begin_layout Plain Layout
1477 autotests/
1478 \end_layout
1479
1480 \end_inset
1481
1482  subfolder of the
1483 \emph on
1484  build directory
1485 \emph default
1486 .
1487  The test logs are written to the
1488 \begin_inset Flex Code
1489 status collapsed
1490
1491 \begin_layout Plain Layout
1492 Testing/Temporary/
1493 \end_layout
1494
1495 \end_inset
1496
1497  subfolder of the
1498 \emph on
1499
1500 \emph default
1501 build directory.
1502
1503 \end_layout
1504
1505 \begin_layout Subsubsection
1506 Export tests
1507 \end_layout
1508
1509 \begin_layout Standard
1510 The export tests are integration tests.
1511  They take longer to run and are more likely to break than the tex2lyx tests.
1512  Nevertheless, they have caught many regressions and without a better alternativ
1513 e it is important to keep them up-to-date and understand how they work.
1514 \end_layout
1515
1516 \begin_layout Standard
1517 The export tests
1518 \begin_inset Quotes eld
1519 \end_inset
1520
1521 reuse
1522 \begin_inset Quotes erd
1523 \end_inset
1524
1525  documentation, template, and example documents.
1526  In addition, there are a number of dedicated sample documents in the
1527 \begin_inset Flex Code
1528 status collapsed
1529
1530 \begin_layout Plain Layout
1531 autotests/export/
1532 \end_layout
1533
1534 \end_inset
1535
1536  subfolder of the \SpecialChar LyX
1537  source code distribution.
1538  All samples are (after copying and eventual processing by scripts) exported
1539  to various output formats via the
1540 \begin_inset Flex Code
1541 status collapsed
1542
1543 \begin_layout Plain Layout
1544 —export-to
1545 \end_layout
1546
1547 \end_inset
1548
1549  command line option.
1550  The test checks for errors reported by LyX (However, error-free export
1551  is no guarantee for an error-free output document.)
1552 \end_layout
1553
1554 \begin_layout Paragraph
1555 Expectations of LyX developers
1556 \end_layout
1557
1558 \begin_layout Standard
1559 Because the export tests are integration tests and take a long time to run,
1560  LyX developers are rarely expected to run all of the tests.
1561  Here are some good practices to follow by developers:
1562 \end_layout
1563
1564 \begin_layout Itemize
1565 When making a non-trivial change to a .layout file, run the export and layout
1566  tests corresponding with that .layout file.
1567 \end_layout
1568
1569 \begin_layout Itemize
1570 When making non-trivial changes to a .lyx file, run the export tests correspondin
1571 g to that .lyx file.
1572 \end_layout
1573
1574 \begin_layout Itemize
1575 When making non-trivial changes to LyX's \SpecialChar LaTeX
1576  export code (e.g.
1577  touching the encoding code or package handling code that you expect will
1578  change the exported \SpecialChar LaTeX
1579  in some way):
1580 \end_layout
1581
1582 \begin_deeper
1583 \begin_layout Standard
1584 \paragraph_spacing single
1585 Consider running all of the export tests before and after your change.
1586  If there are differences, please reconcile these (i.e.
1587  fix the bug or fix the tests)
1588 \emph on
1589 before
1590 \emph default
1591  committing.
1592  Ask for help if you're not sure what to.
1593 \end_layout
1594
1595 \begin_layout Standard
1596 If you do not want to run the tests,
1597 \end_layout
1598
1599 \begin_layout Itemize
1600 post the patch on the list and others will run the tests and eventually
1601  ask for fixes, or
1602 \end_layout
1603
1604 \begin_layout Itemize
1605 commit, but be prepared to fix eventually arising problems or to revert
1606  the commit if there is no easy fix.
1607 \end_layout
1608
1609 \end_deeper
1610 \begin_layout Itemize
1611 Understand how to interpret test failures.
1612  If your commit is found to have broken a test, you should be able to interpret
1613  the test results when made aware of them.
1614  See Section
1615 \begin_inset CommandInset ref
1616 LatexCommand ref
1617 reference "subsec:Interpreting-export-tests"
1618
1619 \end_inset
1620
1621 .
1622 \end_layout
1623
1624 \begin_layout Paragraph
1625 \begin_inset CommandInset label
1626 LatexCommand label
1627 name "par:export-test-output-formats"
1628
1629 \end_inset
1630
1631 Output formats
1632 \end_layout
1633
1634 \begin_layout Standard
1635 The following output formats are currently tested for each sample document
1636  (see
1637 \begin_inset CommandInset ref
1638 LatexCommand ref
1639 reference "par:Export-test-filtering"
1640
1641 \end_inset
1642
1643  for exceptions):
1644 \end_layout
1645
1646 \begin_layout Labeling
1647 \labelwidthstring 00.00.0000
1648 LyX:
1649 \end_layout
1650
1651 \begin_deeper
1652 \begin_layout Labeling
1653 \labelwidthstring 00.00.0000
1654 lyx16 LyX 1.6 file format (lyx2lyx)
1655 \end_layout
1656
1657 \begin_layout Labeling
1658 \labelwidthstring 00.00.0000
1659 lyx21 LyX 2.1 file format (lyx2lyx)
1660 \end_layout
1661
1662 \begin_layout Labeling
1663 \labelwidthstring 00.00.0000
1664 xhtml LyXHTML (native LyX HTML export)
1665 \end_layout
1666
1667 \end_deeper
1668 \begin_layout Labeling
1669 \labelwidthstring 00.00.0000
1670 LyX
1671 \begin_inset space ~
1672 \end_inset
1673
1674 +
1675 \begin_inset space ~
1676 \end_inset
1677
1678 LaTeX:
1679 \end_layout
1680
1681 \begin_deeper
1682 \begin_layout Labeling
1683 \labelwidthstring pdf5msystemFM
1684 dvi DVI (8-bit latex)
1685 \end_layout
1686
1687 \begin_layout Labeling
1688 \labelwidthstring pdf5msystemFM
1689 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
1690 \end_layout
1691
1692 \begin_layout Labeling
1693 \labelwidthstring pdf5msystemFM
1694 dvi3_systemF DVI (LuaTeX with Unicode fonts)
1695 \end_layout
1696
1697 \begin_layout Labeling
1698 \labelwidthstring pdf5msystemFM
1699 pdf2 PDF (pdflatex)
1700 \end_layout
1701
1702 \begin_layout Labeling
1703 \labelwidthstring pdf5msystemFM
1704 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
1705 \end_layout
1706
1707 \begin_layout Labeling
1708 \labelwidthstring pdf5msystemFM
1709 pdf4_systemF PDF (XeTeX with Unicode fonts)
1710 \end_layout
1711
1712 \begin_layout Labeling
1713 \labelwidthstring pdf5msystemFM
1714 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
1715 \end_layout
1716
1717 \begin_layout Labeling
1718 \labelwidthstring pdf5msystemFM
1719 pdf5_systemF PDF (LuaTeX with Unicode fonts)
1720 \end_layout
1721
1722 \end_deeper
1723 \begin_layout Labeling
1724 \labelwidthstring 00.00.0000
1725 LyX
1726 \begin_inset space ~
1727 \end_inset
1728
1729 +
1730 \begin_inset space ~
1731 \end_inset
1732
1733 LaTeX
1734 \begin_inset space ~
1735 \end_inset
1736
1737 +
1738 \begin_inset space ~
1739 \end_inset
1740
1741 postprocessing:
1742 \end_layout
1743
1744 \begin_deeper
1745 \begin_layout Labeling
1746 \labelwidthstring pdf5msystemFM
1747 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
1748 \end_layout
1749
1750 \begin_layout Labeling
1751 \labelwidthstring pdf5msystemFM
1752 pdf3 DVI -> PDF (dvipdfm)
1753 \end_layout
1754
1755 \end_deeper
1756 \begin_layout Labeling
1757 \labelwidthstring 00.00.0000
1758 not
1759 \begin_inset space ~
1760 \end_inset
1761
1762 tested: (or only if set as default output format in the document source)
1763 \end_layout
1764
1765 \begin_deeper
1766 \begin_layout Labeling
1767 \labelwidthstring pdf5msystemFM
1768 latex LaTeX (plain)
1769 \end_layout
1770
1771 \begin_layout Labeling
1772 \labelwidthstring pdf5msystemFM
1773 luatex LaTeX (LuaTeX)
1774 \end_layout
1775
1776 \begin_layout Labeling
1777 \labelwidthstring pdf5msystemFM
1778 dviluatex LaTeX (dviluatex)
1779 \end_layout
1780
1781 \begin_layout Labeling
1782 \labelwidthstring pdf5msystemFM
1783 pdflatex LaTeX (pdflatex)
1784 \end_layout
1785
1786 \begin_layout Labeling
1787 \labelwidthstring pdf5msystemFM
1788 platex LaTeX (pLaTeX)
1789 \end_layout
1790
1791 \begin_layout Labeling
1792 \labelwidthstring pdf5msystemFM
1793 xetex LaTeX (XeTeX)
1794 \end_layout
1795
1796 \begin_layout Labeling
1797 \labelwidthstring pdf5msystemFM
1798 eps3 EPS (encapsulated Postscript) (cropped)
1799 \end_layout
1800
1801 \begin_layout Labeling
1802 \labelwidthstring pdf5msystemFM
1803 ps DVI -> Postscript (dvips)
1804 \end_layout
1805
1806 \begin_layout Labeling
1807 \labelwidthstring pdf5msystemFM
1808 odf
1809 \end_layout
1810
1811 \begin_layout Labeling
1812 \labelwidthstring pdf5msystemFM
1813 text (nor text2, ..., text4)
1814 \end_layout
1815
1816 \begin_layout Labeling
1817 \labelwidthstring pdf5msystemFM
1818 textparagraph
1819 \end_layout
1820
1821 \begin_layout Labeling
1822 \labelwidthstring pdf5msystemFM
1823 word
1824 \end_layout
1825
1826 \begin_layout Labeling
1827 \labelwidthstring pdf5msystemFM
1828 word2
1829 \end_layout
1830
1831 \begin_layout Labeling
1832 \labelwidthstring pdf5msystemFM
1833 wordhtml
1834 \end_layout
1835
1836 \end_deeper
1837 \begin_layout Paragraph
1838 \begin_inset CommandInset label
1839 LatexCommand label
1840 name "par:Configuring-ctests"
1841
1842 \end_inset
1843
1844 Configuring the tests
1845 \end_layout
1846
1847 \begin_layout Standard
1848 To enable the export autotests, add the
1849 \begin_inset Flex Code
1850 status collapsed
1851
1852 \begin_layout Plain Layout
1853 -DLYX_ENABLE_EXPORT_TESTS=ON
1854 \end_layout
1855
1856 \end_inset
1857
1858  flag.
1859  For example:
1860 \end_layout
1861
1862 \begin_layout Standard
1863 \begin_inset Flex Code
1864 status collapsed
1865
1866 \begin_layout Plain Layout
1867 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
1868 \end_layout
1869
1870 \end_inset
1871
1872
1873 \end_layout
1874
1875 \begin_layout Standard
1876 \noindent
1877 This flag will increase the time for the cmake command by several seconds,
1878  mainly because of the process of inverting tests (see Section
1879 \begin_inset CommandInset ref
1880 LatexCommand ref
1881 reference "subsec:Interpreting-export-tests"
1882
1883 \end_inset
1884
1885 ).
1886 \end_layout
1887
1888 \begin_layout Paragraph
1889 \begin_inset CommandInset label
1890 LatexCommand label
1891 name "par:ctest-options"
1892
1893 \end_inset
1894
1895 Running the tests
1896 \end_layout
1897
1898 \begin_layout Standard
1899 To run all tests, in the build directory simply run the command
1900 \begin_inset Flex Code
1901 status collapsed
1902
1903 \begin_layout Plain Layout
1904 ctest
1905 \end_layout
1906
1907 \end_inset
1908
1909 .
1910
1911 \end_layout
1912
1913 \begin_layout Standard
1914 To run only some of the tests, use command line options (see examples below):
1915 \end_layout
1916
1917 \begin_layout Labeling
1918 \labelwidthstring -R
1919 \begin_inset Flex Code
1920 status collapsed
1921
1922 \begin_layout Plain Layout
1923 -R <pattern>
1924 \end_layout
1925
1926 \end_inset
1927
1928  Run only the tests whose names match the given regular expression.
1929 \end_layout
1930
1931 \begin_layout Labeling
1932 \labelwidthstring -R
1933 \begin_inset Flex Code
1934 status collapsed
1935
1936 \begin_layout Plain Layout
1937 -L <pattern>
1938 \end_layout
1939
1940 \end_inset
1941
1942  Run only the tests whose labels match the given regular expression.
1943  A test may have more that one label.
1944
1945 \end_layout
1946
1947 \begin_layout Labeling
1948 \labelwidthstring -R
1949 \begin_inset Flex Code
1950 status collapsed
1951
1952 \begin_layout Plain Layout
1953 -E <pattern>
1954 \end_layout
1955
1956 \end_inset
1957
1958  Exclude the tests whose names match the given regular expression.
1959 \end_layout
1960
1961 \begin_layout Labeling
1962 \labelwidthstring -R
1963 \begin_inset Flex Code
1964 status collapsed
1965
1966 \begin_layout Plain Layout
1967 -LE <pattern>
1968 \end_layout
1969
1970 \end_inset
1971
1972  Exclude the tests whose labels match the given regular expression.
1973  Cannot be combined with
1974 \begin_inset Flex Code
1975 status collapsed
1976
1977 \begin_layout Plain Layout
1978 -L
1979 \end_layout
1980
1981 \end_inset
1982
1983 .
1984 \end_layout
1985
1986 \begin_layout Standard
1987 The following options help to find good selection patterns:
1988 \end_layout
1989
1990 \begin_layout Labeling
1991 \labelwidthstring -R
1992 \begin_inset Flex Code
1993 status collapsed
1994
1995 \begin_layout Plain Layout
1996 -N
1997 \end_layout
1998
1999 \end_inset
2000
2001  List the tests that would be run but not actually run them.
2002
2003 \end_layout
2004
2005 \begin_deeper
2006 \begin_layout Standard
2007 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2008  to know how many tests there are or whether your
2009 \begin_inset Flex Code
2010 status collapsed
2011
2012 \begin_layout Plain Layout
2013 <pattern>
2014 \end_layout
2015
2016 \end_inset
2017
2018  regular expression did what you expected.
2019 \end_layout
2020
2021 \end_deeper
2022 \begin_layout Labeling
2023 \labelwidthstring -R
2024 \begin_inset Flex Code
2025 status collapsed
2026
2027 \begin_layout Plain Layout
2028 \SpecialChar nobreakdash
2029 \SpecialChar nobreakdash
2030 print-labels
2031 \end_layout
2032
2033 \end_inset
2034
2035  print the list of all labels associated with the test set.
2036  Can also be combined with -R, -L, -E, ...
2037
2038 \end_layout
2039
2040 \begin_layout Standard
2041 Other useful options are:
2042 \end_layout
2043
2044 \begin_layout Labeling
2045 \labelwidthstring -R
2046 \begin_inset Flex Code
2047 status collapsed
2048
2049 \begin_layout Plain Layout
2050 -j <jobs>
2051 \end_layout
2052
2053 \end_inset
2054
2055  Run the tests in parallel using the given number of jobs.
2056 \end_layout
2057
2058 \begin_deeper
2059 \begin_layout Standard
2060 We are still working on getting the tests to run in parallel.
2061  However, when running the tests in parallel, sometimes tests fail that
2062  pass when run sequentially.
2063  A reasonable approach is to first run the tests in parallel and then run
2064  the failed tests sequentially.
2065
2066 \end_layout
2067
2068 \begin_layout Standard
2069 For example, to run 8 jobs at a time:
2070 \end_layout
2071
2072 \begin_layout Standard
2073 \begin_inset Flex Code
2074 status collapsed
2075
2076 \begin_layout Plain Layout
2077 ctest -j8
2078 \end_layout
2079
2080 \end_inset
2081
2082
2083 \end_layout
2084
2085 \begin_layout Standard
2086 \begin_inset Flex Code
2087 status collapsed
2088
2089 \begin_layout Plain Layout
2090 ctest \SpecialChar nobreakdash
2091 \SpecialChar nobreakdash
2092 rerun-failed
2093 \end_layout
2094
2095 \end_inset
2096
2097
2098 \end_layout
2099
2100 \begin_layout Standard
2101 \noindent
2102 Note that some tests cannot be run in parallel.
2103  These tests are marked in the code with the
2104 \begin_inset Flex Code
2105 status collapsed
2106
2107 \begin_layout Plain Layout
2108 \noindent
2109 RUN_SERIAL ON
2110 \end_layout
2111
2112 \end_inset
2113
2114  CMake property.
2115 \end_layout
2116
2117 \end_deeper
2118 \begin_layout Labeling
2119 \labelwidthstring -R
2120 \begin_inset Flex Code
2121 status collapsed
2122
2123 \begin_layout Plain Layout
2124 \SpecialChar nobreakdash
2125 \SpecialChar nobreakdash
2126 timeout <seconds>
2127 \end_layout
2128
2129 \end_inset
2130
2131  Set a global timeout on all tests that do not already have a timeout set
2132  on them.
2133 \end_layout
2134
2135 \begin_deeper
2136 \begin_layout Standard
2137 There have been bugs in LyX and in \SpecialChar LaTeX
2138  which cause compilation to hang, and
2139  without a timeout a test might never stop (in one case there was even a
2140  memory leak).
2141  If a test times out, the
2142 \begin_inset Flex Code
2143 status collapsed
2144
2145 \begin_layout Plain Layout
2146 ctest
2147 \end_layout
2148
2149 \end_inset
2150
2151  command exits with error, but you can distinguish between a timed out test
2152  and a failed test in the output reported at the end of the
2153 \begin_inset Flex Code
2154 status collapsed
2155
2156 \begin_layout Plain Layout
2157 ctest
2158 \end_layout
2159
2160 \end_inset
2161
2162  command.
2163 \end_layout
2164
2165 \end_deeper
2166 \begin_layout Standard
2167 See the manual (
2168 \begin_inset Flex Code
2169 status collapsed
2170
2171 \begin_layout Plain Layout
2172 man ctest
2173 \end_layout
2174
2175 \end_inset
2176
2177 ) the full list of command line options.
2178 \end_layout
2179
2180 \begin_layout Paragraph
2181 Examples
2182 \end_layout
2183
2184 \begin_layout Itemize
2185 run only the export tests:
2186 \begin_inset Flex Code
2187 status collapsed
2188
2189 \begin_layout Plain Layout
2190 ctest -L export
2191 \end_layout
2192
2193 \end_inset
2194
2195
2196 \end_layout
2197
2198 \begin_layout Itemize
2199 run inverted tests:
2200 \begin_inset Flex Code
2201 status collapsed
2202
2203 \begin_layout Plain Layout
2204 ctest -L "inverted|suspended"
2205 \end_layout
2206
2207 \end_inset
2208
2209
2210 \end_layout
2211
2212 \begin_layout Itemize
2213 list all export tests which match any of the labelling patterns:
2214 \begin_inset Flex Code
2215 status collapsed
2216
2217 \begin_layout Plain Layout
2218 ctest -N -R "
2219 \backslash
2220 ..*_export/"
2221 \end_layout
2222
2223 \end_inset
2224
2225
2226 \end_layout
2227
2228 \begin_layout Itemize
2229 exclude rarely used output formats and post-processing tests
2230 \begin_inset Flex Code
2231 status collapsed
2232
2233 \begin_layout Plain Layout
2234 ctest -L export -E "_(texF|dvi3|pdf3?)"
2235 \end_layout
2236
2237 \end_inset
2238
2239
2240 \end_layout
2241
2242 \begin_layout Paragraph
2243 \begin_inset CommandInset label
2244 LatexCommand label
2245 name "subsec:Interpreting-export-tests"
2246
2247 \end_inset
2248
2249 Interpreting the export test results
2250 \end_layout
2251
2252 \begin_layout Standard
2253 A test can fail for several reasons, not all of them bad.
2254 \end_layout
2255
2256 \begin_layout Enumerate
2257 A new or edited sample document may be incompatible with some output formats.
2258 \end_layout
2259
2260 \begin_layout Enumerate
2261 A dependency is not met (e.g.
2262  the \SpecialChar LaTeX
2263  class file).
2264  One hint that this is the case is that the corresponding
2265 \begin_inset Flex Code
2266 status collapsed
2267
2268 \begin_layout Plain Layout
2269 check_load
2270 \end_layout
2271
2272 \end_inset
2273
2274  test will likely also fail.
2275 \end_layout
2276
2277 \begin_layout Enumerate
2278 An inverted test fails to fail (i.e.
2279  export that previously failed now works).
2280 \end_layout
2281
2282 \begin_layout Enumerate
2283 An external dependency was updated (e.g.
2284  \SpecialChar TeX
2285  Live).
2286 \end_layout
2287
2288 \begin_layout Enumerate
2289 A recent code change introduced a bug.
2290 \end_layout
2291
2292 \begin_layout Enumerate
2293 \begin_inset CommandInset label
2294 LatexCommand label
2295 name "enu:exposed"
2296
2297 \end_inset
2298
2299 A change in a document exposed a previously unknown bug or an incompatibility
2300  with an export format (e.g.
2301  Lua\SpecialChar LaTeX
2302 ).
2303 \end_layout
2304
2305 \begin_layout Standard
2306 Because the .lyx files are exported in several formats, it is not surprising
2307  that many of the exports fail.
2308  This expectation of failure is addressed by
2309 \begin_inset Quotes eld
2310 \end_inset
2311
2312 inverting
2313 \begin_inset Quotes erd
2314 \end_inset
2315
2316  the tests, that is, by marking the test as
2317 \begin_inset Quotes eld
2318 \end_inset
2319
2320 passing
2321 \begin_inset Quotes erd
2322 \end_inset
2323
2324  if the export exits with error and as
2325 \begin_inset Quotes eld
2326 \end_inset
2327
2328 failing
2329 \begin_inset Quotes erd
2330 \end_inset
2331
2332  if the export succeeds
2333 \emph on
2334 .
2335
2336 \emph default
2337  It follows that these expected failures will not show up as failed tests
2338  in the test results and thus will not pollute the
2339 \begin_inset Quotes eld
2340 \end_inset
2341
2342 good
2343 \begin_inset Quotes erd
2344 \end_inset
2345
2346  tests.
2347  If the export actually succeeds, then the test will fail.
2348  The purpose of this failure is to get your attention—something has changed,
2349  possibly for the better.
2350 \end_layout
2351
2352 \begin_layout Standard
2353 We try to document why a test is inverted or ignored.
2354  See the comment (prefixed with
2355 \begin_inset Flex Code
2356 status collapsed
2357
2358 \begin_layout Plain Layout
2359 #
2360 \end_layout
2361
2362 \end_inset
2363
2364 ) above the block in which the test is listed as inverted or ignored in
2365  the files
2366 \begin_inset Flex Code
2367 status collapsed
2368
2369 \begin_layout Plain Layout
2370 development/autotests/suspiciousTests
2371 \end_layout
2372
2373 \end_inset
2374
2375 ,
2376 \begin_inset Flex Code
2377 status collapsed
2378
2379 \begin_layout Plain Layout
2380 development/autotests/unreliableTests
2381 \end_layout
2382
2383 \end_inset
2384
2385  and
2386 \begin_inset Flex Code
2387 status collapsed
2388
2389 \begin_layout Plain Layout
2390 development/autotests/ignoredTests
2391 \end_layout
2392
2393 \end_inset
2394
2395 .
2396
2397 \end_layout
2398
2399 \begin_layout Standard
2400 A good question is why do we enable the tests for non-default formats? The
2401  answer is that if a non-default route is broken it is often because a bug
2402  was introduced in LyX and not because a document-specific change was made
2403  that is not supported by the route.
2404  In other words, there is a high signal/noise ratio in the export tests
2405  for some non-default formats.
2406
2407 \end_layout
2408
2409 \begin_layout Standard
2410 When a test or several tests fail, consider checking the files in the
2411 \begin_inset Flex Code
2412 status collapsed
2413
2414 \begin_layout Plain Layout
2415 Testing/Temporary/
2416 \end_layout
2417
2418 \end_inset
2419
2420  subdirectory of your build directory.
2421  In this subdirectory are three files: the file
2422 \begin_inset Flex Code
2423 status collapsed
2424
2425 \begin_layout Plain Layout
2426 LastTestsFailed.log
2427 \end_layout
2428
2429 \end_inset
2430
2431  simply lists the tests that failed on your last
2432 \begin_inset Flex Code
2433 status collapsed
2434
2435 \begin_layout Plain Layout
2436 ctest
2437 \end_layout
2438
2439 \end_inset
2440
2441  command; the
2442 \begin_inset Flex Code
2443 status collapsed
2444
2445 \begin_layout Plain Layout
2446 LastTest.log
2447 \end_layout
2448
2449 \end_inset
2450
2451  file contains the output from the tests (and often has details explaining
2452  why a test failed); and the
2453 \begin_inset Flex Code
2454 status collapsed
2455
2456 \begin_layout Plain Layout
2457 CTestCostData.txt
2458 \end_layout
2459
2460 \end_inset
2461
2462  file lists the times that it took to run the tests.
2463 \end_layout
2464
2465 \begin_layout Paragraph
2466 What action should you take if a test fails?
2467 \end_layout
2468
2469 \begin_layout Standard
2470 \paragraph_spacing single
2471 It is always good to check manually why something fails and if it passes
2472  if the PDF output is good.
2473 \end_layout
2474
2475 \begin_layout Itemize
2476 Generally, if a change breaks compilation for the target format (for the
2477  manuals pdf2) without solving some important other issue,
2478 \emph on
2479 fix or revert the commit
2480 \emph default
2481  that led to failure.
2482 \end_layout
2483
2484 \begin_layout Itemize
2485 If it is not possible to (immediately) fix the failure but there are reasons
2486  not to revert the commit (e.g.
2487  it fixes another more important issue),
2488 \emph on
2489 invert
2490 \emph default
2491  the failing test case (see
2492 \begin_inset CommandInset ref
2493 LatexCommand ref
2494 reference "par:Inverted-tests"
2495
2496 \end_inset
2497
2498 ).
2499 \end_layout
2500
2501 \begin_layout Itemize
2502 If an
2503 \emph on
2504 inverted
2505 \emph default
2506  test case fails because the export now works,
2507 \emph on
2508 uninvert
2509 \emph default
2510  the test by removing the labeling pattern from
2511 \begin_inset Quotes eld
2512 \end_inset
2513
2514 suspiciousTests
2515 \begin_inset Quotes erd
2516 \end_inset
2517
2518 ) (see
2519 \begin_inset CommandInset ref
2520 LatexCommand ref
2521 reference "par:Inverted-tests"
2522
2523 \end_inset
2524
2525 ).
2526 \end_layout
2527
2528 \begin_layout Itemize
2529 If the export did not fail previously but led to wrong output (PDF, say),
2530  it is in fact an improvement when the test now fails, label it as
2531 \begin_inset Quotes eld
2532 \end_inset
2533
2534 unreliable:wrong:output
2535 \begin_inset Quotes erd
2536 \end_inset
2537
2538  (
2539 \begin_inset CommandInset ref
2540 LatexCommand ref
2541 reference "par:Unreliable-tests"
2542
2543 \end_inset
2544
2545 ).
2546 \end_layout
2547
2548 \begin_layout Paragraph
2549 \begin_inset CommandInset label
2550 LatexCommand label
2551 name "par:Inverted-tests"
2552
2553 \end_inset
2554
2555 Inverted tests
2556 \end_layout
2557
2558 \begin_layout Standard
2559 Test cases whose name matches a pattern in the file
2560 \begin_inset Flex Code
2561 status collapsed
2562
2563 \begin_layout Plain Layout
2564 development/autotests/suspiciousTests
2565 \end_layout
2566
2567 \end_inset
2568
2569  get the label
2570 \emph on
2571 inverted
2572 \emph default
2573 .
2574  They get also the test property
2575 \begin_inset Flex Code
2576 status collapsed
2577
2578 \begin_layout Plain Layout
2579 WILL_FAIL
2580 \end_layout
2581
2582 \end_inset
2583
2584 , i.e.
2585  they are reported as failing if the export works without error
2586 \begin_inset Flex URL
2587 status collapsed
2588
2589 \begin_layout Plain Layout
2590
2591 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
2592 \end_layout
2593
2594 \end_inset
2595
2596 .
2597 \end_layout
2598
2599 \begin_layout Standard
2600 Add failing cases to this file, if they cannot be solved
2601 \begin_inset Quotes eld
2602 \end_inset
2603
2604 immediately
2605 \begin_inset Quotes erd
2606 \end_inset
2607
2608  but it is expected that the export will work in a foreseeable future, e.g.
2609  low priority issues like failures to export to a non-target format (for
2610  the manuals everything except pdf2).
2611 \end_layout
2612
2613 \begin_layout Standard
2614 The following sublabels are currently present in
2615 \begin_inset Flex Code
2616 status collapsed
2617
2618 \begin_layout Plain Layout
2619 suspiciousTests
2620 \end_layout
2621
2622 \end_inset
2623
2624 :
2625 \end_layout
2626
2627 \begin_layout Description
2628 todo test failures that require attention:
2629 \end_layout
2630
2631 \begin_deeper
2632 \begin_layout Itemize
2633 minor issues to explore and properly sort later,
2634 \end_layout
2635
2636 \begin_layout Itemize
2637 easyfix issues,
2638 \end_layout
2639
2640 \begin_layout Itemize
2641 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
2642 \end_layout
2643
2644 \end_deeper
2645 \begin_layout Description
2646 lyxbugs LyX bugs with a Trac number.
2647 \end_layout
2648
2649 \begin_layout Description
2650 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
2651 \end_layout
2652
2653 \begin_deeper
2654 \begin_layout Standard
2655 "Wontfix" if demonstrating correct use and OK in the default output format.
2656 \end_layout
2657
2658 \end_deeper
2659 \begin_layout Description
2660 texissues Export fails due to LaTeX limitations like non-ASCII characters
2661  in verbatim or listings, incompatible packages, ...
2662 \end_layout
2663
2664 \begin_deeper
2665 \begin_layout Standard
2666 "Wontfix" if documents demonstrate correct use in the default output format:
2667 \end_layout
2668
2669 \begin_layout Itemize
2670 If the source can be made more robust without becoming "hackish", fix the
2671  source,
2672 \end_layout
2673
2674 \begin_layout Itemize
2675 if LyX could be enhanced to care for a permanent TeX limitation, file a
2676  ticket at trac and add a pattern under lyxbugs,
2677 \end_layout
2678
2679 \begin_layout Itemize
2680 otherwise, add a pattern here.
2681 \end_layout
2682
2683 \end_deeper
2684 \begin_layout Description
2685 attic Documents in the attic.
2686  (Kept for reference and format conversion test.)
2687 \end_layout
2688
2689 \begin_layout Subparagraph
2690 suspended
2691 \end_layout
2692
2693 \begin_layout Standard
2694 Test cases whose name additionally matches a pattern in the file
2695 \begin_inset Flex Code
2696 status collapsed
2697
2698 \begin_layout Plain Layout
2699 development/autotests/suspendedTests
2700 \end_layout
2701
2702 \end_inset
2703
2704  get the label
2705 \emph on
2706 suspended
2707 \emph default
2708 (instead of
2709 \emph on
2710 export
2711 \emph default
2712 and
2713 \emph on
2714  inverted
2715 \emph default
2716 ).
2717  This means they are not executed using
2718 \begin_inset Flex Code
2719 status collapsed
2720
2721 \begin_layout Plain Layout
2722 ctest -L export
2723 \end_layout
2724
2725 \end_inset
2726
2727  or
2728 \begin_inset Flex Code
2729 status collapsed
2730
2731 \begin_layout Plain Layout
2732 ctest -L inverted
2733 \end_layout
2734
2735 \end_inset
2736
2737 .
2738  However, they also get the test property
2739 \begin_inset Flex Code
2740 status collapsed
2741
2742 \begin_layout Plain Layout
2743 WILL_FAIL
2744 \end_layout
2745
2746 \end_inset
2747
2748 , i.e.
2749  they are reported as failing if the export works without error.
2750  From time to time they still have to be checked using
2751 \begin_inset Flex Code
2752 status collapsed
2753
2754 \begin_layout Plain Layout
2755 ctest -L suspended
2756 \end_layout
2757
2758 \end_inset
2759
2760 .
2761 \end_layout
2762
2763 \begin_layout Standard
2764 These tests are suspended, because the export fails for known reasons which
2765  cannot ATM be resolved.
2766  But it is expected the reason might disappear in the future.
2767  Be it new TL or better handling in \SpecialChar LyX
2768 .
2769 \end_layout
2770
2771 \begin_layout Standard
2772 For ctest commands without the
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  parameter nothing changes.
2783  Suspended or not, tests will be executed depending only on the selecting
2784  regular expression given to the ctest command (see
2785 \begin_inset CommandInset ref
2786 LatexCommand ref
2787 reference "par:ctest-options"
2788
2789 \end_inset
2790
2791 ).
2792 \end_layout
2793
2794 \begin_layout Paragraph
2795 \begin_inset CommandInset label
2796 LatexCommand label
2797 name "par:Unreliable-tests"
2798
2799 \end_inset
2800
2801 Unreliable tests
2802 \end_layout
2803
2804 \begin_layout Standard
2805 Test cases whose name matches a pattern in the file
2806 \begin_inset Flex Code
2807 status collapsed
2808
2809 \begin_layout Plain Layout
2810 development/autotests/unreliableTests
2811 \end_layout
2812
2813 \end_inset
2814
2815  get the label
2816 \emph on
2817 unreliable
2818 \emph default
2819 .
2820 \end_layout
2821
2822 \begin_layout Standard
2823 These tests are not executed using
2824 \begin_inset Flex Code
2825 status collapsed
2826
2827 \begin_layout Plain Layout
2828 ctest -L export
2829 \end_layout
2830
2831 \end_inset
2832
2833  or
2834 \begin_inset Flex Code
2835 status collapsed
2836
2837 \begin_layout Plain Layout
2838 ctest -L inverted
2839 \end_layout
2840
2841 \end_inset
2842
2843 .
2844
2845 \end_layout
2846
2847 \begin_layout Standard
2848 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
2849  or pass but should rather fail (wrong output).
2850
2851 \begin_inset Note Note
2852 status collapsed
2853
2854 \begin_layout Plain Layout
2855 *invalid* tests (wrong output) are not *unreliable*.
2856  # Use "unfit" or "unapplicable" as better label and name of pattern file?
2857
2858 \end_layout
2859
2860 \end_inset
2861
2862
2863 \end_layout
2864
2865 \begin_layout Description
2866 nonstandard Documents with additional requirements, e.g.
2867  a class or package file not in TeXLive.
2868
2869 \begin_inset Note Note
2870 status open
2871
2872 \begin_layout Plain Layout
2873 TODO: rename to "extra"?
2874 \end_layout
2875
2876 \end_inset
2877
2878
2879 \end_layout
2880
2881 \begin_deeper
2882 \begin_layout Standard
2883 These tests are labeled as
2884 \family typewriter
2885 'nonstandard'.
2886 \end_layout
2887
2888 \end_deeper
2889 \begin_layout Description
2890 erratic Tests depending on local configuration, OS, TeX distribution, package
2891  versions, or the phase of the moon.
2892
2893 \begin_inset Note Note
2894 status open
2895
2896 \begin_layout Plain Layout
2897 TODO: use
2898 \emph on
2899 erratic
2900 \emph default
2901  only for the phase-of-moon dependency?
2902 \end_layout
2903
2904 \end_inset
2905
2906
2907 \end_layout
2908
2909 \begin_deeper
2910 \begin_layout Standard
2911 These tests are labeled as
2912 \family typewriter
2913 'erratic'.
2914 \end_layout
2915
2916 \end_deeper
2917 \begin_layout Description
2918 wrong
2919 \begin_inset space ~
2920 \end_inset
2921
2922 output Export does not fail but the resulting document has errors.
2923 \end_layout
2924
2925 \begin_deeper
2926 \begin_layout Standard
2927 \paragraph_spacing single
2928 \begin_inset Note Note
2929 status open
2930
2931 \begin_layout Plain Layout
2932 \paragraph_spacing single
2933 These tests are actually not
2934 \emph on
2935 unreliable
2936 \emph default
2937  but
2938 \emph on
2939 invalid
2940 \emph default
2941  (not measuring what they should measure).
2942 \end_layout
2943
2944 \end_inset
2945
2946
2947 \end_layout
2948
2949 \end_deeper
2950 \begin_layout Paragraph
2951 \begin_inset CommandInset label
2952 LatexCommand label
2953 name "par:Export-test-filtering"
2954
2955 \end_inset
2956
2957 Export test filtering
2958 \end_layout
2959
2960 \begin_layout Standard
2961 The assignment of a label to a test is controlled by a set of files with
2962  regular expressions that are matched against the test names.
2963 \end_layout
2964
2965 \begin_layout Description
2966 ignoredTests (small file)
2967 \begin_inset Newline newline
2968 \end_inset
2969
2970 Tests selected here are withdrawn in the configuration step (cf.
2971
2972 \begin_inset CommandInset ref
2973 LatexCommand ref
2974 reference "par:Configuring-ctests"
2975
2976 \end_inset
2977
2978 ).
2979 \end_layout
2980
2981 \begin_deeper
2982 \begin_layout Labeling
2983 \labelwidthstring 00.00.0000
2984 Input Test of any export combination
2985 \end_layout
2986
2987 \begin_layout Labeling
2988 \labelwidthstring 00.00.0000
2989 Output Stop if tests not selected here
2990 \end_layout
2991
2992 \end_deeper
2993 \begin_layout Description
2994 unreliableTests: Tests selected either pass or fail, but that is dependent
2995  on the system where the test is run.
2996  Selected tests gain the label 'unreliable'.
2997 \end_layout
2998
2999 \begin_deeper
3000 \begin_layout Labeling
3001 \labelwidthstring 00.00.0000
3002 Input Each test which passed 'ignoredTests'
3003 \end_layout
3004
3005 \begin_layout Labeling
3006 \labelwidthstring 00.00.0000
3007 Output Stop if test selected, gain label 'unreliable'.
3008 \end_layout
3009
3010 \end_deeper
3011 \begin_layout Description
3012 suspiciousTests
3013 \begin_inset space \space{}
3014 \end_inset
3015
3016
3017 \end_layout
3018
3019 \begin_deeper
3020 \begin_layout Labeling
3021 \labelwidthstring 00.00.0000
3022 Input Each test which passed 'unreliableTests'
3023 \end_layout
3024
3025 \begin_layout Labeling
3026 \labelwidthstring 00.00.0000
3027 Output Stop if not selected.
3028 \end_layout
3029
3030 \begin_layout Standard
3031 The following file is meant as subselections of 'suspiciousTests'.
3032  If neither subselection applies, test gains labels 'export' and 'inverted'
3033 \end_layout
3034
3035 \begin_layout Description
3036 suspendedTests Tests selected here gain the label 'suspended' but _not_
3037  'export' or 'inverted', although in ctest they remain inverted.
3038  ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3039 \end_layout
3040
3041 \begin_deeper
3042 \begin_layout Labeling
3043 \labelwidthstring 00.00.0000
3044 Input Each test selected by 'suspiciousTests'
3045 \end_layout
3046
3047 \begin_layout Labeling
3048 \labelwidthstring 00.00.0000
3049 Output Selected test gains label 'suspended'.
3050
3051 \end_layout
3052
3053 \end_deeper
3054 \end_deeper
3055 \begin_layout Standard
3056 The following table may clarify label assignement
3057 \end_layout
3058
3059 \begin_layout Standard
3060 \begin_inset Tabular
3061 <lyxtabular version="3" rows="7" columns="12">
3062 <features tabularvalignment="middle">
3063 <column alignment="left" valignment="top" width="0pt">
3064 <column alignment="left" valignment="top" width="0pt">
3065 <column alignment="left" valignment="top" width="0pt">
3066 <column alignment="left" valignment="top" width="0pt">
3067 <column alignment="center" valignment="top">
3068 <column alignment="center" valignment="top">
3069 <column alignment="center" valignment="top">
3070 <column alignment="center" valignment="top">
3071 <column alignment="center" valignment="top">
3072 <column alignment="center" valignment="top">
3073 <column alignment="center" valignment="top">
3074 <column alignment="center" valignment="top">
3075 <row>
3076 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3077 \begin_inset Text
3078
3079 \begin_layout Plain Layout
3080 Test found in file:
3081 \end_layout
3082
3083 \end_inset
3084 </cell>
3085 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3086 \begin_inset Text
3087
3088 \begin_layout Plain Layout
3089
3090 \end_layout
3091
3092 \end_inset
3093 </cell>
3094 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3095 \begin_inset Text
3096
3097 \begin_layout Plain Layout
3098
3099 \end_layout
3100
3101 \end_inset
3102 </cell>
3103 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3104 \begin_inset Text
3105
3106 \begin_layout Plain Layout
3107
3108 \end_layout
3109
3110 \end_inset
3111 </cell>
3112 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3113 \begin_inset Text
3114
3115 \begin_layout Plain Layout
3116 Marked in ctest, Assigned label
3117 \end_layout
3118
3119 \end_inset
3120 </cell>
3121 <cell multicolumn="2" alignment="center" valignment="top" usebox="none">
3122 \begin_inset Text
3123
3124 \begin_layout Plain Layout
3125
3126 \end_layout
3127
3128 \end_inset
3129 </cell>
3130 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3131 \begin_inset Text
3132
3133 \begin_layout Plain Layout
3134
3135 \end_layout
3136
3137 \end_inset
3138 </cell>
3139 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3140 \begin_inset Text
3141
3142 \begin_layout Plain Layout
3143
3144 \end_layout
3145
3146 \end_inset
3147 </cell>
3148 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3149 \begin_inset Text
3150
3151 \begin_layout Plain Layout
3152
3153 \end_layout
3154
3155 \end_inset
3156 </cell>
3157 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3158 \begin_inset Text
3159
3160 \begin_layout Plain Layout
3161
3162 \end_layout
3163
3164 \end_inset
3165 </cell>
3166 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3167 \begin_inset Text
3168
3169 \begin_layout Plain Layout
3170
3171 \end_layout
3172
3173 \end_inset
3174 </cell>
3175 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3176 \begin_inset Text
3177
3178 \begin_layout Plain Layout
3179
3180 \end_layout
3181
3182 \end_inset
3183 </cell>
3184 </row>
3185 <row>
3186 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3187 \begin_inset Text
3188
3189 \begin_layout Plain Layout
3190 Ignored
3191 \end_layout
3192
3193 \end_inset
3194 </cell>
3195 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3196 \begin_inset Text
3197
3198 \begin_layout Plain Layout
3199 Unreliable
3200 \end_layout
3201
3202 \end_inset
3203 </cell>
3204 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3205 \begin_inset Text
3206
3207 \begin_layout Plain Layout
3208 Suspicious
3209 \end_layout
3210
3211 \end_inset
3212 </cell>
3213 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3214 \begin_inset Text
3215
3216 \begin_layout Plain Layout
3217 Suspended
3218 \end_layout
3219
3220 \end_inset
3221 </cell>
3222 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3223 \begin_inset Text
3224
3225 \begin_layout Plain Layout
3226 export
3227 \end_layout
3228
3229 \end_inset
3230 </cell>
3231 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
3232 \begin_inset Text
3233
3234 \begin_layout Plain Layout
3235
3236 \end_layout
3237
3238 \end_inset
3239 </cell>
3240 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3241 \begin_inset Text
3242
3243 \begin_layout Plain Layout
3244 unreliable
3245 \end_layout
3246
3247 \end_inset
3248 </cell>
3249 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
3250 \begin_inset Text
3251
3252 \begin_layout Plain Layout
3253
3254 \end_layout
3255
3256 \end_inset
3257 </cell>
3258 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3259 \begin_inset Text
3260
3261 \begin_layout Plain Layout
3262 inverted
3263 \end_layout
3264
3265 \end_inset
3266 </cell>
3267 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
3268 \begin_inset Text
3269
3270 \begin_layout Plain Layout
3271
3272 \end_layout
3273
3274 \end_inset
3275 </cell>
3276 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3277 \begin_inset Text
3278
3279 \begin_layout Plain Layout
3280 suspended
3281 \end_layout
3282
3283 \end_inset
3284 </cell>
3285 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3286 \begin_inset Text
3287
3288 \begin_layout Plain Layout
3289
3290 \end_layout
3291
3292 \end_inset
3293 </cell>
3294 </row>
3295 <row>
3296 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3297 \begin_inset Text
3298
3299 \begin_layout Plain Layout
3300 Yes
3301 \end_layout
3302
3303 \end_inset
3304 </cell>
3305 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3306 \begin_inset Text
3307
3308 \begin_layout Plain Layout
3309 -
3310 \end_layout
3311
3312 \end_inset
3313 </cell>
3314 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3315 \begin_inset Text
3316
3317 \begin_layout Plain Layout
3318 -
3319 \end_layout
3320
3321 \end_inset
3322 </cell>
3323 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3324 \begin_inset Text
3325
3326 \begin_layout Plain Layout
3327 -
3328 \end_layout
3329
3330 \end_inset
3331 </cell>
3332 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3333 \begin_inset Text
3334
3335 \begin_layout Plain Layout
3336 -
3337 \end_layout
3338
3339 \end_inset
3340 </cell>
3341 <cell alignment="center" valignment="top" topline="true" usebox="none">
3342 \begin_inset Text
3343
3344 \begin_layout Plain Layout
3345 -
3346 \end_layout
3347
3348 \end_inset
3349 </cell>
3350 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3351 \begin_inset Text
3352
3353 \begin_layout Plain Layout
3354 -
3355 \end_layout
3356
3357 \end_inset
3358 </cell>
3359 <cell alignment="center" valignment="top" topline="true" usebox="none">
3360 \begin_inset Text
3361
3362 \begin_layout Plain Layout
3363
3364 \end_layout
3365
3366 \end_inset
3367 </cell>
3368 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3369 \begin_inset Text
3370
3371 \begin_layout Plain Layout
3372 -
3373 \end_layout
3374
3375 \end_inset
3376 </cell>
3377 <cell alignment="center" valignment="top" topline="true" usebox="none">
3378 \begin_inset Text
3379
3380 \begin_layout Plain Layout
3381 -
3382 \end_layout
3383
3384 \end_inset
3385 </cell>
3386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3387 \begin_inset Text
3388
3389 \begin_layout Plain Layout
3390 -
3391 \end_layout
3392
3393 \end_inset
3394 </cell>
3395 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3396 \begin_inset Text
3397
3398 \begin_layout Plain Layout
3399 -
3400 \end_layout
3401
3402 \end_inset
3403 </cell>
3404 </row>
3405 <row>
3406 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3407 \begin_inset Text
3408
3409 \begin_layout Plain Layout
3410 No
3411 \end_layout
3412
3413 \end_inset
3414 </cell>
3415 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3416 \begin_inset Text
3417
3418 \begin_layout Plain Layout
3419 Yes
3420 \end_layout
3421
3422 \end_inset
3423 </cell>
3424 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3425 \begin_inset Text
3426
3427 \begin_layout Plain Layout
3428 -
3429 \end_layout
3430
3431 \end_inset
3432 </cell>
3433 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3434 \begin_inset Text
3435
3436 \begin_layout Plain Layout
3437 -
3438 \end_layout
3439
3440 \end_inset
3441 </cell>
3442 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3443 \begin_inset Text
3444
3445 \begin_layout Plain Layout
3446 -
3447 \end_layout
3448
3449 \end_inset
3450 </cell>
3451 <cell alignment="center" valignment="top" topline="true" usebox="none">
3452 \begin_inset Text
3453
3454 \begin_layout Plain Layout
3455 -
3456 \end_layout
3457
3458 \end_inset
3459 </cell>
3460 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3461 \begin_inset Text
3462
3463 \begin_layout Plain Layout
3464 -
3465 \end_layout
3466
3467 \end_inset
3468 </cell>
3469 <cell alignment="center" valignment="top" topline="true" usebox="none">
3470 \begin_inset Text
3471
3472 \begin_layout Plain Layout
3473 +
3474 \end_layout
3475
3476 \end_inset
3477 </cell>
3478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3479 \begin_inset Text
3480
3481 \begin_layout Plain Layout
3482 -
3483 \end_layout
3484
3485 \end_inset
3486 </cell>
3487 <cell alignment="center" valignment="top" topline="true" usebox="none">
3488 \begin_inset Text
3489
3490 \begin_layout Plain Layout
3491 -
3492 \end_layout
3493
3494 \end_inset
3495 </cell>
3496 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3497 \begin_inset Text
3498
3499 \begin_layout Plain Layout
3500 -
3501 \end_layout
3502
3503 \end_inset
3504 </cell>
3505 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3506 \begin_inset Text
3507
3508 \begin_layout Plain Layout
3509 -
3510 \end_layout
3511
3512 \end_inset
3513 </cell>
3514 </row>
3515 <row>
3516 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
3517 \begin_inset Text
3518
3519 \begin_layout Plain Layout
3520
3521 \end_layout
3522
3523 \end_inset
3524 </cell>
3525 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3526 \begin_inset Text
3527
3528 \begin_layout Plain Layout
3529 No
3530 \end_layout
3531
3532 \end_inset
3533 </cell>
3534 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
3535 \begin_inset Text
3536
3537 \begin_layout Plain Layout
3538 Yes
3539 \end_layout
3540
3541 \end_inset
3542 </cell>
3543 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3544 \begin_inset Text
3545
3546 \begin_layout Plain Layout
3547 Yes
3548 \end_layout
3549
3550 \end_inset
3551 </cell>
3552 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3553 \begin_inset Text
3554
3555 \begin_layout Plain Layout
3556 -
3557 \end_layout
3558
3559 \end_inset
3560 </cell>
3561 <cell alignment="center" valignment="top" topline="true" usebox="none">
3562 \begin_inset Text
3563
3564 \begin_layout Plain Layout
3565 -
3566 \end_layout
3567
3568 \end_inset
3569 </cell>
3570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3571 \begin_inset Text
3572
3573 \begin_layout Plain Layout
3574 -
3575 \end_layout
3576
3577 \end_inset
3578 </cell>
3579 <cell alignment="center" valignment="top" topline="true" usebox="none">
3580 \begin_inset Text
3581
3582 \begin_layout Plain Layout
3583 -
3584 \end_layout
3585
3586 \end_inset
3587 </cell>
3588 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3589 \begin_inset Text
3590
3591 \begin_layout Plain Layout
3592 +
3593 \end_layout
3594
3595 \end_inset
3596 </cell>
3597 <cell alignment="center" valignment="top" topline="true" usebox="none">
3598 \begin_inset Text
3599
3600 \begin_layout Plain Layout
3601 -
3602 \end_layout
3603
3604 \end_inset
3605 </cell>
3606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3607 \begin_inset Text
3608
3609 \begin_layout Plain Layout
3610 -
3611 \end_layout
3612
3613 \end_inset
3614 </cell>
3615 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3616 \begin_inset Text
3617
3618 \begin_layout Plain Layout
3619 +
3620 \end_layout
3621
3622 \end_inset
3623 </cell>
3624 </row>
3625 <row>
3626 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3627 \begin_inset Text
3628
3629 \begin_layout Plain Layout
3630
3631 \end_layout
3632
3633 \end_inset
3634 </cell>
3635 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3636 \begin_inset Text
3637
3638 \begin_layout Plain Layout
3639
3640 \end_layout
3641
3642 \end_inset
3643 </cell>
3644 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3645 \begin_inset Text
3646
3647 \begin_layout Plain Layout
3648
3649 \end_layout
3650
3651 \end_inset
3652 </cell>
3653 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3654 \begin_inset Text
3655
3656 \begin_layout Plain Layout
3657 No
3658 \end_layout
3659
3660 \end_inset
3661 </cell>
3662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3663 \begin_inset Text
3664
3665 \begin_layout Plain Layout
3666 -
3667 \end_layout
3668
3669 \end_inset
3670 </cell>
3671 <cell alignment="center" valignment="top" topline="true" usebox="none">
3672 \begin_inset Text
3673
3674 \begin_layout Plain Layout
3675 +
3676 \end_layout
3677
3678 \end_inset
3679 </cell>
3680 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3681 \begin_inset Text
3682
3683 \begin_layout Plain Layout
3684 -
3685 \end_layout
3686
3687 \end_inset
3688 </cell>
3689 <cell alignment="center" valignment="top" topline="true" usebox="none">
3690 \begin_inset Text
3691
3692 \begin_layout Plain Layout
3693 -
3694 \end_layout
3695
3696 \end_inset
3697 </cell>
3698 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3699 \begin_inset Text
3700
3701 \begin_layout Plain Layout
3702 +
3703 \end_layout
3704
3705 \end_inset
3706 </cell>
3707 <cell alignment="center" valignment="top" topline="true" usebox="none">
3708 \begin_inset Text
3709
3710 \begin_layout Plain Layout
3711 +
3712 \end_layout
3713
3714 \end_inset
3715 </cell>
3716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3717 \begin_inset Text
3718
3719 \begin_layout Plain Layout
3720 -
3721 \end_layout
3722
3723 \end_inset
3724 </cell>
3725 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3726 \begin_inset Text
3727
3728 \begin_layout Plain Layout
3729 -
3730 \end_layout
3731
3732 \end_inset
3733 </cell>
3734 </row>
3735 <row>
3736 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3737 \begin_inset Text
3738
3739 \begin_layout Plain Layout
3740
3741 \end_layout
3742
3743 \end_inset
3744 </cell>
3745 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3746 \begin_inset Text
3747
3748 \begin_layout Plain Layout
3749
3750 \end_layout
3751
3752 \end_inset
3753 </cell>
3754 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3755 \begin_inset Text
3756
3757 \begin_layout Plain Layout
3758 No
3759 \end_layout
3760
3761 \end_inset
3762 </cell>
3763 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3764 \begin_inset Text
3765
3766 \begin_layout Plain Layout
3767 -
3768 \end_layout
3769
3770 \end_inset
3771 </cell>
3772 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3773 \begin_inset Text
3774
3775 \begin_layout Plain Layout
3776 -
3777 \end_layout
3778
3779 \end_inset
3780 </cell>
3781 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
3782 \begin_inset Text
3783
3784 \begin_layout Plain Layout
3785 +
3786 \end_layout
3787
3788 \end_inset
3789 </cell>
3790 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3791 \begin_inset Text
3792
3793 \begin_layout Plain Layout
3794 -
3795 \end_layout
3796
3797 \end_inset
3798 </cell>
3799 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
3800 \begin_inset Text
3801
3802 \begin_layout Plain Layout
3803 -
3804 \end_layout
3805
3806 \end_inset
3807 </cell>
3808 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3809 \begin_inset Text
3810
3811 \begin_layout Plain Layout
3812 -
3813 \end_layout
3814
3815 \end_inset
3816 </cell>
3817 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
3818 \begin_inset Text
3819
3820 \begin_layout Plain Layout
3821 -
3822 \end_layout
3823
3824 \end_inset
3825 </cell>
3826 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3827 \begin_inset Text
3828
3829 \begin_layout Plain Layout
3830 -
3831 \end_layout
3832
3833 \end_inset
3834 </cell>
3835 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
3836 \begin_inset Text
3837
3838 \begin_layout Plain Layout
3839 -
3840 \end_layout
3841
3842 \end_inset
3843 </cell>
3844 </row>
3845 </lyxtabular>
3846
3847 \end_inset
3848
3849
3850 \end_layout
3851
3852 \begin_layout Subsubsection
3853 check_load tests
3854 \end_layout
3855
3856 \begin_layout Standard
3857 These tests check whether a .lyx file loads without any terminal messages.
3858  They correspond to the manual operations of simply opening a .lyx file on
3859  the terminal, exiting LyX once the file is loaded, and then checking whether
3860  there is any output from the terminal.
3861  These tests are useful for catching malformed .lyx files and parsing bugs.
3862  They can also be used to find a .lyx file in which an instance of something
3863  happens.
3864  To do this, compile LyX with a local patch that outputs something to the
3865  terminal when an instance is found, and then run the check_load tests to
3866  see if any fail, which would mean that the situation occurs in the LyX
3867  documentation files corresponding to the failed tests.
3868  These tests are expectedly fragile: any LyX diagnostic message, which is
3869  not necessarily an error, would cause the tests to fail.
3870  Similarly, any message output by a library (e.g.
3871  Qt) would also cause failure.
3872  There are some messages that the check_load tests are instructed to ignore,
3873  which are stored in the file
3874 \begin_inset Flex Code
3875 status collapsed
3876
3877 \begin_layout Plain Layout
3878 development/autotests/filterCheckWarnings
3879 \end_layout
3880
3881 \end_inset
3882
3883 .
3884 \end_layout
3885
3886 \begin_layout Standard
3887 Under cmake, the tests are labeled as 'load'.
3888 \end_layout
3889
3890 \begin_layout Subsubsection
3891 Keytests
3892 \end_layout
3893
3894 \begin_layout Standard
3895 Automated tests based on the "MonKey Testing" keytest program.
3896  They are documented in the README document in
3897 \begin_inset Flex Code
3898 status collapsed
3899
3900 \begin_layout Plain Layout
3901 development/autotests
3902 \end_layout
3903
3904 \end_inset
3905
3906  subfolder of the \SpecialChar LyX
3907  source code distribution.
3908  T
3909 \end_layout
3910
3911 \begin_layout Subsubsection
3912 lyx21 tests
3913 \end_layout
3914
3915 \begin_layout Standard
3916 These tests combine lyx2lyx tests with check_load tests.
3917  They fail if either fails.
3918 \end_layout
3919
3920 \begin_layout Subsubsection
3921 URL tests
3922 \end_layout
3923
3924 \begin_layout Standard
3925 The URL tests are enabled with the
3926 \begin_inset Flex Code
3927 status collapsed
3928
3929 \begin_layout Plain Layout
3930 -DLYX_ENABLE_URLTESTS=ON
3931 \end_layout
3932
3933 \end_inset
3934
3935  CMake flag and are useful for finding broken links in our documentation
3936  files.
3937  If a URL test fails, to see which link in particular was reported as broken,
3938  see the output in
3939 \begin_inset Flex Code
3940 status collapsed
3941
3942 \begin_layout Plain Layout
3943 LastTest.log
3944 \end_layout
3945
3946 \end_inset
3947
3948 .
3949  These tests are extremely fragile (e.g.
3950  a test can depend on your Internet connection) and a failed URL test should
3951  not be taken too seriously.
3952  URL tests are labeled as
3953 \family typewriter
3954 'url'.
3955 \end_layout
3956
3957 \begin_layout Paragraph
3958 Running URL tests
3959 \end_layout
3960
3961 \begin_layout Standard
3962 cmake is required to run the \SpecialChar LyX
3963  tests, running them is not implemented for
3964  autotools.
3965 \end_layout
3966
3967 \begin_layout Standard
3968 The appropriate commands are:
3969 \end_layout
3970
3971 \begin_layout Itemize
3972
3973 \family typewriter
3974 ctest -L url
3975 \family default
3976
3977 \begin_inset Newline newline
3978 \end_inset
3979
3980 runs all tests with label
3981 \family typewriter
3982 'url'
3983 \end_layout
3984
3985 \begin_layout Itemize
3986
3987 \family typewriter
3988 ctest -R 'check_.*urls'
3989 \family default
3990
3991 \begin_inset Newline newline
3992 \end_inset
3993
3994 runs the tests 'check_accessible_urls'
3995 \end_layout
3996
3997 \begin_layout Standard
3998 Associated test results can be examined in ctest-log directory in files
3999  of the form 'LastFailed.*URLS.log'
4000 \end_layout
4001
4002 \begin_layout Section
4003 Development policies
4004 \end_layout
4005
4006 \begin_layout Standard
4007 This chapter lists some guidelines that should be followed.
4008  This list is not complete, and many guidelines are in separate chapters,
4009  such as
4010 \begin_inset Quotes eld
4011 \end_inset
4012
4013 When is an update of the .lyx file format number needed?
4014 \begin_inset Quotes erd
4015 \end_inset
4016
4017  in Section
4018 \begin_inset CommandInset ref
4019 LatexCommand ref
4020 reference "sec:When-is-an"
4021
4022 \end_inset
4023
4024 .
4025 \end_layout
4026
4027 \begin_layout Subsection
4028 When to set a fixed milestone?
4029 \end_layout
4030
4031 \begin_layout Standard
4032 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
4033  holds:
4034 \end_layout
4035
4036 \begin_layout Enumerate
4037 Somebody is actively working on a fix.
4038 \end_layout
4039
4040 \begin_layout Enumerate
4041 The bug is so severe that it would block the release if it is not fixed.
4042 \end_layout
4043
4044 \begin_layout Standard
4045 If a bug is important, but nobody is working on it, and it is no showstopper,
4046  use a milestone like 2.1.x or 2.2.x.
4047  For all other bugs, do not set a milestone at all.
4048 \end_layout
4049
4050 \begin_layout Subsection
4051 Can we add rc entries in stable branch?
4052 \end_layout
4053
4054 \begin_layout Standard
4055 No.
4056  We are supposed to increase the prefs2prefs version number with such things.
4057 \end_layout
4058
4059 \begin_layout Section
4060 Documentation policies
4061 \end_layout
4062
4063 \begin_layout Standard
4064 The main documentation consists of these files:
4065 \end_layout
4066
4067 \begin_layout Description
4068 splash.lyx it is the first file you see after an installation.
4069  We assume that a new user sees this.
4070  It is therefore designed to be as simple as possible.
4071  Therefore please don't add any new formatting, only fix typos etc.
4072  Splash.lyx is up to date for \SpecialChar LyX
4073  2.1.x, currently maintained by Uwe Stöhr.
4074 \end_layout
4075
4076 \begin_layout Description
4077 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
4078 .
4079  It therefore uses a limited set of formatting.
4080  For example a standard document class.
4081  Since new users will first learn about the formatting possibilities of
4082  \SpecialChar LyX
4083  please keep this file that simple.
4084  Intro.lyx is up to date for \SpecialChar LyX
4085  2.1.x, currently maintained by Uwe Stöhr.
4086 \end_layout
4087
4088 \begin_layout Description
4089 Tutorial.lyx our tutorial.
4090  It must be always up to date.
4091  Normally there is nothing to add since we don't want to overwhelm new users
4092  with too much details.
4093  The will learn these details while using \SpecialChar LyX
4094  and we have special manuals.
4095  Tutorial.lyx is up to date for \SpecialChar LyX
4096  2.1.x, currently maintained by Uwe Stöhr.
4097 \end_layout
4098
4099 \begin_layout Description
4100 UserGuide.lyx our main user guide.
4101  It covers a mixture of basic and detailed information.
4102  Some information is also in the Math and EmbeddedObjects manual so that
4103  the UserGuide refers to these files.
4104  UserGuide.lyx is up to date for \SpecialChar LyX
4105  2.1.x, currently maintained by Uwe Stöhr.
4106 \end_layout
4107
4108 \begin_layout Description
4109 EmbeddedObjects.lyx a special manual to explain things like tables floats
4110  boxes etc.
4111  in all detail.
4112  EmbeddedObjects.lyx is up to date for \SpecialChar LyX
4113  2.1.x, currently maintained by Uwe
4114  Stöhr.
4115 \end_layout
4116
4117 \begin_layout Description
4118 Math.lyx a special manual to explain everything regarding math in all detail.
4119  Math.lyx is up to date for \SpecialChar LyX
4120  2.1.x, currently maintained by Uwe Stöhr.
4121 \end_layout
4122
4123 \begin_layout Description
4124 Additional.lyx this manual covers information that would be too much detail
4125  for the UserGuide or would make the UserGuide uncompilable or only compilable
4126  when installing a lot of special \SpecialChar LaTeX
4127 -packages.
4128  What should be in the UserGuide or better in Additional is a matter of
4129  taste.
4130  it is up to you to decide that.
4131  Additional.lyx is not completely up to date for \SpecialChar LyX
4132  2.1.x.
4133  Only chapter
4134 \begin_inset space ~
4135 \end_inset
4136
4137 8 is up to date and currently maintained by Uwe Stöhr.
4138  It certainly needs a rewrite and update.
4139  For example many info in chapter
4140 \begin_inset space ~
4141 \end_inset
4142
4143 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
4144  manual.
4145 \end_layout
4146
4147 \begin_layout Description
4148 Customization.lyx this manual covers information how to customize \SpecialChar LyX
4149  for certain
4150  output formats, operating systems, languages etc.
4151  It is currently completely out of date and needs a major rewrite and update.
4152  If you do this please assure that your information are given for all OSes
4153  and \SpecialChar LaTeX
4154  distributions (meaning be as objective as possible).
4155 \end_layout
4156
4157 \begin_layout Standard
4158 There are only 4
4159 \begin_inset space ~
4160 \end_inset
4161
4162 rules in editing the docs:
4163 \end_layout
4164
4165 \begin_layout Enumerate
4166 If you are not the maintainer of a doc file or a chapter/section, you MUST
4167  use change tracking so that the maintainer could review your changes
4168 \end_layout
4169
4170 \begin_layout Enumerate
4171 Respect the formatting of the document.
4172  The different files use different formatting styles.
4173  That is OK and has historic reasons nobody fully know ;-).
4174  But it is important to be consistent within one file.
4175 \end_layout
4176
4177 \begin_layout Enumerate
4178 All changes you make to a file in one language MUST also go the file in
4179  the other actively maintained languages.
4180  Normally the maintainer does this for you, if you are the maintainer, you
4181  must do this by copying or changing the changed or added text to the other
4182  files so that the translators sees the blue underlined text and know what
4183  they have to translate and what was changed.
4184 \end_layout
4185
4186 \begin_layout Enumerate
4187 You MUST assure that the document is compilable as
4188 \begin_inset Quotes eld
4189 \end_inset
4190
4191 PDF (pdflatex)
4192 \begin_inset Quotes erd
4193 \end_inset
4194
4195  after your changes.
4196 \end_layout
4197
4198 \end_body
4199 \end_document