lib/doc/Development.lyx

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