lib/doc/Development.lyx

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