lib/doc/Development.lyx

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