lib/doc/Development.lyx

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