lib/doc/Development.lyx

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