lib/doc/Development.lyx

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