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 right-click on the project
2031 \family sans
2032 updatetex2lyxtests
2033 \family default
2034  in the project explorer and chose
2035 \family sans
2036 Create
2037 \family default
2038 .
2039 \end_layout
2040
2041 \begin_layout Standard
2042 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2043  files.
2044  Please examine the changed output carefully before committing the changed
2045  files to the repository: Since the test machinery does not do a roundtrip
2046  test .tex
2047 \begin_inset Formula $\Rightarrow$
2048 \end_inset
2049
2050  .lyx
2051 \begin_inset Formula $\Rightarrow$
2052 \end_inset
2053
2054  .tex, and does not compare the produced dvi or pdf output, it assumes that
2055  the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2056 .
2057  There is only one chance to detect wrong output: before committing a new
2058  reference.
2059  Once it is committed, it is quite difficult to verify whether it is correct.
2060 \end_layout
2061
2062 \begin_layout Standard
2063 Please
2064 \emph on
2065 do not
2066 \emph default
2067  update the test references by opening them with \SpecialChar LyX
2068  or directly running lyx2lyx
2069  on them.
2070  This would not work, since lyx2lyx and \SpecialChar LyX
2071  produce slightly different files
2072  regarding insignificant whitespace and line breaks.
2073 \end_layout
2074
2075 \begin_layout Subsubsection
2076 Adding a new test
2077 \end_layout
2078
2079 \begin_layout Standard
2080 In many cases tests for new features may be added to one of the existing
2081  test files, but sometimes this is not possible or not wanted.
2082  Then a new test file needs to be added:
2083 \end_layout
2084
2085 \begin_layout Enumerate
2086 Create the new file
2087 \begin_inset Flex Code
2088 status collapsed
2089
2090 \begin_layout Plain Layout
2091 src/tex2lyx/test/<test name>.tex
2092 \end_layout
2093
2094 \end_inset
2095
2096  and run tex2lyx in roundtrip mode to produce the file
2097 \begin_inset Flex Code
2098 status collapsed
2099
2100 \begin_layout Plain Layout
2101 src/tex2lyx/test/<test name>.lyx.lyx
2102 \end_layout
2103
2104 \end_inset
2105
2106 .
2107  This file will be the new reference.
2108 \end_layout
2109
2110 \begin_layout Enumerate
2111 Once you confirmed that the tex2lyx output is correct, add the new files
2112  to the corresponding lists in
2113 \begin_inset Flex Code
2114 status collapsed
2115
2116 \begin_layout Plain Layout
2117 src/tex2lyx/test/runtests.py
2118 \end_layout
2119
2120 \end_inset
2121
2122 ,
2123 \begin_inset Flex Code
2124 status collapsed
2125
2126 \begin_layout Plain Layout
2127 src/tex2lyx/Makefile.am
2128 \end_layout
2129
2130 \end_inset
2131
2132  and
2133 \begin_inset Flex Code
2134 status collapsed
2135
2136 \begin_layout Plain Layout
2137 src/tex2lyx/test/CMakeLists.txt
2138 \end_layout
2139
2140 \end_inset
2141
2142 .
2143 \end_layout
2144
2145 \begin_layout Enumerate
2146 Commit the changes to the repository, or send a patch to the development
2147  list and ask for committing if you do not have commit rights.
2148 \end_layout
2149
2150 \begin_layout Subsection
2151 ctest automatic tests
2152 \end_layout
2153
2154 \begin_layout Standard
2155 Some tests are located in the
2156 \begin_inset Flex Code
2157 status collapsed
2158
2159 \begin_layout Plain Layout
2160 development/autotests/
2161 \end_layout
2162
2163 \end_inset
2164
2165  subfolder of the \SpecialChar LyX
2166  source code distribution.
2167
2168 \begin_inset Foot
2169 status open
2170
2171 \begin_layout Plain Layout
2172 The README document in this folder only describes the
2173 \begin_inset Quotes eld
2174 \end_inset
2175
2176 keytests
2177 \begin_inset Quotes erd
2178 \end_inset
2179
2180  subset of autotests!
2181 \end_layout
2182
2183 \end_inset
2184
2185
2186 \end_layout
2187
2188 \begin_layout Standard
2189 These tests can be run by the commands
2190 \begin_inset Flex Code
2191 status collapsed
2192
2193 \begin_layout Plain Layout
2194 ctest
2195 \end_layout
2196
2197 \end_inset
2198
2199  in the
2200 \emph on
2201  build directory
2202 \emph default
2203  (all platforms) or (when using a make based build system and not MSVC)
2204
2205 \begin_inset Flex Code
2206 status collapsed
2207
2208 \begin_layout Plain Layout
2209 make test
2210 \end_layout
2211
2212 \end_inset
2213
2214  in the
2215 \begin_inset Flex Code
2216 status collapsed
2217
2218 \begin_layout Plain Layout
2219 autotests/
2220 \end_layout
2221
2222 \end_inset
2223
2224  subfolder of the
2225 \emph on
2226  build directory
2227 \emph default
2228 .
2229  The test logs are written to the
2230 \begin_inset Flex Code
2231 status collapsed
2232
2233 \begin_layout Plain Layout
2234 Testing/Temporary/
2235 \end_layout
2236
2237 \end_inset
2238
2239  subfolder of the
2240 \emph on
2241
2242 \emph default
2243 build directory.
2244
2245 \end_layout
2246
2247 \begin_layout Subsubsection
2248 Export tests
2249 \end_layout
2250
2251 \begin_layout Standard
2252 The export tests are integration tests.
2253  They take longer to run and are more likely to break than the tex2lyx tests.
2254  Nevertheless, they have caught many regressions and without a better alternativ
2255 e it is important to keep them up-to-date and understand how they work.
2256 \end_layout
2257
2258 \begin_layout Standard
2259 The export tests
2260 \begin_inset Quotes eld
2261 \end_inset
2262
2263 reuse
2264 \begin_inset Quotes erd
2265 \end_inset
2266
2267  documentation, template, and example documents.
2268  In addition, there are a number of dedicated sample documents in the
2269 \begin_inset Flex Code
2270 status collapsed
2271
2272 \begin_layout Plain Layout
2273 autotests/export/
2274 \end_layout
2275
2276 \end_inset
2277
2278  subfolder of the \SpecialChar LyX
2279  source code distribution.
2280  All samples are (after copying and eventual processing by scripts) exported
2281  to various output formats via the
2282 \begin_inset Flex Code
2283 status collapsed
2284
2285 \begin_layout Plain Layout
2286 —export-to
2287 \end_layout
2288
2289 \end_inset
2290
2291  command line option.
2292  The tests checks for errors reported by LyX.
2293  (However, error-free export is no guarantee for an error-free output document.)
2294 \end_layout
2295
2296 \begin_layout Paragraph
2297 \begin_inset CommandInset label
2298 LatexCommand label
2299 name "par:when-to-run-an-export-test"
2300
2301 \end_inset
2302
2303 Expectations of LyX developers
2304 \end_layout
2305
2306 \begin_layout Standard
2307 Because the export tests are integration tests and take a long time to run,
2308  LyX developers are rarely expected to run all of the tests.
2309  Here are some good practices to follow by developers:
2310 \end_layout
2311
2312 \begin_layout Itemize
2313 When making a non-trivial change to a .layout file, run the export and layout
2314  tests corresponding with that .layout file.
2315 \end_layout
2316
2317 \begin_layout Itemize
2318 When making non-trivial changes to a .lyx file, run the export tests correspondin
2319 g to that .lyx file.
2320
2321 \begin_inset Foot
2322 status collapsed
2323
2324 \begin_layout Plain Layout
2325 This rule is due to revision.
2326
2327 \end_layout
2328
2329 \begin_layout Plain Layout
2330 There is an objection from the documentation maintainer that working on
2331  the documentation must not be complicated by having to consider non-standard
2332  exports.
2333 \end_layout
2334
2335 \begin_layout Itemize
2336 successful compiling/testing an edited documentation file with pdflatex
2337  suffices to ensure it can be commited, not tests with other exports are
2338  required.
2339 \end_layout
2340
2341 \begin_layout Plain Layout
2342 If sudden failures with other exports due to “half-tested” documentation
2343  updates are a problem for the test maintainer, the test suite should use
2344  copies that are
2345 \end_layout
2346
2347 \begin_layout Itemize
2348 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2349 \end_layout
2350
2351 \begin_layout Itemize
2352 updated regularely (but on a time chosen by the test suite maintainer) from
2353  the originals in lib/doc/
2354 \end_layout
2355
2356 \begin_layout Plain Layout
2357 This way,
2358 \end_layout
2359
2360 \begin_layout Itemize
2361 no test will fail due to ongoing work on documentation,
2362 \end_layout
2363
2364 \begin_layout Itemize
2365 the documentation is still tested in full (with some delay),
2366 \end_layout
2367
2368 \begin_layout Itemize
2369 failures with non-default export can be examined and handled accordingly
2370  in one run with the cache update,
2371 \end_layout
2372
2373 \begin_layout Itemize
2374 “interesting failures” (like the nested-language+polyglossia problem in
2375  es/Customization can be separated and moved into dedicated test samples.
2376 \end_layout
2377
2378 \end_inset
2379
2380
2381 \end_layout
2382
2383 \begin_layout Itemize
2384 When making non-trivial changes to LyX's \SpecialChar LaTeX
2385  export code (e.g.
2386  touching the encoding code or package handling code that you expect will
2387  change the exported \SpecialChar LaTeX
2388  in some way):
2389 \end_layout
2390
2391 \begin_deeper
2392 \begin_layout Standard
2393 \paragraph_spacing single
2394 Consider running all of the export tests before and after your change.
2395  If there are differences, please reconcile these (i.e.
2396  fix the bug or fix the tests)
2397 \emph on
2398 before
2399 \emph default
2400  committing.
2401  Ask for help if you're not sure what to.
2402 \end_layout
2403
2404 \begin_layout Standard
2405 If you do not want to run the tests,
2406 \end_layout
2407
2408 \begin_layout Itemize
2409 post the patch on the list and others will run the tests and eventually
2410  ask for fixes, or
2411 \end_layout
2412
2413 \begin_layout Itemize
2414 commit, but be prepared to fix eventually arising problems or to revert
2415  the commit if there is no easy fix.
2416 \end_layout
2417
2418 \end_deeper
2419 \begin_layout Itemize
2420 Understand how to interpret test failures.
2421  If your commit is found to have broken a test, you should be able to interpret
2422  the test results when made aware of them.
2423  See Section
2424 \begin_inset CommandInset ref
2425 LatexCommand ref
2426 reference "subsec:Interpreting-export-tests"
2427
2428 \end_inset
2429
2430 .
2431 \end_layout
2432
2433 \begin_layout Paragraph
2434 \begin_inset CommandInset label
2435 LatexCommand label
2436 name "par:export-test-output-formats"
2437
2438 \end_inset
2439
2440 Output formats
2441 \end_layout
2442
2443 \begin_layout Standard
2444 The following output formats are currently tested for each sample document
2445  (see
2446 \begin_inset CommandInset ref
2447 LatexCommand ref
2448 reference "par:Export-test-filtering"
2449
2450 \end_inset
2451
2452  for exceptions):
2453 \end_layout
2454
2455 \begin_layout Labeling
2456 \labelwidthstring 00.00.0000
2457 LyX:
2458 \end_layout
2459
2460 \begin_deeper
2461 \begin_layout Labeling
2462 \labelwidthstring 00.00.0000
2463 lyx16 LyX 1.6 file format (lyx2lyx)
2464 \end_layout
2465
2466 \begin_layout Labeling
2467 \labelwidthstring 00.00.0000
2468 lyx21 LyX 2.1 file format (lyx2lyx)
2469 \end_layout
2470
2471 \begin_layout Labeling
2472 \labelwidthstring 00.00.0000
2473 xhtml LyXHTML (native LyX HTML export)
2474 \end_layout
2475
2476 \end_deeper
2477 \begin_layout Labeling
2478 \labelwidthstring 00.00.0000
2479 LyX
2480 \begin_inset space ~
2481 \end_inset
2482
2483 +
2484 \begin_inset space ~
2485 \end_inset
2486
2487 LaTeX:
2488 \end_layout
2489
2490 \begin_deeper
2491 \begin_layout Labeling
2492 \labelwidthstring pdf5msystemFM
2493 dvi DVI (8-bit latex)
2494 \end_layout
2495
2496 \begin_layout Labeling
2497 \labelwidthstring pdf5msystemFM
2498 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2499 \end_layout
2500
2501 \begin_layout Labeling
2502 \labelwidthstring pdf5msystemFM
2503 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2504 \end_layout
2505
2506 \begin_layout Labeling
2507 \labelwidthstring pdf5msystemFM
2508 pdf2 PDF (pdflatex)
2509 \end_layout
2510
2511 \begin_layout Labeling
2512 \labelwidthstring pdf5msystemFM
2513 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2514 \end_layout
2515
2516 \begin_layout Labeling
2517 \labelwidthstring pdf5msystemFM
2518 pdf4_systemF PDF (XeTeX with Unicode fonts)
2519 \end_layout
2520
2521 \begin_layout Labeling
2522 \labelwidthstring pdf5msystemFM
2523 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2524 \end_layout
2525
2526 \begin_layout Labeling
2527 \labelwidthstring pdf5msystemFM
2528 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2529 \end_layout
2530
2531 \end_deeper
2532 \begin_layout Labeling
2533 \labelwidthstring 00.00.0000
2534 LyX
2535 \begin_inset space ~
2536 \end_inset
2537
2538 +
2539 \begin_inset space ~
2540 \end_inset
2541
2542 LaTeX
2543 \begin_inset space ~
2544 \end_inset
2545
2546 +
2547 \begin_inset space ~
2548 \end_inset
2549
2550 postprocessing:
2551 \end_layout
2552
2553 \begin_deeper
2554 \begin_layout Labeling
2555 \labelwidthstring pdf5msystemFM
2556 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2557 \end_layout
2558
2559 \begin_layout Labeling
2560 \labelwidthstring pdf5msystemFM
2561 pdf3 DVI -> PDF (dvipdfm)
2562 \end_layout
2563
2564 \end_deeper
2565 \begin_layout Labeling
2566 \labelwidthstring 00.00.0000
2567 not
2568 \begin_inset space ~
2569 \end_inset
2570
2571 tested: (or only if set as default output format in the document source)
2572 \end_layout
2573
2574 \begin_deeper
2575 \begin_layout Labeling
2576 \labelwidthstring pdf5msystemFM
2577 latex LaTeX (plain)
2578 \end_layout
2579
2580 \begin_layout Labeling
2581 \labelwidthstring pdf5msystemFM
2582 luatex LaTeX (LuaTeX)
2583 \end_layout
2584
2585 \begin_layout Labeling
2586 \labelwidthstring pdf5msystemFM
2587 dviluatex LaTeX (dviluatex)
2588 \end_layout
2589
2590 \begin_layout Labeling
2591 \labelwidthstring pdf5msystemFM
2592 pdflatex LaTeX (pdflatex)
2593 \end_layout
2594
2595 \begin_layout Labeling
2596 \labelwidthstring pdf5msystemFM
2597 platex LaTeX (pLaTeX)
2598 \end_layout
2599
2600 \begin_layout Labeling
2601 \labelwidthstring pdf5msystemFM
2602 xetex LaTeX (XeTeX)
2603 \end_layout
2604
2605 \begin_layout Labeling
2606 \labelwidthstring pdf5msystemFM
2607 eps3 EPS (encapsulated Postscript) (cropped)
2608 \end_layout
2609
2610 \begin_layout Labeling
2611 \labelwidthstring pdf5msystemFM
2612 ps DVI -> Postscript (dvips)
2613 \end_layout
2614
2615 \begin_layout Labeling
2616 \labelwidthstring pdf5msystemFM
2617 odf
2618 \end_layout
2619
2620 \begin_layout Labeling
2621 \labelwidthstring pdf5msystemFM
2622 text (nor text2, ..., text4)
2623 \end_layout
2624
2625 \begin_layout Labeling
2626 \labelwidthstring pdf5msystemFM
2627 textparagraph
2628 \end_layout
2629
2630 \begin_layout Labeling
2631 \labelwidthstring pdf5msystemFM
2632 word
2633 \end_layout
2634
2635 \begin_layout Labeling
2636 \labelwidthstring pdf5msystemFM
2637 word2
2638 \end_layout
2639
2640 \begin_layout Labeling
2641 \labelwidthstring pdf5msystemFM
2642 wordhtml
2643 \end_layout
2644
2645 \end_deeper
2646 \begin_layout Paragraph
2647 \begin_inset CommandInset label
2648 LatexCommand label
2649 name "par:Configuring-ctests"
2650
2651 \end_inset
2652
2653 Configuring the tests
2654 \end_layout
2655
2656 \begin_layout Standard
2657 To enable the export autotests, add the
2658 \begin_inset Flex Code
2659 status collapsed
2660
2661 \begin_layout Plain Layout
2662 -DLYX_ENABLE_EXPORT_TESTS=ON
2663 \end_layout
2664
2665 \end_inset
2666
2667  flag.
2668  For example:
2669 \end_layout
2670
2671 \begin_layout Standard
2672 \begin_inset Flex Code
2673 status collapsed
2674
2675 \begin_layout Plain Layout
2676 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2677 \end_layout
2678
2679 \end_inset
2680
2681
2682 \end_layout
2683
2684 \begin_layout Standard
2685 \noindent
2686 This flag will increase the time for the cmake command by several seconds,
2687  mainly because of the process of inverting tests (see Section
2688 \begin_inset CommandInset ref
2689 LatexCommand ref
2690 reference "subsec:Interpreting-export-tests"
2691
2692 \end_inset
2693
2694 ).
2695 \end_layout
2696
2697 \begin_layout Paragraph
2698 \begin_inset CommandInset label
2699 LatexCommand label
2700 name "par:ctest-options"
2701
2702 \end_inset
2703
2704 Running the tests
2705 \end_layout
2706
2707 \begin_layout Standard
2708 To run all tests, in the build directory simply run the command
2709 \begin_inset Flex Code
2710 status collapsed
2711
2712 \begin_layout Plain Layout
2713 ctest
2714 \end_layout
2715
2716 \end_inset
2717
2718 .
2719  A full, up-to-date TeXLive installation is recommended to run the tests.
2720  Otherwise, some tests will fail.
2721  Tests with additional requirements are labeled
2722 \begin_inset Quotes eld
2723 \end_inset
2724
2725 unreliable:nonstandard
2726 \begin_inset Quotes erd
2727 \end_inset
2728
2729 .
2730
2731 \end_layout
2732
2733 \begin_layout Standard
2734 To run only some of the tests, use command line options (see examples below):
2735 \end_layout
2736
2737 \begin_layout Labeling
2738 \labelwidthstring -R
2739 \begin_inset Flex Code
2740 status collapsed
2741
2742 \begin_layout Plain Layout
2743 -R <pattern>
2744 \end_layout
2745
2746 \end_inset
2747
2748  Run only the tests whose names match the given regular expression.
2749 \end_layout
2750
2751 \begin_layout Labeling
2752 \labelwidthstring -R
2753 \begin_inset Flex Code
2754 status collapsed
2755
2756 \begin_layout Plain Layout
2757 -L <pattern>
2758 \end_layout
2759
2760 \end_inset
2761
2762  Run only the tests whose labels match the given regular expression.
2763  A test may have more that one label.
2764
2765 \end_layout
2766
2767 \begin_layout Labeling
2768 \labelwidthstring -R
2769 \begin_inset Flex Code
2770 status collapsed
2771
2772 \begin_layout Plain Layout
2773 -E <pattern>
2774 \end_layout
2775
2776 \end_inset
2777
2778  Exclude the tests whose names match the given regular expression.
2779 \end_layout
2780
2781 \begin_layout Labeling
2782 \labelwidthstring -R
2783 \begin_inset Flex Code
2784 status collapsed
2785
2786 \begin_layout Plain Layout
2787 -LE <pattern>
2788 \end_layout
2789
2790 \end_inset
2791
2792  Exclude the tests whose labels match the given regular expression.
2793  Cannot be combined with
2794 \begin_inset Flex Code
2795 status collapsed
2796
2797 \begin_layout Plain Layout
2798 -L
2799 \end_layout
2800
2801 \end_inset
2802
2803 .
2804 \end_layout
2805
2806 \begin_layout Standard
2807 The following options help to find good selection patterns:
2808 \end_layout
2809
2810 \begin_layout Labeling
2811 \labelwidthstring -R
2812 \begin_inset Flex Code
2813 status collapsed
2814
2815 \begin_layout Plain Layout
2816 -N
2817 \end_layout
2818
2819 \end_inset
2820
2821  List the tests that would be run but not actually run them.
2822
2823 \end_layout
2824
2825 \begin_deeper
2826 \begin_layout Standard
2827 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2828  to know how many tests there are or whether your
2829 \begin_inset Flex Code
2830 status collapsed
2831
2832 \begin_layout Plain Layout
2833 <pattern>
2834 \end_layout
2835
2836 \end_inset
2837
2838  regular expression did what you expected.
2839 \end_layout
2840
2841 \end_deeper
2842 \begin_layout Labeling
2843 \labelwidthstring -R
2844 \begin_inset Flex Code
2845 status collapsed
2846
2847 \begin_layout Plain Layout
2848 \SpecialChar nobreakdash
2849 \SpecialChar nobreakdash
2850 print-labels
2851 \end_layout
2852
2853 \end_inset
2854
2855  print the list of all labels associated with the test set.
2856  Can also be combined with -R, -L, -E, ...
2857
2858 \end_layout
2859
2860 \begin_layout Standard
2861 Other useful options are:
2862 \end_layout
2863
2864 \begin_layout Labeling
2865 \labelwidthstring -R
2866 \begin_inset Flex Code
2867 status collapsed
2868
2869 \begin_layout Plain Layout
2870 -j <jobs>
2871 \end_layout
2872
2873 \end_inset
2874
2875  Run the tests in parallel using the given number of jobs.
2876 \end_layout
2877
2878 \begin_deeper
2879 \begin_layout Standard
2880 We are still working on getting the tests to run in parallel.
2881  However, when running the tests in parallel, sometimes tests fail that
2882  pass when run sequentially.
2883  A reasonable approach is to first run the tests in parallel and then run
2884  the failed tests sequentially.
2885 \end_layout
2886
2887 \begin_layout Standard
2888 For example, to run 8 jobs at a time:
2889 \end_layout
2890
2891 \begin_layout Standard
2892 \begin_inset Flex Code
2893 status collapsed
2894
2895 \begin_layout Plain Layout
2896 ctest -j8
2897 \end_layout
2898
2899 \end_inset
2900
2901
2902 \end_layout
2903
2904 \begin_layout Standard
2905 \begin_inset Flex Code
2906 status collapsed
2907
2908 \begin_layout Plain Layout
2909 ctest \SpecialChar nobreakdash
2910 \SpecialChar nobreakdash
2911 rerun-failed
2912 \end_layout
2913
2914 \end_inset
2915
2916
2917 \end_layout
2918
2919 \begin_layout Standard
2920 When specifying a subset of the tests (e.g.
2921  using
2922 \begin_inset Flex Code
2923 status collapsed
2924
2925 \begin_layout Plain Layout
2926 \SpecialChar nobreakdash
2927 R <pattern>
2928 \end_layout
2929
2930 \end_inset
2931
2932 ), the same subset must be specified when using the
2933 \begin_inset Flex Code
2934 status collapsed
2935
2936 \begin_layout Plain Layout
2937 \SpecialChar nobreakdash
2938 \SpecialChar nobreakdash
2939 rerun-failed
2940 \end_layout
2941
2942 \end_inset
2943
2944  option because it is the test numbers that are used to index which tests
2945  failed on the previous run.
2946 \end_layout
2947
2948 \begin_layout Standard
2949 \noindent
2950 Note that some tests cannot be run in parallel.
2951  These tests are marked in the code with the
2952 \begin_inset Flex Code
2953 status collapsed
2954
2955 \begin_layout Plain Layout
2956 \noindent
2957 RUN_SERIAL ON
2958 \end_layout
2959
2960 \end_inset
2961
2962  CMake property.
2963 \end_layout
2964
2965 \end_deeper
2966 \begin_layout Labeling
2967 \labelwidthstring -R
2968 \begin_inset Flex Code
2969 status collapsed
2970
2971 \begin_layout Plain Layout
2972 \SpecialChar nobreakdash
2973 \SpecialChar nobreakdash
2974 timeout <seconds>
2975 \end_layout
2976
2977 \end_inset
2978
2979  Set a global timeout on all tests that do not already have a timeout set
2980  on them.
2981 \end_layout
2982
2983 \begin_deeper
2984 \begin_layout Standard
2985 There have been bugs in LyX and in \SpecialChar LaTeX
2986  which cause compilation to hang, and
2987  without a timeout a test might never stop (in one case there was even a
2988  memory leak).
2989  If a test times out, the
2990 \begin_inset Flex Code
2991 status collapsed
2992
2993 \begin_layout Plain Layout
2994 ctest
2995 \end_layout
2996
2997 \end_inset
2998
2999  command exits with error, but you can distinguish between a timed out test
3000  and a failed test in the output reported at the end of the
3001 \begin_inset Flex Code
3002 status collapsed
3003
3004 \begin_layout Plain Layout
3005 ctest
3006 \end_layout
3007
3008 \end_inset
3009
3010  command.
3011 \end_layout
3012
3013 \end_deeper
3014 \begin_layout Standard
3015 See the manual (
3016 \begin_inset Flex Code
3017 status collapsed
3018
3019 \begin_layout Plain Layout
3020 man ctest
3021 \end_layout
3022
3023 \end_inset
3024
3025 ) the full list of command line options.
3026 \end_layout
3027
3028 \begin_layout Paragraph
3029 Examples
3030 \end_layout
3031
3032 \begin_layout Itemize
3033 run only the export tests:
3034 \begin_inset Flex Code
3035 status collapsed
3036
3037 \begin_layout Plain Layout
3038 ctest -L export
3039 \end_layout
3040
3041 \end_inset
3042
3043
3044 \end_layout
3045
3046 \begin_layout Itemize
3047 run inverted tests:
3048 \begin_inset Flex Code
3049 status collapsed
3050
3051 \begin_layout Plain Layout
3052 ctest -L "inverted|suspended"
3053 \end_layout
3054
3055 \end_inset
3056
3057
3058 \end_layout
3059
3060 \begin_layout Itemize
3061 list all export tests which match any of the labelling patterns:
3062 \begin_inset Flex Code
3063 status collapsed
3064
3065 \begin_layout Plain Layout
3066 ctest -N -R "
3067 \backslash
3068 ..*_export/"
3069 \end_layout
3070
3071 \end_inset
3072
3073
3074 \end_layout
3075
3076 \begin_layout Itemize
3077 exclude rarely used output formats and post-processing tests
3078 \begin_inset Flex Code
3079 status collapsed
3080
3081 \begin_layout Plain Layout
3082 ctest -L export -E "_(texF|dvi3|pdf3?)"
3083 \end_layout
3084
3085 \end_inset
3086
3087
3088 \end_layout
3089
3090 \begin_layout Paragraph
3091 \begin_inset CommandInset label
3092 LatexCommand label
3093 name "subsec:Interpreting-export-tests"
3094
3095 \end_inset
3096
3097 Interpreting the export test results
3098 \end_layout
3099
3100 \begin_layout Standard
3101 A test can fail for several reasons, not all of them bad.
3102 \end_layout
3103
3104 \begin_layout Enumerate
3105 A new or edited sample document may be incompatible with some output formats.
3106 \end_layout
3107
3108 \begin_layout Enumerate
3109 A dependency is not met (e.g.
3110  the \SpecialChar LaTeX
3111  class file).
3112  One hint that this is the case is that the corresponding
3113 \begin_inset Flex Code
3114 status collapsed
3115
3116 \begin_layout Plain Layout
3117 check_load
3118 \end_layout
3119
3120 \end_inset
3121
3122  test will likely also fail.
3123 \end_layout
3124
3125 \begin_layout Enumerate
3126 An inverted test fails to fail (i.e.
3127  export that previously failed now works).
3128 \end_layout
3129
3130 \begin_layout Enumerate
3131 An external dependency was updated (e.g.
3132  \SpecialChar TeX
3133  Live).
3134 \end_layout
3135
3136 \begin_layout Enumerate
3137 A recent code change introduced a bug.
3138 \end_layout
3139
3140 \begin_layout Enumerate
3141 \begin_inset CommandInset label
3142 LatexCommand label
3143 name "enu:exposed"
3144
3145 \end_inset
3146
3147 A change in a document exposed a previously unknown bug or an incompatibility
3148  with an export format (e.g.
3149  Lua\SpecialChar LaTeX
3150 ).
3151 \end_layout
3152
3153 \begin_layout Standard
3154 Because the .lyx files are exported in several formats, it is not surprising
3155  that many of the exports fail.
3156  This expectation of failure is addressed by
3157 \begin_inset Quotes eld
3158 \end_inset
3159
3160 inverting
3161 \begin_inset Quotes erd
3162 \end_inset
3163
3164  the tests, that is, by marking the test as
3165 \begin_inset Quotes eld
3166 \end_inset
3167
3168 passing
3169 \begin_inset Quotes erd
3170 \end_inset
3171
3172  if the export exits with error and as
3173 \begin_inset Quotes eld
3174 \end_inset
3175
3176 failing
3177 \begin_inset Quotes erd
3178 \end_inset
3179
3180  if the export succeeds
3181 \emph on
3182 .
3183
3184 \emph default
3185  It follows that these expected failures will not show up as failed tests
3186  in the test results and thus will not pollute the
3187 \begin_inset Quotes eld
3188 \end_inset
3189
3190 good
3191 \begin_inset Quotes erd
3192 \end_inset
3193
3194  tests.
3195  If the export actually succeeds, then the test will fail.
3196  The purpose of this failure is to get your attention—something has changed,
3197  possibly for the better.
3198 \end_layout
3199
3200 \begin_layout Standard
3201 We try to document why a test is inverted or ignored.
3202  See the comment (prefixed with
3203 \begin_inset Flex Code
3204 status collapsed
3205
3206 \begin_layout Plain Layout
3207 #
3208 \end_layout
3209
3210 \end_inset
3211
3212 ) above the block in which the test is listed as inverted or ignored in
3213  the files
3214 \begin_inset Flex Code
3215 status collapsed
3216
3217 \begin_layout Plain Layout
3218 development/autotests/invertedTests
3219 \end_layout
3220
3221 \end_inset
3222
3223 ,
3224 \begin_inset Flex Code
3225 status collapsed
3226
3227 \begin_layout Plain Layout
3228 development/autotests/unreliableTests
3229 \end_layout
3230
3231 \end_inset
3232
3233  and
3234 \begin_inset Flex Code
3235 status collapsed
3236
3237 \begin_layout Plain Layout
3238 development/autotests/ignoredTests
3239 \end_layout
3240
3241 \end_inset
3242
3243 .
3244
3245 \end_layout
3246
3247 \begin_layout Standard
3248 A good question is why do we enable the tests for non-default formats? The
3249  answer is that if a non-default route is broken it is often because a bug
3250  was introduced in LyX and not because a document-specific change was made
3251  that is not supported by the route.
3252  In other words, there is a high signal/noise ratio in the export tests
3253  for some non-default formats.
3254
3255 \end_layout
3256
3257 \begin_layout Standard
3258 When a test or several tests fail, consider checking the files in the
3259 \begin_inset Flex Code
3260 status collapsed
3261
3262 \begin_layout Plain Layout
3263 Testing/Temporary/
3264 \end_layout
3265
3266 \end_inset
3267
3268  subdirectory of your build directory.
3269  In this subdirectory are three files: the file
3270 \begin_inset Flex Code
3271 status collapsed
3272
3273 \begin_layout Plain Layout
3274 LastTestsFailed.log
3275 \end_layout
3276
3277 \end_inset
3278
3279  simply lists the tests that failed on your last
3280 \begin_inset Flex Code
3281 status collapsed
3282
3283 \begin_layout Plain Layout
3284 ctest
3285 \end_layout
3286
3287 \end_inset
3288
3289  command; the
3290 \begin_inset Flex Code
3291 status collapsed
3292
3293 \begin_layout Plain Layout
3294 LastTest.log
3295 \end_layout
3296
3297 \end_inset
3298
3299  file contains the output from the tests (and often has details explaining
3300  why a test failed); and the
3301 \begin_inset Flex Code
3302 status collapsed
3303
3304 \begin_layout Plain Layout
3305 CTestCostData.txt
3306 \end_layout
3307
3308 \end_inset
3309
3310  file lists the times that it took to run the tests.
3311 \end_layout
3312
3313 \begin_layout Paragraph
3314 What action should you take if a test fails?
3315 \end_layout
3316
3317 \begin_layout Standard
3318 \paragraph_spacing single
3319 It is always good to check manually why something fails and if it passes
3320  if the PDF output is good.
3321 \end_layout
3322
3323 \begin_layout Itemize
3324 Generally, if a change breaks compilation for the target format (for the
3325  manuals pdf2) without solving some important other issue,
3326 \emph on
3327 fix or revert the commit
3328 \emph default
3329  that led to failure.
3330 \end_layout
3331
3332 \begin_layout Itemize
3333 If it is not possible to (immediately) fix the failure but there are reasons
3334  not to revert the commit (e.g.
3335  it fixes another more important issue),
3336 \emph on
3337 invert
3338 \emph default
3339  the failing test case (see
3340 \begin_inset CommandInset ref
3341 LatexCommand ref
3342 reference "par:Inverted-tests"
3343
3344 \end_inset
3345
3346 ).
3347 \end_layout
3348
3349 \begin_layout Itemize
3350 If an
3351 \emph on
3352 inverted
3353 \emph default
3354  test case fails because the export now works,
3355 \emph on
3356 uninvert
3357 \emph default
3358  the test by removing the pattern from the
3359 \begin_inset Quotes eld
3360 \end_inset
3361
3362 invertedTests
3363 \begin_inset Quotes erd
3364 \end_inset
3365
3366  file) (see
3367 \begin_inset CommandInset ref
3368 LatexCommand ref
3369 reference "par:Inverted-tests"
3370
3371 \end_inset
3372
3373 ).
3374 \end_layout
3375
3376 \begin_layout Itemize
3377 If the export did not fail previously but led to wrong output (PDF, say),
3378 \begin_inset Foot
3379 status collapsed
3380
3381 \begin_layout Plain Layout
3382 Non-failing test with wrong output should be labeledas
3383 \begin_inset Quotes eld
3384 \end_inset
3385
3386 unreliable:wrong_output
3387 \begin_inset Quotes erd
3388 \end_inset
3389
3390  (
3391 \begin_inset CommandInset ref
3392 LatexCommand ref
3393 reference "par:Unreliable-tests"
3394
3395 \end_inset
3396
3397 ).
3398 \end_layout
3399
3400 \end_inset
3401
3402  it is in fact an improvement when the test now fails.
3403
3404 \emph on
3405 Invert
3406 \emph default
3407  the failing test case (see
3408 \begin_inset CommandInset ref
3409 LatexCommand ref
3410 reference "par:Inverted-tests"
3411
3412 \end_inset
3413
3414 ).
3415 \end_layout
3416
3417 \begin_layout Itemize
3418 In case of tests failing due to missing requirements (tests labeled
3419 \begin_inset Quotes eld
3420 \end_inset
3421
3422 unreliable:nonstandard
3423 \begin_inset Quotes erd
3424 \end_inset
3425
3426  or testing on a system with only a subset of TeXLive installed), ignore
3427  the failure, ask for someone else to run the test, or install the missing
3428  resources and try again.
3429 \end_layout
3430
3431 \begin_layout Itemize
3432 Check the log file Testing/Temporary/LastTest.log.
3433  In case of latex-errors rerun the failing test with environment variable
3434  'LAX_DEBUG_LATEX' set to '1'.
3435  This will include latex messages in LastTest.log, so it should be easier
3436  to interpret the fail-reason.
3437 \end_layout
3438
3439 \begin_layout Paragraph
3440 \begin_inset CommandInset label
3441 LatexCommand label
3442 name "par:Inverted-tests"
3443
3444 \end_inset
3445
3446 Inverted tests
3447 \end_layout
3448
3449 \begin_layout Standard
3450 Test cases whose name matches a pattern in the file
3451 \begin_inset Flex Code
3452 status collapsed
3453
3454 \begin_layout Plain Layout
3455 development/autotests/invertedTests
3456 \end_layout
3457
3458 \end_inset
3459
3460  get the label
3461 \emph on
3462 inverted
3463 \emph default
3464 .
3465  They get also the test property
3466 \begin_inset Flex Code
3467 status collapsed
3468
3469 \begin_layout Plain Layout
3470 WILL_FAIL
3471 \end_layout
3472
3473 \end_inset
3474
3475 , i.e.
3476  they are reported as failing if the export works without error
3477 \begin_inset Flex URL
3478 status collapsed
3479
3480 \begin_layout Plain Layout
3481
3482 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3483 \end_layout
3484
3485 \end_inset
3486
3487 .
3488 \end_layout
3489
3490 \begin_layout Standard
3491 Add failing cases to this file, if they cannot be solved
3492 \begin_inset Quotes eld
3493 \end_inset
3494
3495 immediately
3496 \begin_inset Quotes erd
3497 \end_inset
3498
3499  but it is expected that the export will work in a foreseeable future, e.g.
3500  low priority issues like failures to export to a non-target format (for
3501  the manuals everything except pdf2).
3502 \end_layout
3503
3504 \begin_layout Standard
3505 The following sublabels are currently present in
3506 \begin_inset Flex Code
3507 status collapsed
3508
3509 \begin_layout Plain Layout
3510 invertedTests
3511 \end_layout
3512
3513 \end_inset
3514
3515 :
3516 \end_layout
3517
3518 \begin_layout Description
3519 todo test failures that require attention:
3520 \end_layout
3521
3522 \begin_deeper
3523 \begin_layout Itemize
3524 minor issues to explore and properly sort later,
3525 \end_layout
3526
3527 \begin_layout Itemize
3528 easyfix issues,
3529 \end_layout
3530
3531 \begin_layout Itemize
3532 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3533 \end_layout
3534
3535 \end_deeper
3536 \begin_layout Description
3537 lyxbugs LyX bugs with a Trac number.
3538 \end_layout
3539
3540 \begin_layout Description
3541 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3542 \end_layout
3543
3544 \begin_deeper
3545 \begin_layout Standard
3546 "Wontfix" if demonstrating correct use and OK in the default output format.
3547 \end_layout
3548
3549 \end_deeper
3550 \begin_layout Description
3551 texissues Export fails due to LaTeX limitations like non-ASCII characters
3552  in verbatim or listings, incompatible packages, ...
3553 \end_layout
3554
3555 \begin_deeper
3556 \begin_layout Standard
3557 "Wontfix" if documents demonstrate correct use in the default output format:
3558 \end_layout
3559
3560 \begin_layout Itemize
3561 If the source can be made more robust without becoming "hackish", fix the
3562  source,
3563 \end_layout
3564
3565 \begin_layout Itemize
3566 if LyX could be enhanced to care for a permanent TeX limitation, file a
3567  ticket at trac and add a pattern under lyxbugs,
3568 \end_layout
3569
3570 \begin_layout Itemize
3571 otherwise, add a pattern here.
3572 \end_layout
3573
3574 \end_deeper
3575 \begin_layout Description
3576 attic Documents in the attic (kept for reference and format conversion test).
3577  Usually
3578 \begin_inset Quotes eld
3579 \end_inset
3580
3581 Wontfix
3582 \begin_inset Quotes erd
3583 \end_inset
3584
3585 .
3586 \end_layout
3587
3588 \begin_layout Subparagraph
3589 suspended tests
3590 \end_layout
3591
3592 \begin_layout Standard
3593 Test cases whose name additionally matches a pattern in the file
3594 \begin_inset Flex Code
3595 status collapsed
3596
3597 \begin_layout Plain Layout
3598 development/autotests/suspendedTests
3599 \end_layout
3600
3601 \end_inset
3602
3603  get the label
3604 \emph on
3605 suspended
3606 \emph default
3607 (instead of
3608 \emph on
3609 export
3610 \emph default
3611 and
3612 \emph on
3613  inverted
3614 \emph default
3615 ).
3616  This means they are not executed using
3617 \begin_inset Flex Code
3618 status collapsed
3619
3620 \begin_layout Plain Layout
3621 ctest -L export
3622 \end_layout
3623
3624 \end_inset
3625
3626  or
3627 \begin_inset Flex Code
3628 status collapsed
3629
3630 \begin_layout Plain Layout
3631 ctest -L inverted
3632 \end_layout
3633
3634 \end_inset
3635
3636 .
3637  However, they also get the test property
3638 \begin_inset Flex Code
3639 status collapsed
3640
3641 \begin_layout Plain Layout
3642 WILL_FAIL
3643 \end_layout
3644
3645 \end_inset
3646
3647 , i.e.
3648  they are reported as failing if the export works without error.
3649  From time to time they still have to be checked using
3650 \begin_inset Flex Code
3651 status collapsed
3652
3653 \begin_layout Plain Layout
3654 ctest -L suspended
3655 \end_layout
3656
3657 \end_inset
3658
3659 .
3660 \end_layout
3661
3662 \begin_layout Standard
3663 These tests are suspended, because the export fails for known reasons which
3664  cannot ATM be resolved.
3665  But it is expected the reason might disappear in the future.
3666  Be it new TL or better handling in \SpecialChar LyX
3667 .
3668 \end_layout
3669
3670 \begin_layout Standard
3671 For ctest commands without the
3672 \begin_inset Flex Code
3673 status collapsed
3674
3675 \begin_layout Plain Layout
3676 -L
3677 \end_layout
3678
3679 \end_inset
3680
3681  parameter nothing changes.
3682  Suspended or not, tests will be executed depending only on the selecting
3683  regular expression given to the ctest command (see
3684 \begin_inset CommandInset ref
3685 LatexCommand ref
3686 reference "par:ctest-options"
3687
3688 \end_inset
3689
3690 ).
3691 \end_layout
3692
3693 \begin_layout Paragraph
3694 \begin_inset CommandInset label
3695 LatexCommand label
3696 name "par:Unreliable-tests"
3697
3698 \end_inset
3699
3700 Unreliable tests
3701 \end_layout
3702
3703 \begin_layout Standard
3704 Test cases whose name matches a pattern in the file
3705 \begin_inset Flex Code
3706 status collapsed
3707
3708 \begin_layout Plain Layout
3709 development/autotests/unreliableTests
3710 \end_layout
3711
3712 \end_inset
3713
3714  get the label
3715 \emph on
3716 unreliable
3717 \emph default
3718 .
3719 \end_layout
3720
3721 \begin_layout Standard
3722 These tests are not executed using
3723 \begin_inset Flex Code
3724 status collapsed
3725
3726 \begin_layout Plain Layout
3727 ctest -L export
3728 \end_layout
3729
3730 \end_inset
3731
3732  or
3733 \begin_inset Flex Code
3734 status collapsed
3735
3736 \begin_layout Plain Layout
3737 ctest -L inverted
3738 \end_layout
3739
3740 \end_inset
3741
3742 .
3743
3744 \end_layout
3745
3746 \begin_layout Standard
3747 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3748  or pass but should rather fail (wrong output).
3749
3750 \begin_inset Note Note
3751 status collapsed
3752
3753 \begin_layout Plain Layout
3754 *invalid* tests (wrong output) are not *unreliable*.
3755  # Use "unfit" or "unapplicable" as better label and name of pattern file?
3756
3757 \end_layout
3758
3759 \end_inset
3760
3761
3762 \end_layout
3763
3764 \begin_layout Standard
3765 The following sublabels are currently present in
3766 \begin_inset Flex Code
3767 status collapsed
3768
3769 \begin_layout Plain Layout
3770 unreliableTests
3771 \end_layout
3772
3773 \end_inset
3774
3775 :
3776 \end_layout
3777
3778 \begin_layout Description
3779 nonstandard Documents with additional requirements, e.g.
3780  a class or package file not in TeXLive.
3781
3782 \begin_inset Note Note
3783 status open
3784
3785 \begin_layout Plain Layout
3786 TODO: rename to
3787 \begin_inset Quotes eld
3788 \end_inset
3789
3790 extra
3791 \begin_inset Quotes erd
3792 \end_inset
3793
3794  or
3795 \begin_inset Quotes eld
3796 \end_inset
3797
3798 exotic
3799 \begin_inset Quotes erd
3800 \end_inset
3801
3802 ?
3803 \end_layout
3804
3805 \end_inset
3806
3807
3808 \end_layout
3809
3810 \begin_layout Description
3811 erratic Tests depending on local configuration or the phase of the moon.
3812
3813 \end_layout
3814
3815 \begin_layout Description
3816 varying_versions Test depending on TeX distribution, package versions or
3817  OS.
3818 \end_layout
3819
3820 \begin_layout Description
3821 wrong
3822 \begin_inset space ~
3823 \end_inset
3824
3825 output Export does not fail but the resulting document has (undetected)
3826  errors.
3827 \end_layout
3828
3829 \begin_deeper
3830 \begin_layout Standard
3831 \paragraph_spacing single
3832 \begin_inset Note Note
3833 status open
3834
3835 \begin_layout Plain Layout
3836 \paragraph_spacing single
3837 These tests are in a strict sense not unreliable but
3838 \emph on
3839 invalid
3840 \emph default
3841  (not measuring what they should measure).
3842 \end_layout
3843
3844 \end_inset
3845
3846
3847 \end_layout
3848
3849 \end_deeper
3850 \begin_layout Paragraph
3851 \begin_inset CommandInset label
3852 LatexCommand label
3853 name "par:Export-test-filtering"
3854
3855 \end_inset
3856
3857 Export test filtering
3858 \end_layout
3859
3860 \begin_layout Standard
3861 The assignment of a label to a test is controlled by a set of files with
3862  regular expressions that are matched against the test names.
3863 \end_layout
3864
3865 \begin_layout Description
3866 ignoredTests (small file)
3867 \begin_inset Newline newline
3868 \end_inset
3869
3870 Tests selected here are withdrawn in the configuration step (cf.
3871
3872 \begin_inset CommandInset ref
3873 LatexCommand ref
3874 reference "par:Configuring-ctests"
3875
3876 \end_inset
3877
3878 ).
3879 \end_layout
3880
3881 \begin_deeper
3882 \begin_layout Labeling
3883 \labelwidthstring 00.00.0000
3884 Input Test of any export combination
3885 \end_layout
3886
3887 \begin_layout Labeling
3888 \labelwidthstring 00.00.0000
3889 Output Stop if tests not selected here
3890 \end_layout
3891
3892 \end_deeper
3893 \begin_layout Description
3894 unreliableTests: Tests selected pass or fail dependent on the system where
3895  the test is run.
3896  Selected tests gain the label 'unreliable'.
3897 \end_layout
3898
3899 \begin_deeper
3900 \begin_layout Labeling
3901 \labelwidthstring 00.00.0000
3902 Input Each test which passed 'ignoredTests'
3903 \end_layout
3904
3905 \begin_layout Labeling
3906 \labelwidthstring 00.00.0000
3907 Output Stop if test selected, gain label 'unreliable'.
3908 \end_layout
3909
3910 \end_deeper
3911 \begin_layout Description
3912 invertedTests
3913 \begin_inset space \space{}
3914 \end_inset
3915
3916
3917 \end_layout
3918
3919 \begin_deeper
3920 \begin_layout Labeling
3921 \labelwidthstring 00.00.0000
3922 Input Each test which passed 'unreliableTests'
3923 \end_layout
3924
3925 \begin_layout Labeling
3926 \labelwidthstring 00.00.0000
3927 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3928  tests are reported as failing if the export works without error.) If no
3929  subselection applies, gain labels 'export' and 'inverted'.
3930 \end_layout
3931
3932 \begin_layout Standard
3933 The following filter perfoms a subselection of 'invertedTests':
3934 \end_layout
3935
3936 \begin_layout Description
3937 suspendedTests Tests selected here gain the label 'suspended' but _not_
3938  'export' or 'inverted', although in ctest they remain inverted.
3939  ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3940 \end_layout
3941
3942 \begin_deeper
3943 \begin_layout Labeling
3944 \labelwidthstring 00.00.0000
3945 Input Each test selected by 'invertedTests'
3946 \end_layout
3947
3948 \begin_layout Labeling
3949 \labelwidthstring 00.00.0000
3950 Output Selected test gains label 'suspended'.
3951
3952 \end_layout
3953
3954 \end_deeper
3955 \end_deeper
3956 \begin_layout Standard
3957 The following table may clarify label assignement
3958 \end_layout
3959
3960 \begin_layout Standard
3961 \begin_inset Tabular
3962 <lyxtabular version="3" rows="7" columns="9">
3963 <features tabularvalignment="middle">
3964 <column alignment="left" valignment="top" width="0pt">
3965 <column alignment="left" valignment="top" width="0pt">
3966 <column alignment="left" valignment="top" width="0pt">
3967 <column alignment="left" valignment="top" width="0pt">
3968 <column alignment="center" valignment="top">
3969 <column alignment="center" valignment="top">
3970 <column alignment="center" valignment="top">
3971 <column alignment="center" valignment="top">
3972 <column alignment="center" valignment="top">
3973 <row>
3974 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3975 \begin_inset Text
3976
3977 \begin_layout Plain Layout
3978 Test matching pattern in file:
3979 \end_layout
3980
3981 \end_inset
3982 </cell>
3983 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3984 \begin_inset Text
3985
3986 \begin_layout Plain Layout
3987
3988 \end_layout
3989
3990 \end_inset
3991 </cell>
3992 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3993 \begin_inset Text
3994
3995 \begin_layout Plain Layout
3996
3997 \end_layout
3998
3999 \end_inset
4000 </cell>
4001 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4002 \begin_inset Text
4003
4004 \begin_layout Plain Layout
4005
4006 \end_layout
4007
4008 \end_inset
4009 </cell>
4010 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4011 \begin_inset Text
4012
4013 \begin_layout Plain Layout
4014 Assigned label
4015 \end_layout
4016
4017 \end_inset
4018 </cell>
4019 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4020 \begin_inset Text
4021
4022 \begin_layout Plain Layout
4023
4024 \end_layout
4025
4026 \end_inset
4027 </cell>
4028 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4029 \begin_inset Text
4030
4031 \begin_layout Plain Layout
4032
4033 \end_layout
4034
4035 \end_inset
4036 </cell>
4037 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4038 \begin_inset Text
4039
4040 \begin_layout Plain Layout
4041
4042 \end_layout
4043
4044 \end_inset
4045 </cell>
4046 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4047 \begin_inset Text
4048
4049 \begin_layout Plain Layout
4050 test property
4051 \end_layout
4052
4053 \end_inset
4054 </cell>
4055 </row>
4056 <row>
4057 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4058 \begin_inset Text
4059
4060 \begin_layout Plain Layout
4061 ignoredTests
4062 \end_layout
4063
4064 \end_inset
4065 </cell>
4066 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4067 \begin_inset Text
4068
4069 \begin_layout Plain Layout
4070 unreliableTests
4071 \end_layout
4072
4073 \end_inset
4074 </cell>
4075 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4076 \begin_inset Text
4077
4078 \begin_layout Plain Layout
4079 invertedTests
4080 \end_layout
4081
4082 \end_inset
4083 </cell>
4084 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4085 \begin_inset Text
4086
4087 \begin_layout Plain Layout
4088 suspendedTests
4089 \end_layout
4090
4091 \end_inset
4092 </cell>
4093 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4094 \begin_inset Text
4095
4096 \begin_layout Plain Layout
4097 export
4098 \end_layout
4099
4100 \end_inset
4101 </cell>
4102 <cell alignment="center" valignment="top" topline="true" usebox="none">
4103 \begin_inset Text
4104
4105 \begin_layout Plain Layout
4106 unreliable
4107 \end_layout
4108
4109 \end_inset
4110 </cell>
4111 <cell alignment="center" valignment="top" topline="true" usebox="none">
4112 \begin_inset Text
4113
4114 \begin_layout Plain Layout
4115 inverted
4116 \end_layout
4117
4118 \end_inset
4119 </cell>
4120 <cell alignment="center" valignment="top" topline="true" usebox="none">
4121 \begin_inset Text
4122
4123 \begin_layout Plain Layout
4124 suspended
4125 \end_layout
4126
4127 \end_inset
4128 </cell>
4129 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4130 \begin_inset Text
4131
4132 \begin_layout Plain Layout
4133
4134 \end_layout
4135
4136 \end_inset
4137 </cell>
4138 </row>
4139 <row>
4140 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4141 \begin_inset Text
4142
4143 \begin_layout Plain Layout
4144 Yes
4145 \end_layout
4146
4147 \end_inset
4148 </cell>
4149 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4150 \begin_inset Text
4151
4152 \begin_layout Plain Layout
4153 -
4154 \end_layout
4155
4156 \end_inset
4157 </cell>
4158 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4159 \begin_inset Text
4160
4161 \begin_layout Plain Layout
4162 -
4163 \end_layout
4164
4165 \end_inset
4166 </cell>
4167 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4168 \begin_inset Text
4169
4170 \begin_layout Plain Layout
4171 -
4172 \end_layout
4173
4174 \end_inset
4175 </cell>
4176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4177 \begin_inset Text
4178
4179 \begin_layout Plain Layout
4180 -
4181 \end_layout
4182
4183 \end_inset
4184 </cell>
4185 <cell alignment="center" valignment="top" topline="true" usebox="none">
4186 \begin_inset Text
4187
4188 \begin_layout Plain Layout
4189
4190 \end_layout
4191
4192 \end_inset
4193 </cell>
4194 <cell alignment="center" valignment="top" topline="true" usebox="none">
4195 \begin_inset Text
4196
4197 \begin_layout Plain Layout
4198 -
4199 \end_layout
4200
4201 \end_inset
4202 </cell>
4203 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4204 \begin_inset Text
4205
4206 \begin_layout Plain Layout
4207 -
4208 \end_layout
4209
4210 \end_inset
4211 </cell>
4212 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4213 \begin_inset Text
4214
4215 \begin_layout Plain Layout
4216
4217 \end_layout
4218
4219 \end_inset
4220 </cell>
4221 </row>
4222 <row>
4223 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4224 \begin_inset Text
4225
4226 \begin_layout Plain Layout
4227 No
4228 \end_layout
4229
4230 \end_inset
4231 </cell>
4232 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4233 \begin_inset Text
4234
4235 \begin_layout Plain Layout
4236 Yes
4237 \end_layout
4238
4239 \end_inset
4240 </cell>
4241 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4242 \begin_inset Text
4243
4244 \begin_layout Plain Layout
4245 -
4246 \end_layout
4247
4248 \end_inset
4249 </cell>
4250 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4251 \begin_inset Text
4252
4253 \begin_layout Plain Layout
4254 -
4255 \end_layout
4256
4257 \end_inset
4258 </cell>
4259 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4260 \begin_inset Text
4261
4262 \begin_layout Plain Layout
4263 -
4264 \end_layout
4265
4266 \end_inset
4267 </cell>
4268 <cell alignment="center" valignment="top" topline="true" usebox="none">
4269 \begin_inset Text
4270
4271 \begin_layout Plain Layout
4272 +
4273 \end_layout
4274
4275 \end_inset
4276 </cell>
4277 <cell alignment="center" valignment="top" topline="true" usebox="none">
4278 \begin_inset Text
4279
4280 \begin_layout Plain Layout
4281 -
4282 \end_layout
4283
4284 \end_inset
4285 </cell>
4286 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4287 \begin_inset Text
4288
4289 \begin_layout Plain Layout
4290 -
4291 \end_layout
4292
4293 \end_inset
4294 </cell>
4295 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4296 \begin_inset Text
4297
4298 \begin_layout Plain Layout
4299
4300 \end_layout
4301
4302 \end_inset
4303 </cell>
4304 </row>
4305 <row>
4306 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4307 \begin_inset Text
4308
4309 \begin_layout Plain Layout
4310
4311 \end_layout
4312
4313 \end_inset
4314 </cell>
4315 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4316 \begin_inset Text
4317
4318 \begin_layout Plain Layout
4319 No
4320 \end_layout
4321
4322 \end_inset
4323 </cell>
4324 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4325 \begin_inset Text
4326
4327 \begin_layout Plain Layout
4328 Yes
4329 \end_layout
4330
4331 \end_inset
4332 </cell>
4333 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4334 \begin_inset Text
4335
4336 \begin_layout Plain Layout
4337 Yes
4338 \end_layout
4339
4340 \end_inset
4341 </cell>
4342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4343 \begin_inset Text
4344
4345 \begin_layout Plain Layout
4346 -
4347 \end_layout
4348
4349 \end_inset
4350 </cell>
4351 <cell alignment="center" valignment="top" topline="true" usebox="none">
4352 \begin_inset Text
4353
4354 \begin_layout Plain Layout
4355 -
4356 \end_layout
4357
4358 \end_inset
4359 </cell>
4360 <cell alignment="center" valignment="top" topline="true" usebox="none">
4361 \begin_inset Text
4362
4363 \begin_layout Plain Layout
4364 -
4365 \end_layout
4366
4367 \end_inset
4368 </cell>
4369 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4370 \begin_inset Text
4371
4372 \begin_layout Plain Layout
4373 +
4374 \end_layout
4375
4376 \end_inset
4377 </cell>
4378 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4379 \begin_inset Text
4380
4381 \begin_layout Plain Layout
4382 WILL_FAIL
4383 \end_layout
4384
4385 \end_inset
4386 </cell>
4387 </row>
4388 <row>
4389 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4390 \begin_inset Text
4391
4392 \begin_layout Plain Layout
4393
4394 \end_layout
4395
4396 \end_inset
4397 </cell>
4398 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4399 \begin_inset Text
4400
4401 \begin_layout Plain Layout
4402
4403 \end_layout
4404
4405 \end_inset
4406 </cell>
4407 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4408 \begin_inset Text
4409
4410 \begin_layout Plain Layout
4411
4412 \end_layout
4413
4414 \end_inset
4415 </cell>
4416 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4417 \begin_inset Text
4418
4419 \begin_layout Plain Layout
4420 No
4421 \end_layout
4422
4423 \end_inset
4424 </cell>
4425 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4426 \begin_inset Text
4427
4428 \begin_layout Plain Layout
4429 +
4430 \end_layout
4431
4432 \end_inset
4433 </cell>
4434 <cell alignment="center" valignment="top" topline="true" usebox="none">
4435 \begin_inset Text
4436
4437 \begin_layout Plain Layout
4438 -
4439 \end_layout
4440
4441 \end_inset
4442 </cell>
4443 <cell alignment="center" valignment="top" topline="true" usebox="none">
4444 \begin_inset Text
4445
4446 \begin_layout Plain Layout
4447 +
4448 \end_layout
4449
4450 \end_inset
4451 </cell>
4452 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4453 \begin_inset Text
4454
4455 \begin_layout Plain Layout
4456 -
4457 \end_layout
4458
4459 \end_inset
4460 </cell>
4461 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4462 \begin_inset Text
4463
4464 \begin_layout Plain Layout
4465 WILL_FAIL
4466 \end_layout
4467
4468 \end_inset
4469 </cell>
4470 </row>
4471 <row>
4472 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4473 \begin_inset Text
4474
4475 \begin_layout Plain Layout
4476
4477 \end_layout
4478
4479 \end_inset
4480 </cell>
4481 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4482 \begin_inset Text
4483
4484 \begin_layout Plain Layout
4485
4486 \end_layout
4487
4488 \end_inset
4489 </cell>
4490 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4491 \begin_inset Text
4492
4493 \begin_layout Plain Layout
4494 No
4495 \end_layout
4496
4497 \end_inset
4498 </cell>
4499 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4500 \begin_inset Text
4501
4502 \begin_layout Plain Layout
4503 -
4504 \end_layout
4505
4506 \end_inset
4507 </cell>
4508 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4509 \begin_inset Text
4510
4511 \begin_layout Plain Layout
4512 +
4513 \end_layout
4514
4515 \end_inset
4516 </cell>
4517 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4518 \begin_inset Text
4519
4520 \begin_layout Plain Layout
4521 -
4522 \end_layout
4523
4524 \end_inset
4525 </cell>
4526 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4527 \begin_inset Text
4528
4529 \begin_layout Plain Layout
4530 -
4531 \end_layout
4532
4533 \end_inset
4534 </cell>
4535 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4536 \begin_inset Text
4537
4538 \begin_layout Plain Layout
4539 -
4540 \end_layout
4541
4542 \end_inset
4543 </cell>
4544 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4545 \begin_inset Text
4546
4547 \begin_layout Plain Layout
4548
4549 \end_layout
4550
4551 \end_inset
4552 </cell>
4553 </row>
4554 </lyxtabular>
4555
4556 \end_inset
4557
4558
4559 \end_layout
4560
4561 \begin_layout Standard
4562 \begin_inset Note Note
4563 status open
4564
4565 \begin_layout Plain Layout
4566 Without the
4567 \begin_inset Quotes eld
4568 \end_inset
4569
4570 suspendedTests
4571 \begin_inset Quotes erd
4572 \end_inset
4573
4574  filter, this would be far less complicated:
4575 \end_layout
4576
4577 \begin_layout Plain Layout
4578 \begin_inset Tabular
4579 <lyxtabular version="3" rows="6" columns="7">
4580 <features tabularvalignment="middle">
4581 <column alignment="left" valignment="top" width="0pt">
4582 <column alignment="left" valignment="top" width="0pt">
4583 <column alignment="left" valignment="top" width="0pt">
4584 <column alignment="center" valignment="top">
4585 <column alignment="center" valignment="top">
4586 <column alignment="center" valignment="top">
4587 <column alignment="center" valignment="top">
4588 <row>
4589 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4590 \begin_inset Text
4591
4592 \begin_layout Plain Layout
4593 Test matching pattern in file:
4594 \end_layout
4595
4596 \end_inset
4597 </cell>
4598 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4599 \begin_inset Text
4600
4601 \begin_layout Plain Layout
4602
4603 \end_layout
4604
4605 \end_inset
4606 </cell>
4607 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4608 \begin_inset Text
4609
4610 \begin_layout Plain Layout
4611
4612 \end_layout
4613
4614 \end_inset
4615 </cell>
4616 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4617 \begin_inset Text
4618
4619 \begin_layout Plain Layout
4620 Label
4621 \end_layout
4622
4623 \end_inset
4624 </cell>
4625 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4626 \begin_inset Text
4627
4628 \begin_layout Plain Layout
4629
4630 \end_layout
4631
4632 \end_inset
4633 </cell>
4634 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4635 \begin_inset Text
4636
4637 \begin_layout Plain Layout
4638
4639 \end_layout
4640
4641 \end_inset
4642 </cell>
4643 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4644 \begin_inset Text
4645
4646 \begin_layout Plain Layout
4647 test property
4648 \end_layout
4649
4650 \end_inset
4651 </cell>
4652 </row>
4653 <row>
4654 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4655 \begin_inset Text
4656
4657 \begin_layout Plain Layout
4658 ignoredTests
4659 \end_layout
4660
4661 \end_inset
4662 </cell>
4663 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4664 \begin_inset Text
4665
4666 \begin_layout Plain Layout
4667 unreliableTests
4668 \end_layout
4669
4670 \end_inset
4671 </cell>
4672 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4673 \begin_inset Text
4674
4675 \begin_layout Plain Layout
4676 invertedTests
4677 \end_layout
4678
4679 \end_inset
4680 </cell>
4681 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4682 \begin_inset Text
4683
4684 \begin_layout Plain Layout
4685 export
4686 \end_layout
4687
4688 \end_inset
4689 </cell>
4690 <cell alignment="center" valignment="top" topline="true" usebox="none">
4691 \begin_inset Text
4692
4693 \begin_layout Plain Layout
4694 unreliable
4695 \end_layout
4696
4697 \end_inset
4698 </cell>
4699 <cell alignment="center" valignment="top" topline="true" usebox="none">
4700 \begin_inset Text
4701
4702 \begin_layout Plain Layout
4703 inverted
4704 \end_layout
4705
4706 \end_inset
4707 </cell>
4708 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4709 \begin_inset Text
4710
4711 \begin_layout Plain Layout
4712
4713 \end_layout
4714
4715 \end_inset
4716 </cell>
4717 </row>
4718 <row>
4719 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4720 \begin_inset Text
4721
4722 \begin_layout Plain Layout
4723 Yes
4724 \end_layout
4725
4726 \end_inset
4727 </cell>
4728 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4729 \begin_inset Text
4730
4731 \begin_layout Plain Layout
4732 -
4733 \end_layout
4734
4735 \end_inset
4736 </cell>
4737 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4738 \begin_inset Text
4739
4740 \begin_layout Plain Layout
4741 -
4742 \end_layout
4743
4744 \end_inset
4745 </cell>
4746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4747 \begin_inset Text
4748
4749 \begin_layout Plain Layout
4750 -
4751 \end_layout
4752
4753 \end_inset
4754 </cell>
4755 <cell alignment="center" valignment="top" topline="true" usebox="none">
4756 \begin_inset Text
4757
4758 \begin_layout Plain Layout
4759
4760 \end_layout
4761
4762 \end_inset
4763 </cell>
4764 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4765 \begin_inset Text
4766
4767 \begin_layout Plain Layout
4768 -
4769 \end_layout
4770
4771 \end_inset
4772 </cell>
4773 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4774 \begin_inset Text
4775
4776 \begin_layout Plain Layout
4777
4778 \end_layout
4779
4780 \end_inset
4781 </cell>
4782 </row>
4783 <row>
4784 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4785 \begin_inset Text
4786
4787 \begin_layout Plain Layout
4788 No
4789 \end_layout
4790
4791 \end_inset
4792 </cell>
4793 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4794 \begin_inset Text
4795
4796 \begin_layout Plain Layout
4797 Yes
4798 \end_layout
4799
4800 \end_inset
4801 </cell>
4802 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4803 \begin_inset Text
4804
4805 \begin_layout Plain Layout
4806 -
4807 \end_layout
4808
4809 \end_inset
4810 </cell>
4811 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4812 \begin_inset Text
4813
4814 \begin_layout Plain Layout
4815 -
4816 \end_layout
4817
4818 \end_inset
4819 </cell>
4820 <cell alignment="center" valignment="top" topline="true" usebox="none">
4821 \begin_inset Text
4822
4823 \begin_layout Plain Layout
4824 +
4825 \end_layout
4826
4827 \end_inset
4828 </cell>
4829 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4830 \begin_inset Text
4831
4832 \begin_layout Plain Layout
4833 -
4834 \end_layout
4835
4836 \end_inset
4837 </cell>
4838 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4839 \begin_inset Text
4840
4841 \begin_layout Plain Layout
4842
4843 \end_layout
4844
4845 \end_inset
4846 </cell>
4847 </row>
4848 <row>
4849 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4850 \begin_inset Text
4851
4852 \begin_layout Plain Layout
4853
4854 \end_layout
4855
4856 \end_inset
4857 </cell>
4858 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4859 \begin_inset Text
4860
4861 \begin_layout Plain Layout
4862 No
4863 \end_layout
4864
4865 \end_inset
4866 </cell>
4867 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4868 \begin_inset Text
4869
4870 \begin_layout Plain Layout
4871 Yes
4872 \end_layout
4873
4874 \end_inset
4875 </cell>
4876 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4877 \begin_inset Text
4878
4879 \begin_layout Plain Layout
4880 +
4881 \end_layout
4882
4883 \end_inset
4884 </cell>
4885 <cell alignment="center" valignment="top" topline="true" usebox="none">
4886 \begin_inset Text
4887
4888 \begin_layout Plain Layout
4889 -
4890 \end_layout
4891
4892 \end_inset
4893 </cell>
4894 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4895 \begin_inset Text
4896
4897 \begin_layout Plain Layout
4898 +
4899 \end_layout
4900
4901 \end_inset
4902 </cell>
4903 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4904 \begin_inset Text
4905
4906 \begin_layout Plain Layout
4907 WILL_FAIL
4908 \end_layout
4909
4910 \end_inset
4911 </cell>
4912 </row>
4913 <row>
4914 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4915 \begin_inset Text
4916
4917 \begin_layout Plain Layout
4918
4919 \end_layout
4920
4921 \end_inset
4922 </cell>
4923 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4924 \begin_inset Text
4925
4926 \begin_layout Plain Layout
4927
4928 \end_layout
4929
4930 \end_inset
4931 </cell>
4932 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4933 \begin_inset Text
4934
4935 \begin_layout Plain Layout
4936 No
4937 \end_layout
4938
4939 \end_inset
4940 </cell>
4941 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4942 \begin_inset Text
4943
4944 \begin_layout Plain Layout
4945 +
4946 \end_layout
4947
4948 \end_inset
4949 </cell>
4950 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4951 \begin_inset Text
4952
4953 \begin_layout Plain Layout
4954 -
4955 \end_layout
4956
4957 \end_inset
4958 </cell>
4959 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4960 \begin_inset Text
4961
4962 \begin_layout Plain Layout
4963 -
4964 \end_layout
4965
4966 \end_inset
4967 </cell>
4968 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4969 \begin_inset Text
4970
4971 \begin_layout Plain Layout
4972
4973 \end_layout
4974
4975 \end_inset
4976 </cell>
4977 </row>
4978 </lyxtabular>
4979
4980 \end_inset
4981
4982
4983 \end_layout
4984
4985 \end_inset
4986
4987
4988 \end_layout
4989
4990 \begin_layout Subsubsection
4991 check_load tests
4992 \end_layout
4993
4994 \begin_layout Standard
4995 These tests check whether a .lyx file loads without any terminal messages.
4996  They correspond to the manual operations of simply opening a .lyx file on
4997  the terminal, exiting LyX once the file is loaded, and then checking whether
4998  there is any output from the terminal.
4999  These tests are useful for catching malformed .lyx files and parsing bugs.
5000  They can also be used to find a .lyx file in which an instance of something
5001  happens.
5002  To do this, compile LyX with a local patch that outputs something to the
5003  terminal when an instance is found, and then run the check_load tests to
5004  see if any fail, which would mean that the situation occurs in the LyX
5005  documentation files corresponding to the failed tests.
5006  These tests are expectedly fragile: any LyX diagnostic message, which is
5007  not necessarily an error, would cause the tests to fail.
5008  Similarly, any message output by a library (e.g.
5009  Qt) would also cause failure.
5010  There are some messages that the check_load tests are instructed to ignore,
5011  which are stored in the file
5012 \begin_inset Flex Code
5013 status collapsed
5014
5015 \begin_layout Plain Layout
5016 development/autotests/filterCheckWarnings
5017 \end_layout
5018
5019 \end_inset
5020
5021 .
5022 \end_layout
5023
5024 \begin_layout Standard
5025 Under cmake, the tests are labeled as 'load'.
5026 \end_layout
5027
5028 \begin_layout Subsubsection
5029 Keytests
5030 \end_layout
5031
5032 \begin_layout Standard
5033 Automated tests based on the "MonKey Testing" keytest program are enabled
5034  if the necessary dependencies are found and if the CMake flag
5035 \begin_inset Flex Code
5036 status collapsed
5037
5038 \begin_layout Plain Layout
5039 -DLYX_ENABLE_KEYTESTS=ON
5040 \end_layout
5041
5042 \end_inset
5043
5044  is used.
5045  They are documented in the README document in
5046 \begin_inset Flex Code
5047 status collapsed
5048
5049 \begin_layout Plain Layout
5050 development/autotests
5051 \end_layout
5052
5053 \end_inset
5054
5055  subfolder of the \SpecialChar LyX
5056  source code distribution.
5057 \end_layout
5058
5059 \begin_layout Subsubsection
5060 lyx21 tests
5061 \end_layout
5062
5063 \begin_layout Standard
5064 These tests combine lyx2lyx tests with check_load tests.
5065  They fail if either fails.
5066 \end_layout
5067
5068 \begin_layout Subsubsection
5069 URL tests
5070 \end_layout
5071
5072 \begin_layout Standard
5073 The URL tests are enabled with the
5074 \begin_inset Flex Code
5075 status collapsed
5076
5077 \begin_layout Plain Layout
5078 -DLYX_ENABLE_URLTESTS=ON
5079 \end_layout
5080
5081 \end_inset
5082
5083  CMake flag and are useful for finding broken links in our documentation
5084  files.
5085  If a URL test fails, to see which link in particular was reported as broken,
5086  see the output in
5087 \begin_inset Flex Code
5088 status collapsed
5089
5090 \begin_layout Plain Layout
5091 LastTest.log
5092 \end_layout
5093
5094 \end_inset
5095
5096 .
5097  These tests are extremely fragile (e.g.
5098  a test can depend on your Internet connection) and a failed URL test should
5099  not be taken too seriously.
5100  URL tests are labeled as
5101 \family typewriter
5102 'url'.
5103 \end_layout
5104
5105 \begin_layout Paragraph
5106 Running URL tests
5107 \end_layout
5108
5109 \begin_layout Standard
5110 cmake is required to run the \SpecialChar LyX
5111  tests, running them is not implemented for
5112  autotools.
5113 \end_layout
5114
5115 \begin_layout Standard
5116 The appropriate commands are:
5117 \end_layout
5118
5119 \begin_layout Itemize
5120
5121 \family typewriter
5122 ctest -L url
5123 \family default
5124
5125 \begin_inset Newline newline
5126 \end_inset
5127
5128 runs all tests with label
5129 \family typewriter
5130 'url'
5131 \end_layout
5132
5133 \begin_layout Itemize
5134
5135 \family typewriter
5136 ctest -R 'check_.*urls'
5137 \family default
5138
5139 \begin_inset Newline newline
5140 \end_inset
5141
5142 runs the tests 'check_accessible_urls'
5143 \end_layout
5144
5145 \begin_layout Standard
5146 Associated test results can be examined in ctest-log directory in files
5147  of the form 'LastFailed.*URLS.log'
5148 \end_layout
5149
5150 \begin_layout Section
5151 Development policies
5152 \end_layout
5153
5154 \begin_layout Standard
5155 This chapter lists some guidelines that should be followed.
5156  This list is not complete, and many guidelines are in separate chapters,
5157  such as
5158 \begin_inset Quotes eld
5159 \end_inset
5160
5161 When is an update of the .lyx file format number needed?
5162 \begin_inset Quotes erd
5163 \end_inset
5164
5165  in Section
5166 \begin_inset CommandInset ref
5167 LatexCommand ref
5168 reference "sec:When-is-an"
5169
5170 \end_inset
5171
5172 .
5173 \end_layout
5174
5175 \begin_layout Subsection
5176 When to set a fixed milestone?
5177 \end_layout
5178
5179 \begin_layout Standard
5180 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5181  holds:
5182 \end_layout
5183
5184 \begin_layout Enumerate
5185 Somebody is actively working on a fix.
5186 \end_layout
5187
5188 \begin_layout Enumerate
5189 The bug is so severe that it would block the release if it is not fixed.
5190 \end_layout
5191
5192 \begin_layout Standard
5193 If a bug is important, but nobody is working on it, and it is no showstopper,
5194  use a milestone like 2.1.x or 2.2.x.
5195  For all other bugs, do not set a milestone at all.
5196 \end_layout
5197
5198 \begin_layout Subsection
5199 Can we add rc entries in stable branch?
5200 \end_layout
5201
5202 \begin_layout Standard
5203 No.
5204  We are supposed to increase the prefs2prefs version number with such things.
5205 \end_layout
5206
5207 \begin_layout Section
5208 \begin_inset CommandInset label
5209 LatexCommand label
5210 name "sec:Documentation-policies"
5211
5212 \end_inset
5213
5214 Documentation policies
5215 \end_layout
5216
5217 \begin_layout Subsection
5218 Rules
5219 \end_layout
5220
5221 \begin_layout Standard
5222 There are 6
5223 \begin_inset space ~
5224 \end_inset
5225
5226 rules in editing the docs:
5227 \end_layout
5228
5229 \begin_layout Enumerate
5230 \begin_inset CommandInset label
5231 LatexCommand label
5232 name "enu:If-you-are"
5233
5234 \end_inset
5235
5236 If you are not the maintainer of a doc file or a chapter/section, you MUST
5237  use change tracking so that the maintainer could review your changes
5238 \end_layout
5239
5240 \begin_layout Enumerate
5241 Respect the formatting of the document.
5242  The different files use different formatting styles.
5243  That is OK and has historic reasons nobody fully knows ;-).
5244  But it is important to be consistent within one file.
5245 \end_layout
5246
5247 \begin_layout Enumerate
5248 All changes you make to a file in one language MUST also go the file in
5249  the other actively maintained languages.
5250  Normally the maintainer does this for you, if you are the maintainer, you
5251  must do this by copying or changing the changed or added text to the other
5252  files so that the translators sees the blue underlined text and know what
5253  they have to translate and what was changed.
5254 \end_layout
5255
5256 \begin_layout Enumerate
5257 You MUST assure that the document is compilable as
5258 \begin_inset Quotes eld
5259 \end_inset
5260
5261 PDF (pdflatex)
5262 \begin_inset Quotes erd
5263 \end_inset
5264
5265  or the document's default output format after your changes.
5266 \end_layout
5267
5268 \begin_layout Enumerate
5269 All fixes (typos, compilation fixes, updates info etc.) go at first into
5270  the current GIT branch because the user should benefit from all fixes with
5271  every minor release.
5272  Feel free to commit directly to branch as long as you follow rule
5273 \begin_inset space ~
5274 \end_inset
5275
5276
5277 \begin_inset CommandInset ref
5278 LatexCommand ref
5279 reference "enu:If-you-are"
5280
5281 \end_inset
5282
5283 .
5284  You can immediately commit to master as well.
5285 \end_layout
5286
5287 \begin_layout Enumerate
5288 \begin_inset CommandInset label
5289 LatexCommand label
5290 name "enu:The-fileformat-of"
5291
5292 \end_inset
5293
5294 The fileformat of a file must not be changed unless you document a new feature
5295  in LyX that requires a new fileformat.
5296  The reason for this rule is to keep it easy for the doc maintainers to
5297  port/backport changes to from master/branch.
5298 \end_layout
5299
5300 \begin_layout Standard
5301 The main documentation consists of these files:
5302 \end_layout
5303
5304 \begin_layout Description
5305 splash.lyx it is the first file you see after an installation.
5306  We assume that a new user sees this.
5307  It is therefore designed to be as simple as possible.
5308  Therefore please don't add any new formatting, only fix typos etc.
5309  Splash.lyx is up to date for \SpecialChar LyX
5310  2.1.x, currently maintained by Uwe Stöhr.
5311 \end_layout
5312
5313 \begin_layout Description
5314 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5315 .
5316  It therefore uses a limited set of formatting.
5317  For example a standard document class.
5318  Since new users will first learn about the formatting possibilities of
5319  \SpecialChar LyX
5320  please keep this file that simple.
5321  Intro.lyx is up to date for \SpecialChar LyX
5322  2.1.x, currently maintained by Uwe Stöhr.
5323 \end_layout
5324
5325 \begin_layout Description
5326 Tutorial.lyx our tutorial.
5327  It must be always up to date.
5328  Normally there is nothing to add since we don't want to overwhelm new users
5329  with too much details.
5330  The will learn these details while using \SpecialChar LyX
5331  and we have special manuals.
5332  Tutorial.lyx is up to date for \SpecialChar LyX
5333  2.1.x, currently maintained by Uwe Stöhr.
5334 \end_layout
5335
5336 \begin_layout Description
5337 UserGuide.lyx our main user guide.
5338  It covers a mixture of basic and detailed information.
5339  Some information is also in the Math and EmbeddedObjects manual so that
5340  the UserGuide refers to these files.
5341  UserGuide.lyx is up to date for \SpecialChar LyX
5342  2.1.x, currently maintained by Uwe Stöhr.
5343 \end_layout
5344
5345 \begin_layout Description
5346 EmbeddedObjects.lyx a special manual to explain things like tables floats
5347  boxes etc.
5348  in all detail.
5349  EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5350  2.1.x, currently maintained by Uwe
5351  Stöhr.
5352 \end_layout
5353
5354 \begin_layout Description
5355 Math.lyx a special manual to explain everything regarding math in all detail.
5356  Math.lyx is up to date for \SpecialChar LyX
5357  2.1.x, currently maintained by Uwe Stöhr.
5358 \end_layout
5359
5360 \begin_layout Description
5361 Additional.lyx this manual covers information that would be too much detail
5362  for the UserGuide or would make the UserGuide uncompilable or only compilable
5363  when installing a lot of special \SpecialChar LaTeX
5364 -packages.
5365  What should be in the UserGuide or better in Additional is a matter of
5366  taste.
5367  it is up to you to decide that.
5368  Additional.lyx is not completely up to date for \SpecialChar LyX
5369  2.1.x.
5370  Only chapter
5371 \begin_inset space ~
5372 \end_inset
5373
5374 8 is up to date and currently maintained by Uwe Stöhr.
5375  It certainly needs a rewrite and update.
5376  For example many info in chapter
5377 \begin_inset space ~
5378 \end_inset
5379
5380 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5381  manual.
5382 \end_layout
5383
5384 \begin_layout Description
5385 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5386  for certain
5387  output formats, operating systems, languages etc.
5388  It is currently completely out of date and needs a major rewrite and update.
5389  If you do this please assure that your information are given for all OSes
5390  and \SpecialChar LaTeX
5391  distributions (meaning be as objective as possible).
5392 \end_layout
5393
5394 \end_body
5395 \end_document