lib/doc/Development.lyx

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