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 \end_layout
2066
2067 \begin_layout Standard
2068 For example, to run 8 jobs at a time:
2069 \end_layout
2070
2071 \begin_layout Standard
2072 \begin_inset Flex Code
2073 status collapsed
2074
2075 \begin_layout Plain Layout
2076 ctest -j8
2077 \end_layout
2078
2079 \end_inset
2080
2081
2082 \end_layout
2083
2084 \begin_layout Standard
2085 \begin_inset Flex Code
2086 status collapsed
2087
2088 \begin_layout Plain Layout
2089 ctest \SpecialChar nobreakdash
2090 \SpecialChar nobreakdash
2091 rerun-failed
2092 \end_layout
2093
2094 \end_inset
2095
2096
2097 \end_layout
2098
2099 \begin_layout Standard
2100 When specifying a subset of the tests (e.g.
2101  using
2102 \begin_inset Flex Code
2103 status collapsed
2104
2105 \begin_layout Plain Layout
2106 \SpecialChar nobreakdash
2107 R <pattern>
2108 \end_layout
2109
2110 \end_inset
2111
2112 ), the same subset must be specified when using the
2113 \begin_inset Flex Code
2114 status collapsed
2115
2116 \begin_layout Plain Layout
2117 \SpecialChar nobreakdash
2118 \SpecialChar nobreakdash
2119 rerun-failed
2120 \end_layout
2121
2122 \end_inset
2123
2124  option because it is the test numbers that are used to index which tests
2125  failed on the previous run.
2126 \end_layout
2127
2128 \begin_layout Standard
2129 \noindent
2130 Note that some tests cannot be run in parallel.
2131  These tests are marked in the code with the
2132 \begin_inset Flex Code
2133 status collapsed
2134
2135 \begin_layout Plain Layout
2136 \noindent
2137 RUN_SERIAL ON
2138 \end_layout
2139
2140 \end_inset
2141
2142  CMake property.
2143 \end_layout
2144
2145 \end_deeper
2146 \begin_layout Labeling
2147 \labelwidthstring -R
2148 \begin_inset Flex Code
2149 status collapsed
2150
2151 \begin_layout Plain Layout
2152 \SpecialChar nobreakdash
2153 \SpecialChar nobreakdash
2154 timeout <seconds>
2155 \end_layout
2156
2157 \end_inset
2158
2159  Set a global timeout on all tests that do not already have a timeout set
2160  on them.
2161 \end_layout
2162
2163 \begin_deeper
2164 \begin_layout Standard
2165 There have been bugs in LyX and in \SpecialChar LaTeX
2166  which cause compilation to hang, and
2167  without a timeout a test might never stop (in one case there was even a
2168  memory leak).
2169  If a test times out, the
2170 \begin_inset Flex Code
2171 status collapsed
2172
2173 \begin_layout Plain Layout
2174 ctest
2175 \end_layout
2176
2177 \end_inset
2178
2179  command exits with error, but you can distinguish between a timed out test
2180  and a failed test in the output reported at the end of the
2181 \begin_inset Flex Code
2182 status collapsed
2183
2184 \begin_layout Plain Layout
2185 ctest
2186 \end_layout
2187
2188 \end_inset
2189
2190  command.
2191 \end_layout
2192
2193 \end_deeper
2194 \begin_layout Standard
2195 See the manual (
2196 \begin_inset Flex Code
2197 status collapsed
2198
2199 \begin_layout Plain Layout
2200 man ctest
2201 \end_layout
2202
2203 \end_inset
2204
2205 ) the full list of command line options.
2206 \end_layout
2207
2208 \begin_layout Paragraph
2209 Examples
2210 \end_layout
2211
2212 \begin_layout Itemize
2213 run only the export tests:
2214 \begin_inset Flex Code
2215 status collapsed
2216
2217 \begin_layout Plain Layout
2218 ctest -L export
2219 \end_layout
2220
2221 \end_inset
2222
2223
2224 \end_layout
2225
2226 \begin_layout Itemize
2227 run inverted tests:
2228 \begin_inset Flex Code
2229 status collapsed
2230
2231 \begin_layout Plain Layout
2232 ctest -L "inverted|suspended"
2233 \end_layout
2234
2235 \end_inset
2236
2237
2238 \end_layout
2239
2240 \begin_layout Itemize
2241 list all export tests which match any of the labelling patterns:
2242 \begin_inset Flex Code
2243 status collapsed
2244
2245 \begin_layout Plain Layout
2246 ctest -N -R "
2247 \backslash
2248 ..*_export/"
2249 \end_layout
2250
2251 \end_inset
2252
2253
2254 \end_layout
2255
2256 \begin_layout Itemize
2257 exclude rarely used output formats and post-processing tests
2258 \begin_inset Flex Code
2259 status collapsed
2260
2261 \begin_layout Plain Layout
2262 ctest -L export -E "_(texF|dvi3|pdf3?)"
2263 \end_layout
2264
2265 \end_inset
2266
2267
2268 \end_layout
2269
2270 \begin_layout Paragraph
2271 \begin_inset CommandInset label
2272 LatexCommand label
2273 name "subsec:Interpreting-export-tests"
2274
2275 \end_inset
2276
2277 Interpreting the export test results
2278 \end_layout
2279
2280 \begin_layout Standard
2281 A test can fail for several reasons, not all of them bad.
2282 \end_layout
2283
2284 \begin_layout Enumerate
2285 A new or edited sample document may be incompatible with some output formats.
2286 \end_layout
2287
2288 \begin_layout Enumerate
2289 A dependency is not met (e.g.
2290  the \SpecialChar LaTeX
2291  class file).
2292  One hint that this is the case is that the corresponding
2293 \begin_inset Flex Code
2294 status collapsed
2295
2296 \begin_layout Plain Layout
2297 check_load
2298 \end_layout
2299
2300 \end_inset
2301
2302  test will likely also fail.
2303 \end_layout
2304
2305 \begin_layout Enumerate
2306 An inverted test fails to fail (i.e.
2307  export that previously failed now works).
2308 \end_layout
2309
2310 \begin_layout Enumerate
2311 An external dependency was updated (e.g.
2312  \SpecialChar TeX
2313  Live).
2314 \end_layout
2315
2316 \begin_layout Enumerate
2317 A recent code change introduced a bug.
2318 \end_layout
2319
2320 \begin_layout Enumerate
2321 \begin_inset CommandInset label
2322 LatexCommand label
2323 name "enu:exposed"
2324
2325 \end_inset
2326
2327 A change in a document exposed a previously unknown bug or an incompatibility
2328  with an export format (e.g.
2329  Lua\SpecialChar LaTeX
2330 ).
2331 \end_layout
2332
2333 \begin_layout Standard
2334 Because the .lyx files are exported in several formats, it is not surprising
2335  that many of the exports fail.
2336  This expectation of failure is addressed by
2337 \begin_inset Quotes eld
2338 \end_inset
2339
2340 inverting
2341 \begin_inset Quotes erd
2342 \end_inset
2343
2344  the tests, that is, by marking the test as
2345 \begin_inset Quotes eld
2346 \end_inset
2347
2348 passing
2349 \begin_inset Quotes erd
2350 \end_inset
2351
2352  if the export exits with error and as
2353 \begin_inset Quotes eld
2354 \end_inset
2355
2356 failing
2357 \begin_inset Quotes erd
2358 \end_inset
2359
2360  if the export succeeds
2361 \emph on
2362 .
2363
2364 \emph default
2365  It follows that these expected failures will not show up as failed tests
2366  in the test results and thus will not pollute the
2367 \begin_inset Quotes eld
2368 \end_inset
2369
2370 good
2371 \begin_inset Quotes erd
2372 \end_inset
2373
2374  tests.
2375  If the export actually succeeds, then the test will fail.
2376  The purpose of this failure is to get your attention—something has changed,
2377  possibly for the better.
2378 \end_layout
2379
2380 \begin_layout Standard
2381 We try to document why a test is inverted or ignored.
2382  See the comment (prefixed with
2383 \begin_inset Flex Code
2384 status collapsed
2385
2386 \begin_layout Plain Layout
2387 #
2388 \end_layout
2389
2390 \end_inset
2391
2392 ) above the block in which the test is listed as inverted or ignored in
2393  the files
2394 \begin_inset Flex Code
2395 status collapsed
2396
2397 \begin_layout Plain Layout
2398 development/autotests/suspiciousTests
2399 \end_layout
2400
2401 \end_inset
2402
2403 ,
2404 \begin_inset Flex Code
2405 status collapsed
2406
2407 \begin_layout Plain Layout
2408 development/autotests/unreliableTests
2409 \end_layout
2410
2411 \end_inset
2412
2413  and
2414 \begin_inset Flex Code
2415 status collapsed
2416
2417 \begin_layout Plain Layout
2418 development/autotests/ignoredTests
2419 \end_layout
2420
2421 \end_inset
2422
2423 .
2424
2425 \end_layout
2426
2427 \begin_layout Standard
2428 A good question is why do we enable the tests for non-default formats? The
2429  answer is that if a non-default route is broken it is often because a bug
2430  was introduced in LyX and not because a document-specific change was made
2431  that is not supported by the route.
2432  In other words, there is a high signal/noise ratio in the export tests
2433  for some non-default formats.
2434
2435 \end_layout
2436
2437 \begin_layout Standard
2438 When a test or several tests fail, consider checking the files in the
2439 \begin_inset Flex Code
2440 status collapsed
2441
2442 \begin_layout Plain Layout
2443 Testing/Temporary/
2444 \end_layout
2445
2446 \end_inset
2447
2448  subdirectory of your build directory.
2449  In this subdirectory are three files: the file
2450 \begin_inset Flex Code
2451 status collapsed
2452
2453 \begin_layout Plain Layout
2454 LastTestsFailed.log
2455 \end_layout
2456
2457 \end_inset
2458
2459  simply lists the tests that failed on your last
2460 \begin_inset Flex Code
2461 status collapsed
2462
2463 \begin_layout Plain Layout
2464 ctest
2465 \end_layout
2466
2467 \end_inset
2468
2469  command; the
2470 \begin_inset Flex Code
2471 status collapsed
2472
2473 \begin_layout Plain Layout
2474 LastTest.log
2475 \end_layout
2476
2477 \end_inset
2478
2479  file contains the output from the tests (and often has details explaining
2480  why a test failed); and the
2481 \begin_inset Flex Code
2482 status collapsed
2483
2484 \begin_layout Plain Layout
2485 CTestCostData.txt
2486 \end_layout
2487
2488 \end_inset
2489
2490  file lists the times that it took to run the tests.
2491 \end_layout
2492
2493 \begin_layout Paragraph
2494 What action should you take if a test fails?
2495 \end_layout
2496
2497 \begin_layout Standard
2498 \paragraph_spacing single
2499 It is always good to check manually why something fails and if it passes
2500  if the PDF output is good.
2501 \end_layout
2502
2503 \begin_layout Itemize
2504 Generally, if a change breaks compilation for the target format (for the
2505  manuals pdf2) without solving some important other issue,
2506 \emph on
2507 fix or revert the commit
2508 \emph default
2509  that led to failure.
2510 \end_layout
2511
2512 \begin_layout Itemize
2513 If it is not possible to (immediately) fix the failure but there are reasons
2514  not to revert the commit (e.g.
2515  it fixes another more important issue),
2516 \emph on
2517 invert
2518 \emph default
2519  the failing test case (see
2520 \begin_inset CommandInset ref
2521 LatexCommand ref
2522 reference "par:Inverted-tests"
2523
2524 \end_inset
2525
2526 ).
2527 \end_layout
2528
2529 \begin_layout Itemize
2530 If an
2531 \emph on
2532 inverted
2533 \emph default
2534  test case fails because the export now works,
2535 \emph on
2536 uninvert
2537 \emph default
2538  the test by removing the labeling pattern from
2539 \begin_inset Quotes eld
2540 \end_inset
2541
2542 suspiciousTests
2543 \begin_inset Quotes erd
2544 \end_inset
2545
2546 ) (see
2547 \begin_inset CommandInset ref
2548 LatexCommand ref
2549 reference "par:Inverted-tests"
2550
2551 \end_inset
2552
2553 ).
2554 \end_layout
2555
2556 \begin_layout Itemize
2557 If the export did not fail previously but led to wrong output (PDF, say),
2558  it is in fact an improvement when the test now fails, label it as
2559 \begin_inset Quotes eld
2560 \end_inset
2561
2562 unreliable:wrong:output
2563 \begin_inset Quotes erd
2564 \end_inset
2565
2566  (
2567 \begin_inset CommandInset ref
2568 LatexCommand ref
2569 reference "par:Unreliable-tests"
2570
2571 \end_inset
2572
2573 ).
2574 \end_layout
2575
2576 \begin_layout Paragraph
2577 \begin_inset CommandInset label
2578 LatexCommand label
2579 name "par:Inverted-tests"
2580
2581 \end_inset
2582
2583 Inverted tests
2584 \end_layout
2585
2586 \begin_layout Standard
2587 Test cases whose name matches a pattern in the file
2588 \begin_inset Flex Code
2589 status collapsed
2590
2591 \begin_layout Plain Layout
2592 development/autotests/suspiciousTests
2593 \end_layout
2594
2595 \end_inset
2596
2597  get the label
2598 \emph on
2599 inverted
2600 \emph default
2601 .
2602  They get also the test property
2603 \begin_inset Flex Code
2604 status collapsed
2605
2606 \begin_layout Plain Layout
2607 WILL_FAIL
2608 \end_layout
2609
2610 \end_inset
2611
2612 , i.e.
2613  they are reported as failing if the export works without error
2614 \begin_inset Flex URL
2615 status collapsed
2616
2617 \begin_layout Plain Layout
2618
2619 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
2620 \end_layout
2621
2622 \end_inset
2623
2624 .
2625 \end_layout
2626
2627 \begin_layout Standard
2628 Add failing cases to this file, if they cannot be solved
2629 \begin_inset Quotes eld
2630 \end_inset
2631
2632 immediately
2633 \begin_inset Quotes erd
2634 \end_inset
2635
2636  but it is expected that the export will work in a foreseeable future, e.g.
2637  low priority issues like failures to export to a non-target format (for
2638  the manuals everything except pdf2).
2639 \end_layout
2640
2641 \begin_layout Standard
2642 The following sublabels are currently present in
2643 \begin_inset Flex Code
2644 status collapsed
2645
2646 \begin_layout Plain Layout
2647 suspiciousTests
2648 \end_layout
2649
2650 \end_inset
2651
2652 :
2653 \end_layout
2654
2655 \begin_layout Description
2656 todo test failures that require attention:
2657 \end_layout
2658
2659 \begin_deeper
2660 \begin_layout Itemize
2661 minor issues to explore and properly sort later,
2662 \end_layout
2663
2664 \begin_layout Itemize
2665 easyfix issues,
2666 \end_layout
2667
2668 \begin_layout Itemize
2669 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
2670 \end_layout
2671
2672 \end_deeper
2673 \begin_layout Description
2674 lyxbugs LyX bugs with a Trac number.
2675 \end_layout
2676
2677 \begin_layout Description
2678 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
2679 \end_layout
2680
2681 \begin_deeper
2682 \begin_layout Standard
2683 "Wontfix" if demonstrating correct use and OK in the default output format.
2684 \end_layout
2685
2686 \end_deeper
2687 \begin_layout Description
2688 texissues Export fails due to LaTeX limitations like non-ASCII characters
2689  in verbatim or listings, incompatible packages, ...
2690 \end_layout
2691
2692 \begin_deeper
2693 \begin_layout Standard
2694 "Wontfix" if documents demonstrate correct use in the default output format:
2695 \end_layout
2696
2697 \begin_layout Itemize
2698 If the source can be made more robust without becoming "hackish", fix the
2699  source,
2700 \end_layout
2701
2702 \begin_layout Itemize
2703 if LyX could be enhanced to care for a permanent TeX limitation, file a
2704  ticket at trac and add a pattern under lyxbugs,
2705 \end_layout
2706
2707 \begin_layout Itemize
2708 otherwise, add a pattern here.
2709 \end_layout
2710
2711 \end_deeper
2712 \begin_layout Description
2713 attic Documents in the attic.
2714  (Kept for reference and format conversion test.)
2715 \end_layout
2716
2717 \begin_layout Subparagraph
2718 suspended
2719 \end_layout
2720
2721 \begin_layout Standard
2722 Test cases whose name additionally matches a pattern in the file
2723 \begin_inset Flex Code
2724 status collapsed
2725
2726 \begin_layout Plain Layout
2727 development/autotests/suspendedTests
2728 \end_layout
2729
2730 \end_inset
2731
2732  get the label
2733 \emph on
2734 suspended
2735 \emph default
2736 (instead of
2737 \emph on
2738 export
2739 \emph default
2740 and
2741 \emph on
2742  inverted
2743 \emph default
2744 ).
2745  This means they are not executed using
2746 \begin_inset Flex Code
2747 status collapsed
2748
2749 \begin_layout Plain Layout
2750 ctest -L export
2751 \end_layout
2752
2753 \end_inset
2754
2755  or
2756 \begin_inset Flex Code
2757 status collapsed
2758
2759 \begin_layout Plain Layout
2760 ctest -L inverted
2761 \end_layout
2762
2763 \end_inset
2764
2765 .
2766  However, they also get the test property
2767 \begin_inset Flex Code
2768 status collapsed
2769
2770 \begin_layout Plain Layout
2771 WILL_FAIL
2772 \end_layout
2773
2774 \end_inset
2775
2776 , i.e.
2777  they are reported as failing if the export works without error.
2778  From time to time they still have to be checked using
2779 \begin_inset Flex Code
2780 status collapsed
2781
2782 \begin_layout Plain Layout
2783 ctest -L suspended
2784 \end_layout
2785
2786 \end_inset
2787
2788 .
2789 \end_layout
2790
2791 \begin_layout Standard
2792 These tests are suspended, because the export fails for known reasons which
2793  cannot ATM be resolved.
2794  But it is expected the reason might disappear in the future.
2795  Be it new TL or better handling in \SpecialChar LyX
2796 .
2797 \end_layout
2798
2799 \begin_layout Standard
2800 For ctest commands without the
2801 \begin_inset Flex Code
2802 status collapsed
2803
2804 \begin_layout Plain Layout
2805 -L
2806 \end_layout
2807
2808 \end_inset
2809
2810  parameter nothing changes.
2811  Suspended or not, tests will be executed depending only on the selecting
2812  regular expression given to the ctest command (see
2813 \begin_inset CommandInset ref
2814 LatexCommand ref
2815 reference "par:ctest-options"
2816
2817 \end_inset
2818
2819 ).
2820 \end_layout
2821
2822 \begin_layout Paragraph
2823 \begin_inset CommandInset label
2824 LatexCommand label
2825 name "par:Unreliable-tests"
2826
2827 \end_inset
2828
2829 Unreliable tests
2830 \end_layout
2831
2832 \begin_layout Standard
2833 Test cases whose name matches a pattern in the file
2834 \begin_inset Flex Code
2835 status collapsed
2836
2837 \begin_layout Plain Layout
2838 development/autotests/unreliableTests
2839 \end_layout
2840
2841 \end_inset
2842
2843  get the label
2844 \emph on
2845 unreliable
2846 \emph default
2847 .
2848 \end_layout
2849
2850 \begin_layout Standard
2851 These tests are not executed using
2852 \begin_inset Flex Code
2853 status collapsed
2854
2855 \begin_layout Plain Layout
2856 ctest -L export
2857 \end_layout
2858
2859 \end_inset
2860
2861  or
2862 \begin_inset Flex Code
2863 status collapsed
2864
2865 \begin_layout Plain Layout
2866 ctest -L inverted
2867 \end_layout
2868
2869 \end_inset
2870
2871 .
2872
2873 \end_layout
2874
2875 \begin_layout Standard
2876 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
2877  or pass but should rather fail (wrong output).
2878
2879 \begin_inset Note Note
2880 status collapsed
2881
2882 \begin_layout Plain Layout
2883 *invalid* tests (wrong output) are not *unreliable*.
2884  # Use "unfit" or "unapplicable" as better label and name of pattern file?
2885
2886 \end_layout
2887
2888 \end_inset
2889
2890
2891 \end_layout
2892
2893 \begin_layout Description
2894 nonstandard Documents with additional requirements, e.g.
2895  a class or package file not in TeXLive.
2896
2897 \begin_inset Note Note
2898 status open
2899
2900 \begin_layout Plain Layout
2901 TODO: rename to "extra"?
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 'nonstandard'.
2914 \end_layout
2915
2916 \end_deeper
2917 \begin_layout Description
2918 erratic Tests depending on local configuration, OS, TeX distribution, package
2919  versions, or the phase of the moon.
2920
2921 \begin_inset Note Note
2922 status open
2923
2924 \begin_layout Plain Layout
2925 TODO: use
2926 \emph on
2927 erratic
2928 \emph default
2929  only for the phase-of-moon dependency?
2930 \end_layout
2931
2932 \end_inset
2933
2934
2935 \end_layout
2936
2937 \begin_deeper
2938 \begin_layout Standard
2939 These tests are labeled as
2940 \family typewriter
2941 'erratic'.
2942 \end_layout
2943
2944 \end_deeper
2945 \begin_layout Description
2946 wrong
2947 \begin_inset space ~
2948 \end_inset
2949
2950 output Export does not fail but the resulting document has errors.
2951 \end_layout
2952
2953 \begin_deeper
2954 \begin_layout Standard
2955 \paragraph_spacing single
2956 \begin_inset Note Note
2957 status open
2958
2959 \begin_layout Plain Layout
2960 \paragraph_spacing single
2961 These tests are actually not
2962 \emph on
2963 unreliable
2964 \emph default
2965  but
2966 \emph on
2967 invalid
2968 \emph default
2969  (not measuring what they should measure).
2970 \end_layout
2971
2972 \end_inset
2973
2974
2975 \end_layout
2976
2977 \end_deeper
2978 \begin_layout Paragraph
2979 \begin_inset CommandInset label
2980 LatexCommand label
2981 name "par:Export-test-filtering"
2982
2983 \end_inset
2984
2985 Export test filtering
2986 \end_layout
2987
2988 \begin_layout Standard
2989 The assignment of a label to a test is controlled by a set of files with
2990  regular expressions that are matched against the test names.
2991 \end_layout
2992
2993 \begin_layout Description
2994 ignoredTests (small file)
2995 \begin_inset Newline newline
2996 \end_inset
2997
2998 Tests selected here are withdrawn in the configuration step (cf.
2999
3000 \begin_inset CommandInset ref
3001 LatexCommand ref
3002 reference "par:Configuring-ctests"
3003
3004 \end_inset
3005
3006 ).
3007 \end_layout
3008
3009 \begin_deeper
3010 \begin_layout Labeling
3011 \labelwidthstring 00.00.0000
3012 Input Test of any export combination
3013 \end_layout
3014
3015 \begin_layout Labeling
3016 \labelwidthstring 00.00.0000
3017 Output Stop if tests not selected here
3018 \end_layout
3019
3020 \end_deeper
3021 \begin_layout Description
3022 unreliableTests: Tests selected either pass or fail, but that is dependent
3023  on the system where the test is run.
3024  Selected tests gain the label 'unreliable'.
3025 \end_layout
3026
3027 \begin_deeper
3028 \begin_layout Labeling
3029 \labelwidthstring 00.00.0000
3030 Input Each test which passed 'ignoredTests'
3031 \end_layout
3032
3033 \begin_layout Labeling
3034 \labelwidthstring 00.00.0000
3035 Output Stop if test selected, gain label 'unreliable'.
3036 \end_layout
3037
3038 \end_deeper
3039 \begin_layout Description
3040 suspiciousTests
3041 \begin_inset space \space{}
3042 \end_inset
3043
3044
3045 \end_layout
3046
3047 \begin_deeper
3048 \begin_layout Labeling
3049 \labelwidthstring 00.00.0000
3050 Input Each test which passed 'unreliableTests'
3051 \end_layout
3052
3053 \begin_layout Labeling
3054 \labelwidthstring 00.00.0000
3055 Output Stop if not selected.
3056 \end_layout
3057
3058 \begin_layout Standard
3059 The following file is meant as subselections of 'suspiciousTests'.
3060  If neither subselection applies, test gains labels 'export' and 'inverted'
3061 \end_layout
3062
3063 \begin_layout Description
3064 suspendedTests Tests selected here gain the label 'suspended' but _not_
3065  'export' or 'inverted', although in ctest they remain inverted.
3066  ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3067 \end_layout
3068
3069 \begin_deeper
3070 \begin_layout Labeling
3071 \labelwidthstring 00.00.0000
3072 Input Each test selected by 'suspiciousTests'
3073 \end_layout
3074
3075 \begin_layout Labeling
3076 \labelwidthstring 00.00.0000
3077 Output Selected test gains label 'suspended'.
3078
3079 \end_layout
3080
3081 \end_deeper
3082 \end_deeper
3083 \begin_layout Standard
3084 The following table may clarify label assignement
3085 \end_layout
3086
3087 \begin_layout Standard
3088 \begin_inset Tabular
3089 <lyxtabular version="3" rows="7" columns="12">
3090 <features tabularvalignment="middle">
3091 <column alignment="left" valignment="top" width="0pt">
3092 <column alignment="left" valignment="top" width="0pt">
3093 <column alignment="left" valignment="top" width="0pt">
3094 <column alignment="left" valignment="top" width="0pt">
3095 <column alignment="center" valignment="top">
3096 <column alignment="center" valignment="top">
3097 <column alignment="center" valignment="top">
3098 <column alignment="center" valignment="top">
3099 <column alignment="center" valignment="top">
3100 <column alignment="center" valignment="top">
3101 <column alignment="center" valignment="top">
3102 <column alignment="center" valignment="top">
3103 <row>
3104 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3105 \begin_inset Text
3106
3107 \begin_layout Plain Layout
3108 Test found in file:
3109 \end_layout
3110
3111 \end_inset
3112 </cell>
3113 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3114 \begin_inset Text
3115
3116 \begin_layout Plain Layout
3117
3118 \end_layout
3119
3120 \end_inset
3121 </cell>
3122 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3123 \begin_inset Text
3124
3125 \begin_layout Plain Layout
3126
3127 \end_layout
3128
3129 \end_inset
3130 </cell>
3131 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3132 \begin_inset Text
3133
3134 \begin_layout Plain Layout
3135
3136 \end_layout
3137
3138 \end_inset
3139 </cell>
3140 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3141 \begin_inset Text
3142
3143 \begin_layout Plain Layout
3144 Marked in ctest, Assigned label
3145 \end_layout
3146
3147 \end_inset
3148 </cell>
3149 <cell multicolumn="2" alignment="center" valignment="top" usebox="none">
3150 \begin_inset Text
3151
3152 \begin_layout Plain Layout
3153
3154 \end_layout
3155
3156 \end_inset
3157 </cell>
3158 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3159 \begin_inset Text
3160
3161 \begin_layout Plain Layout
3162
3163 \end_layout
3164
3165 \end_inset
3166 </cell>
3167 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3168 \begin_inset Text
3169
3170 \begin_layout Plain Layout
3171
3172 \end_layout
3173
3174 \end_inset
3175 </cell>
3176 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3177 \begin_inset Text
3178
3179 \begin_layout Plain Layout
3180
3181 \end_layout
3182
3183 \end_inset
3184 </cell>
3185 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3186 \begin_inset Text
3187
3188 \begin_layout Plain Layout
3189
3190 \end_layout
3191
3192 \end_inset
3193 </cell>
3194 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3195 \begin_inset Text
3196
3197 \begin_layout Plain Layout
3198
3199 \end_layout
3200
3201 \end_inset
3202 </cell>
3203 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3204 \begin_inset Text
3205
3206 \begin_layout Plain Layout
3207
3208 \end_layout
3209
3210 \end_inset
3211 </cell>
3212 </row>
3213 <row>
3214 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3215 \begin_inset Text
3216
3217 \begin_layout Plain Layout
3218 Ignored
3219 \end_layout
3220
3221 \end_inset
3222 </cell>
3223 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3224 \begin_inset Text
3225
3226 \begin_layout Plain Layout
3227 Unreliable
3228 \end_layout
3229
3230 \end_inset
3231 </cell>
3232 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3233 \begin_inset Text
3234
3235 \begin_layout Plain Layout
3236 Suspicious
3237 \end_layout
3238
3239 \end_inset
3240 </cell>
3241 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3242 \begin_inset Text
3243
3244 \begin_layout Plain Layout
3245 Suspended
3246 \end_layout
3247
3248 \end_inset
3249 </cell>
3250 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3251 \begin_inset Text
3252
3253 \begin_layout Plain Layout
3254 export
3255 \end_layout
3256
3257 \end_inset
3258 </cell>
3259 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
3260 \begin_inset Text
3261
3262 \begin_layout Plain Layout
3263
3264 \end_layout
3265
3266 \end_inset
3267 </cell>
3268 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3269 \begin_inset Text
3270
3271 \begin_layout Plain Layout
3272 unreliable
3273 \end_layout
3274
3275 \end_inset
3276 </cell>
3277 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
3278 \begin_inset Text
3279
3280 \begin_layout Plain Layout
3281
3282 \end_layout
3283
3284 \end_inset
3285 </cell>
3286 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3287 \begin_inset Text
3288
3289 \begin_layout Plain Layout
3290 inverted
3291 \end_layout
3292
3293 \end_inset
3294 </cell>
3295 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
3296 \begin_inset Text
3297
3298 \begin_layout Plain Layout
3299
3300 \end_layout
3301
3302 \end_inset
3303 </cell>
3304 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3305 \begin_inset Text
3306
3307 \begin_layout Plain Layout
3308 suspended
3309 \end_layout
3310
3311 \end_inset
3312 </cell>
3313 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3314 \begin_inset Text
3315
3316 \begin_layout Plain Layout
3317
3318 \end_layout
3319
3320 \end_inset
3321 </cell>
3322 </row>
3323 <row>
3324 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3325 \begin_inset Text
3326
3327 \begin_layout Plain Layout
3328 Yes
3329 \end_layout
3330
3331 \end_inset
3332 </cell>
3333 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3334 \begin_inset Text
3335
3336 \begin_layout Plain Layout
3337 -
3338 \end_layout
3339
3340 \end_inset
3341 </cell>
3342 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3343 \begin_inset Text
3344
3345 \begin_layout Plain Layout
3346 -
3347 \end_layout
3348
3349 \end_inset
3350 </cell>
3351 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3352 \begin_inset Text
3353
3354 \begin_layout Plain Layout
3355 -
3356 \end_layout
3357
3358 \end_inset
3359 </cell>
3360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3361 \begin_inset Text
3362
3363 \begin_layout Plain Layout
3364 -
3365 \end_layout
3366
3367 \end_inset
3368 </cell>
3369 <cell alignment="center" valignment="top" topline="true" usebox="none">
3370 \begin_inset Text
3371
3372 \begin_layout Plain Layout
3373 -
3374 \end_layout
3375
3376 \end_inset
3377 </cell>
3378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3379 \begin_inset Text
3380
3381 \begin_layout Plain Layout
3382 -
3383 \end_layout
3384
3385 \end_inset
3386 </cell>
3387 <cell alignment="center" valignment="top" topline="true" usebox="none">
3388 \begin_inset Text
3389
3390 \begin_layout Plain Layout
3391
3392 \end_layout
3393
3394 \end_inset
3395 </cell>
3396 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3397 \begin_inset Text
3398
3399 \begin_layout Plain Layout
3400 -
3401 \end_layout
3402
3403 \end_inset
3404 </cell>
3405 <cell alignment="center" valignment="top" topline="true" usebox="none">
3406 \begin_inset Text
3407
3408 \begin_layout Plain Layout
3409 -
3410 \end_layout
3411
3412 \end_inset
3413 </cell>
3414 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3415 \begin_inset Text
3416
3417 \begin_layout Plain Layout
3418 -
3419 \end_layout
3420
3421 \end_inset
3422 </cell>
3423 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3424 \begin_inset Text
3425
3426 \begin_layout Plain Layout
3427 -
3428 \end_layout
3429
3430 \end_inset
3431 </cell>
3432 </row>
3433 <row>
3434 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3435 \begin_inset Text
3436
3437 \begin_layout Plain Layout
3438 No
3439 \end_layout
3440
3441 \end_inset
3442 </cell>
3443 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3444 \begin_inset Text
3445
3446 \begin_layout Plain Layout
3447 Yes
3448 \end_layout
3449
3450 \end_inset
3451 </cell>
3452 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3453 \begin_inset Text
3454
3455 \begin_layout Plain Layout
3456 -
3457 \end_layout
3458
3459 \end_inset
3460 </cell>
3461 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3462 \begin_inset Text
3463
3464 \begin_layout Plain Layout
3465 -
3466 \end_layout
3467
3468 \end_inset
3469 </cell>
3470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3471 \begin_inset Text
3472
3473 \begin_layout Plain Layout
3474 -
3475 \end_layout
3476
3477 \end_inset
3478 </cell>
3479 <cell alignment="center" valignment="top" topline="true" usebox="none">
3480 \begin_inset Text
3481
3482 \begin_layout Plain Layout
3483 -
3484 \end_layout
3485
3486 \end_inset
3487 </cell>
3488 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3489 \begin_inset Text
3490
3491 \begin_layout Plain Layout
3492 -
3493 \end_layout
3494
3495 \end_inset
3496 </cell>
3497 <cell alignment="center" valignment="top" topline="true" usebox="none">
3498 \begin_inset Text
3499
3500 \begin_layout Plain Layout
3501 +
3502 \end_layout
3503
3504 \end_inset
3505 </cell>
3506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3507 \begin_inset Text
3508
3509 \begin_layout Plain Layout
3510 -
3511 \end_layout
3512
3513 \end_inset
3514 </cell>
3515 <cell alignment="center" valignment="top" topline="true" usebox="none">
3516 \begin_inset Text
3517
3518 \begin_layout Plain Layout
3519 -
3520 \end_layout
3521
3522 \end_inset
3523 </cell>
3524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3525 \begin_inset Text
3526
3527 \begin_layout Plain Layout
3528 -
3529 \end_layout
3530
3531 \end_inset
3532 </cell>
3533 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3534 \begin_inset Text
3535
3536 \begin_layout Plain Layout
3537 -
3538 \end_layout
3539
3540 \end_inset
3541 </cell>
3542 </row>
3543 <row>
3544 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
3545 \begin_inset Text
3546
3547 \begin_layout Plain Layout
3548
3549 \end_layout
3550
3551 \end_inset
3552 </cell>
3553 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3554 \begin_inset Text
3555
3556 \begin_layout Plain Layout
3557 No
3558 \end_layout
3559
3560 \end_inset
3561 </cell>
3562 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
3563 \begin_inset Text
3564
3565 \begin_layout Plain Layout
3566 Yes
3567 \end_layout
3568
3569 \end_inset
3570 </cell>
3571 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3572 \begin_inset Text
3573
3574 \begin_layout Plain Layout
3575 Yes
3576 \end_layout
3577
3578 \end_inset
3579 </cell>
3580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3581 \begin_inset Text
3582
3583 \begin_layout Plain Layout
3584 -
3585 \end_layout
3586
3587 \end_inset
3588 </cell>
3589 <cell alignment="center" valignment="top" topline="true" usebox="none">
3590 \begin_inset Text
3591
3592 \begin_layout Plain Layout
3593 -
3594 \end_layout
3595
3596 \end_inset
3597 </cell>
3598 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3599 \begin_inset Text
3600
3601 \begin_layout Plain Layout
3602 -
3603 \end_layout
3604
3605 \end_inset
3606 </cell>
3607 <cell alignment="center" valignment="top" topline="true" usebox="none">
3608 \begin_inset Text
3609
3610 \begin_layout Plain Layout
3611 -
3612 \end_layout
3613
3614 \end_inset
3615 </cell>
3616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3617 \begin_inset Text
3618
3619 \begin_layout Plain Layout
3620 +
3621 \end_layout
3622
3623 \end_inset
3624 </cell>
3625 <cell alignment="center" valignment="top" topline="true" usebox="none">
3626 \begin_inset Text
3627
3628 \begin_layout Plain Layout
3629 -
3630 \end_layout
3631
3632 \end_inset
3633 </cell>
3634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3635 \begin_inset Text
3636
3637 \begin_layout Plain Layout
3638 -
3639 \end_layout
3640
3641 \end_inset
3642 </cell>
3643 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3644 \begin_inset Text
3645
3646 \begin_layout Plain Layout
3647 +
3648 \end_layout
3649
3650 \end_inset
3651 </cell>
3652 </row>
3653 <row>
3654 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3655 \begin_inset Text
3656
3657 \begin_layout Plain Layout
3658
3659 \end_layout
3660
3661 \end_inset
3662 </cell>
3663 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3664 \begin_inset Text
3665
3666 \begin_layout Plain Layout
3667
3668 \end_layout
3669
3670 \end_inset
3671 </cell>
3672 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3673 \begin_inset Text
3674
3675 \begin_layout Plain Layout
3676
3677 \end_layout
3678
3679 \end_inset
3680 </cell>
3681 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3682 \begin_inset Text
3683
3684 \begin_layout Plain Layout
3685 No
3686 \end_layout
3687
3688 \end_inset
3689 </cell>
3690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3691 \begin_inset Text
3692
3693 \begin_layout Plain Layout
3694 -
3695 \end_layout
3696
3697 \end_inset
3698 </cell>
3699 <cell alignment="center" valignment="top" topline="true" usebox="none">
3700 \begin_inset Text
3701
3702 \begin_layout Plain Layout
3703 +
3704 \end_layout
3705
3706 \end_inset
3707 </cell>
3708 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3709 \begin_inset Text
3710
3711 \begin_layout Plain Layout
3712 -
3713 \end_layout
3714
3715 \end_inset
3716 </cell>
3717 <cell alignment="center" valignment="top" topline="true" usebox="none">
3718 \begin_inset Text
3719
3720 \begin_layout Plain Layout
3721 -
3722 \end_layout
3723
3724 \end_inset
3725 </cell>
3726 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3727 \begin_inset Text
3728
3729 \begin_layout Plain Layout
3730 +
3731 \end_layout
3732
3733 \end_inset
3734 </cell>
3735 <cell alignment="center" valignment="top" topline="true" usebox="none">
3736 \begin_inset Text
3737
3738 \begin_layout Plain Layout
3739 +
3740 \end_layout
3741
3742 \end_inset
3743 </cell>
3744 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3745 \begin_inset Text
3746
3747 \begin_layout Plain Layout
3748 -
3749 \end_layout
3750
3751 \end_inset
3752 </cell>
3753 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3754 \begin_inset Text
3755
3756 \begin_layout Plain Layout
3757 -
3758 \end_layout
3759
3760 \end_inset
3761 </cell>
3762 </row>
3763 <row>
3764 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3765 \begin_inset Text
3766
3767 \begin_layout Plain Layout
3768
3769 \end_layout
3770
3771 \end_inset
3772 </cell>
3773 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3774 \begin_inset Text
3775
3776 \begin_layout Plain Layout
3777
3778 \end_layout
3779
3780 \end_inset
3781 </cell>
3782 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3783 \begin_inset Text
3784
3785 \begin_layout Plain Layout
3786 No
3787 \end_layout
3788
3789 \end_inset
3790 </cell>
3791 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3792 \begin_inset Text
3793
3794 \begin_layout Plain Layout
3795 -
3796 \end_layout
3797
3798 \end_inset
3799 </cell>
3800 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3801 \begin_inset Text
3802
3803 \begin_layout Plain Layout
3804 -
3805 \end_layout
3806
3807 \end_inset
3808 </cell>
3809 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
3810 \begin_inset Text
3811
3812 \begin_layout Plain Layout
3813 +
3814 \end_layout
3815
3816 \end_inset
3817 </cell>
3818 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3819 \begin_inset Text
3820
3821 \begin_layout Plain Layout
3822 -
3823 \end_layout
3824
3825 \end_inset
3826 </cell>
3827 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
3828 \begin_inset Text
3829
3830 \begin_layout Plain Layout
3831 -
3832 \end_layout
3833
3834 \end_inset
3835 </cell>
3836 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3837 \begin_inset Text
3838
3839 \begin_layout Plain Layout
3840 -
3841 \end_layout
3842
3843 \end_inset
3844 </cell>
3845 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
3846 \begin_inset Text
3847
3848 \begin_layout Plain Layout
3849 -
3850 \end_layout
3851
3852 \end_inset
3853 </cell>
3854 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3855 \begin_inset Text
3856
3857 \begin_layout Plain Layout
3858 -
3859 \end_layout
3860
3861 \end_inset
3862 </cell>
3863 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
3864 \begin_inset Text
3865
3866 \begin_layout Plain Layout
3867 -
3868 \end_layout
3869
3870 \end_inset
3871 </cell>
3872 </row>
3873 </lyxtabular>
3874
3875 \end_inset
3876
3877
3878 \end_layout
3879
3880 \begin_layout Subsubsection
3881 check_load tests
3882 \end_layout
3883
3884 \begin_layout Standard
3885 These tests check whether a .lyx file loads without any terminal messages.
3886  They correspond to the manual operations of simply opening a .lyx file on
3887  the terminal, exiting LyX once the file is loaded, and then checking whether
3888  there is any output from the terminal.
3889  These tests are useful for catching malformed .lyx files and parsing bugs.
3890  They can also be used to find a .lyx file in which an instance of something
3891  happens.
3892  To do this, compile LyX with a local patch that outputs something to the
3893  terminal when an instance is found, and then run the check_load tests to
3894  see if any fail, which would mean that the situation occurs in the LyX
3895  documentation files corresponding to the failed tests.
3896  These tests are expectedly fragile: any LyX diagnostic message, which is
3897  not necessarily an error, would cause the tests to fail.
3898  Similarly, any message output by a library (e.g.
3899  Qt) would also cause failure.
3900  There are some messages that the check_load tests are instructed to ignore,
3901  which are stored in the file
3902 \begin_inset Flex Code
3903 status collapsed
3904
3905 \begin_layout Plain Layout
3906 development/autotests/filterCheckWarnings
3907 \end_layout
3908
3909 \end_inset
3910
3911 .
3912 \end_layout
3913
3914 \begin_layout Standard
3915 Under cmake, the tests are labeled as 'load'.
3916 \end_layout
3917
3918 \begin_layout Subsubsection
3919 Keytests
3920 \end_layout
3921
3922 \begin_layout Standard
3923 Automated tests based on the "MonKey Testing" keytest program.
3924  They are documented in the README document in
3925 \begin_inset Flex Code
3926 status collapsed
3927
3928 \begin_layout Plain Layout
3929 development/autotests
3930 \end_layout
3931
3932 \end_inset
3933
3934  subfolder of the \SpecialChar LyX
3935  source code distribution.
3936  T
3937 \end_layout
3938
3939 \begin_layout Subsubsection
3940 lyx21 tests
3941 \end_layout
3942
3943 \begin_layout Standard
3944 These tests combine lyx2lyx tests with check_load tests.
3945  They fail if either fails.
3946 \end_layout
3947
3948 \begin_layout Subsubsection
3949 URL tests
3950 \end_layout
3951
3952 \begin_layout Standard
3953 The URL tests are enabled with the
3954 \begin_inset Flex Code
3955 status collapsed
3956
3957 \begin_layout Plain Layout
3958 -DLYX_ENABLE_URLTESTS=ON
3959 \end_layout
3960
3961 \end_inset
3962
3963  CMake flag and are useful for finding broken links in our documentation
3964  files.
3965  If a URL test fails, to see which link in particular was reported as broken,
3966  see the output in
3967 \begin_inset Flex Code
3968 status collapsed
3969
3970 \begin_layout Plain Layout
3971 LastTest.log
3972 \end_layout
3973
3974 \end_inset
3975
3976 .
3977  These tests are extremely fragile (e.g.
3978  a test can depend on your Internet connection) and a failed URL test should
3979  not be taken too seriously.
3980  URL tests are labeled as
3981 \family typewriter
3982 'url'.
3983 \end_layout
3984
3985 \begin_layout Paragraph
3986 Running URL tests
3987 \end_layout
3988
3989 \begin_layout Standard
3990 cmake is required to run the \SpecialChar LyX
3991  tests, running them is not implemented for
3992  autotools.
3993 \end_layout
3994
3995 \begin_layout Standard
3996 The appropriate commands are:
3997 \end_layout
3998
3999 \begin_layout Itemize
4000
4001 \family typewriter
4002 ctest -L url
4003 \family default
4004
4005 \begin_inset Newline newline
4006 \end_inset
4007
4008 runs all tests with label
4009 \family typewriter
4010 'url'
4011 \end_layout
4012
4013 \begin_layout Itemize
4014
4015 \family typewriter
4016 ctest -R 'check_.*urls'
4017 \family default
4018
4019 \begin_inset Newline newline
4020 \end_inset
4021
4022 runs the tests 'check_accessible_urls'
4023 \end_layout
4024
4025 \begin_layout Standard
4026 Associated test results can be examined in ctest-log directory in files
4027  of the form 'LastFailed.*URLS.log'
4028 \end_layout
4029
4030 \begin_layout Section
4031 Development policies
4032 \end_layout
4033
4034 \begin_layout Standard
4035 This chapter lists some guidelines that should be followed.
4036  This list is not complete, and many guidelines are in separate chapters,
4037  such as
4038 \begin_inset Quotes eld
4039 \end_inset
4040
4041 When is an update of the .lyx file format number needed?
4042 \begin_inset Quotes erd
4043 \end_inset
4044
4045  in Section
4046 \begin_inset CommandInset ref
4047 LatexCommand ref
4048 reference "sec:When-is-an"
4049
4050 \end_inset
4051
4052 .
4053 \end_layout
4054
4055 \begin_layout Subsection
4056 When to set a fixed milestone?
4057 \end_layout
4058
4059 \begin_layout Standard
4060 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
4061  holds:
4062 \end_layout
4063
4064 \begin_layout Enumerate
4065 Somebody is actively working on a fix.
4066 \end_layout
4067
4068 \begin_layout Enumerate
4069 The bug is so severe that it would block the release if it is not fixed.
4070 \end_layout
4071
4072 \begin_layout Standard
4073 If a bug is important, but nobody is working on it, and it is no showstopper,
4074  use a milestone like 2.1.x or 2.2.x.
4075  For all other bugs, do not set a milestone at all.
4076 \end_layout
4077
4078 \begin_layout Subsection
4079 Can we add rc entries in stable branch?
4080 \end_layout
4081
4082 \begin_layout Standard
4083 No.
4084  We are supposed to increase the prefs2prefs version number with such things.
4085 \end_layout
4086
4087 \begin_layout Section
4088 Documentation policies
4089 \end_layout
4090
4091 \begin_layout Standard
4092 The main documentation consists of these files:
4093 \end_layout
4094
4095 \begin_layout Description
4096 splash.lyx it is the first file you see after an installation.
4097  We assume that a new user sees this.
4098  It is therefore designed to be as simple as possible.
4099  Therefore please don't add any new formatting, only fix typos etc.
4100  Splash.lyx is up to date for \SpecialChar LyX
4101  2.1.x, currently maintained by Uwe Stöhr.
4102 \end_layout
4103
4104 \begin_layout Description
4105 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
4106 .
4107  It therefore uses a limited set of formatting.
4108  For example a standard document class.
4109  Since new users will first learn about the formatting possibilities of
4110  \SpecialChar LyX
4111  please keep this file that simple.
4112  Intro.lyx is up to date for \SpecialChar LyX
4113  2.1.x, currently maintained by Uwe Stöhr.
4114 \end_layout
4115
4116 \begin_layout Description
4117 Tutorial.lyx our tutorial.
4118  It must be always up to date.
4119  Normally there is nothing to add since we don't want to overwhelm new users
4120  with too much details.
4121  The will learn these details while using \SpecialChar LyX
4122  and we have special manuals.
4123  Tutorial.lyx is up to date for \SpecialChar LyX
4124  2.1.x, currently maintained by Uwe Stöhr.
4125 \end_layout
4126
4127 \begin_layout Description
4128 UserGuide.lyx our main user guide.
4129  It covers a mixture of basic and detailed information.
4130  Some information is also in the Math and EmbeddedObjects manual so that
4131  the UserGuide refers to these files.
4132  UserGuide.lyx is up to date for \SpecialChar LyX
4133  2.1.x, currently maintained by Uwe Stöhr.
4134 \end_layout
4135
4136 \begin_layout Description
4137 EmbeddedObjects.lyx a special manual to explain things like tables floats
4138  boxes etc.
4139  in all detail.
4140  EmbeddedObjects.lyx is up to date for \SpecialChar LyX
4141  2.1.x, currently maintained by Uwe
4142  Stöhr.
4143 \end_layout
4144
4145 \begin_layout Description
4146 Math.lyx a special manual to explain everything regarding math in all detail.
4147  Math.lyx is up to date for \SpecialChar LyX
4148  2.1.x, currently maintained by Uwe Stöhr.
4149 \end_layout
4150
4151 \begin_layout Description
4152 Additional.lyx this manual covers information that would be too much detail
4153  for the UserGuide or would make the UserGuide uncompilable or only compilable
4154  when installing a lot of special \SpecialChar LaTeX
4155 -packages.
4156  What should be in the UserGuide or better in Additional is a matter of
4157  taste.
4158  it is up to you to decide that.
4159  Additional.lyx is not completely up to date for \SpecialChar LyX
4160  2.1.x.
4161  Only chapter
4162 \begin_inset space ~
4163 \end_inset
4164
4165 8 is up to date and currently maintained by Uwe Stöhr.
4166  It certainly needs a rewrite and update.
4167  For example many info in chapter
4168 \begin_inset space ~
4169 \end_inset
4170
4171 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
4172  manual.
4173 \end_layout
4174
4175 \begin_layout Description
4176 Customization.lyx this manual covers information how to customize \SpecialChar LyX
4177  for certain
4178  output formats, operating systems, languages etc.
4179  It is currently completely out of date and needs a major rewrite and update.
4180  If you do this please assure that your information are given for all OSes
4181  and \SpecialChar LaTeX
4182  distributions (meaning be as objective as possible).
4183 \end_layout
4184
4185 \begin_layout Standard
4186 There are only 4
4187 \begin_inset space ~
4188 \end_inset
4189
4190 rules in editing the docs:
4191 \end_layout
4192
4193 \begin_layout Enumerate
4194 If you are not the maintainer of a doc file or a chapter/section, you MUST
4195  use change tracking so that the maintainer could review your changes
4196 \end_layout
4197
4198 \begin_layout Enumerate
4199 Respect the formatting of the document.
4200  The different files use different formatting styles.
4201  That is OK and has historic reasons nobody fully know ;-).
4202  But it is important to be consistent within one file.
4203 \end_layout
4204
4205 \begin_layout Enumerate
4206 All changes you make to a file in one language MUST also go the file in
4207  the other actively maintained languages.
4208  Normally the maintainer does this for you, if you are the maintainer, you
4209  must do this by copying or changing the changed or added text to the other
4210  files so that the translators sees the blue underlined text and know what
4211  they have to translate and what was changed.
4212 \end_layout
4213
4214 \begin_layout Enumerate
4215 You MUST assure that the document is compilable as
4216 \begin_inset Quotes eld
4217 \end_inset
4218
4219 PDF (pdflatex)
4220 \begin_inset Quotes erd
4221 \end_inset
4222
4223  after your changes.
4224 \end_layout
4225
4226 \end_body
4227 \end_document