lib/doc/Development.lyx

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