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 labeledas
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 Test depending on TeX distribution, package versions or
3831  OS.
3832 \end_layout
3833
3834 \begin_layout Description
3835 wrong
3836 \begin_inset space ~
3837 \end_inset
3838
3839 output Export does not fail but the resulting document has (undetected)
3840  errors.
3841 \end_layout
3842
3843 \begin_deeper
3844 \begin_layout Standard
3845 \paragraph_spacing single
3846 \begin_inset Note Note
3847 status open
3848
3849 \begin_layout Plain Layout
3850 \paragraph_spacing single
3851 These tests are in a strict sense not unreliable but
3852 \emph on
3853 invalid
3854 \emph default
3855  (not measuring what they should measure).
3856 \end_layout
3857
3858 \end_inset
3859
3860
3861 \end_layout
3862
3863 \end_deeper
3864 \begin_layout Paragraph
3865 \begin_inset CommandInset label
3866 LatexCommand label
3867 name "par:Export-test-filtering"
3868
3869 \end_inset
3870
3871 Export test filtering
3872 \end_layout
3873
3874 \begin_layout Standard
3875 The assignment of a label to a test is controlled by a set of files with
3876  regular expressions that are matched against the test names.
3877 \end_layout
3878
3879 \begin_layout Description
3880 ignoredTests (small file)
3881 \begin_inset Newline newline
3882 \end_inset
3883
3884 Tests selected here are withdrawn in the configuration step (cf.
3885
3886 \begin_inset CommandInset ref
3887 LatexCommand ref
3888 reference "par:Configuring-ctests"
3889
3890 \end_inset
3891
3892 ).
3893 \end_layout
3894
3895 \begin_deeper
3896 \begin_layout Labeling
3897 \labelwidthstring 00.00.0000
3898 Input Test of any export combination
3899 \end_layout
3900
3901 \begin_layout Labeling
3902 \labelwidthstring 00.00.0000
3903 Output Stop if tests not selected here
3904 \end_layout
3905
3906 \end_deeper
3907 \begin_layout Description
3908 unreliableTests: Tests selected pass or fail dependent on the system where
3909  the test is run.
3910  Selected tests gain the label 'unreliable'.
3911 \end_layout
3912
3913 \begin_deeper
3914 \begin_layout Labeling
3915 \labelwidthstring 00.00.0000
3916 Input Each test which passed 'ignoredTests'
3917 \end_layout
3918
3919 \begin_layout Labeling
3920 \labelwidthstring 00.00.0000
3921 Output Gain label 'unreliable', proceed with checking for 'inverted'.
3922 \end_layout
3923
3924 \end_deeper
3925 \begin_layout Description
3926 invertedTests
3927 \begin_inset space \space{}
3928 \end_inset
3929
3930
3931 \end_layout
3932
3933 \begin_deeper
3934 \begin_layout Labeling
3935 \labelwidthstring 00.00.0000
3936 Input Each test which passed 'ignoredTests'
3937 \end_layout
3938
3939 \begin_layout Labeling
3940 \labelwidthstring 00.00.0000
3941 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3942  tests are reported as failing if the export works without error.) If no
3943  subselection applies, gain labels 'export' and 'inverted'.
3944 \end_layout
3945
3946 \begin_layout Standard
3947 The following filter perfoms a subselection of 'invertedTests':
3948 \end_layout
3949
3950 \begin_layout Description
3951 suspendedTests Tests selected here gain the label 'suspended' but _not_
3952  'export' or 'inverted', although in ctest they remain inverted.
3953  ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3954 \end_layout
3955
3956 \begin_deeper
3957 \begin_layout Labeling
3958 \labelwidthstring 00.00.0000
3959 Input Each test selected by 'invertedTests'
3960 \end_layout
3961
3962 \begin_layout Labeling
3963 \labelwidthstring 00.00.0000
3964 Output Selected test gains label 'suspended'.
3965
3966 \end_layout
3967
3968 \end_deeper
3969 \end_deeper
3970 \begin_layout Standard
3971 The following table may clarify label assignement
3972 \end_layout
3973
3974 \begin_layout Standard
3975 \begin_inset space \hspace{}
3976 \length -3cm
3977 \end_inset
3978
3979
3980 \begin_inset Tabular
3981 <lyxtabular version="3" rows="6" columns="8">
3982 <features tabularvalignment="middle">
3983 <column alignment="left" valignment="top" width="2cm">
3984 <column alignment="left" valignment="top" width="2.5cm">
3985 <column alignment="left" valignment="top" width="2cm">
3986 <column alignment="center" valignment="top" width="2.5cm">
3987 <column alignment="center" valignment="top">
3988 <column alignment="center" valignment="top">
3989 <column alignment="center" valignment="top">
3990 <column alignment="center" valignment="top">
3991 <row>
3992 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3993 \begin_inset Text
3994
3995 \begin_layout Plain Layout
3996 Test matching pattern in file:
3997 \end_layout
3998
3999 \end_inset
4000 </cell>
4001 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4002 \begin_inset Text
4003
4004 \begin_layout Plain Layout
4005
4006 \end_layout
4007
4008 \end_inset
4009 </cell>
4010 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4011 \begin_inset Text
4012
4013 \begin_layout Plain Layout
4014
4015 \end_layout
4016
4017 \end_inset
4018 </cell>
4019 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4020 \begin_inset Text
4021
4022 \begin_layout Plain Layout
4023
4024 \end_layout
4025
4026 \end_inset
4027 </cell>
4028 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4029 \begin_inset Text
4030
4031 \begin_layout Plain Layout
4032 Assigned label
4033 \end_layout
4034
4035 \end_inset
4036 </cell>
4037 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4038 \begin_inset Text
4039
4040 \begin_layout Plain Layout
4041
4042 \end_layout
4043
4044 \end_inset
4045 </cell>
4046 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4047 \begin_inset Text
4048
4049 \begin_layout Plain Layout
4050
4051 \end_layout
4052
4053 \end_inset
4054 </cell>
4055 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4056 \begin_inset Text
4057
4058 \begin_layout Plain Layout
4059 test property
4060 \end_layout
4061
4062 \end_inset
4063 </cell>
4064 </row>
4065 <row>
4066 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4067 \begin_inset Text
4068
4069 \begin_layout Plain Layout
4070 ignored\SpecialChar softhyphen
4071 Tests
4072 \end_layout
4073
4074 \end_inset
4075 </cell>
4076 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4077 \begin_inset Text
4078
4079 \begin_layout Plain Layout
4080 unreliable\SpecialChar softhyphen
4081 Tests
4082 \end_layout
4083
4084 \end_inset
4085 </cell>
4086 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4087 \begin_inset Text
4088
4089 \begin_layout Plain Layout
4090 inverted\SpecialChar softhyphen
4091 Tests
4092 \end_layout
4093
4094 \end_inset
4095 </cell>
4096 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4097 \begin_inset Text
4098
4099 \begin_layout Plain Layout
4100 suspended\SpecialChar softhyphen
4101 Tests
4102 \end_layout
4103
4104 \end_inset
4105 </cell>
4106 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4107 \begin_inset Text
4108
4109 \begin_layout Plain Layout
4110 export
4111 \end_layout
4112
4113 \end_inset
4114 </cell>
4115 <cell alignment="center" valignment="top" topline="true" usebox="none">
4116 \begin_inset Text
4117
4118 \begin_layout Plain Layout
4119 inverted
4120 \end_layout
4121
4122 \end_inset
4123 </cell>
4124 <cell alignment="center" valignment="top" topline="true" usebox="none">
4125 \begin_inset Text
4126
4127 \begin_layout Plain Layout
4128 suspended
4129 \end_layout
4130
4131 \end_inset
4132 </cell>
4133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4134 \begin_inset Text
4135
4136 \begin_layout Plain Layout
4137
4138 \end_layout
4139
4140 \end_inset
4141 </cell>
4142 </row>
4143 <row>
4144 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4145 \begin_inset Text
4146
4147 \begin_layout Plain Layout
4148 Yes
4149 \end_layout
4150
4151 \end_inset
4152 </cell>
4153 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4154 \begin_inset Text
4155
4156 \begin_layout Plain Layout
4157 -
4158 \end_layout
4159
4160 \end_inset
4161 </cell>
4162 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4163 \begin_inset Text
4164
4165 \begin_layout Plain Layout
4166 -
4167 \end_layout
4168
4169 \end_inset
4170 </cell>
4171 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4172 \begin_inset Text
4173
4174 \begin_layout Plain Layout
4175 -
4176 \end_layout
4177
4178 \end_inset
4179 </cell>
4180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4181 \begin_inset Text
4182
4183 \begin_layout Plain Layout
4184 -
4185 \end_layout
4186
4187 \end_inset
4188 </cell>
4189 <cell alignment="center" valignment="top" topline="true" usebox="none">
4190 \begin_inset Text
4191
4192 \begin_layout Plain Layout
4193 -
4194 \end_layout
4195
4196 \end_inset
4197 </cell>
4198 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4199 \begin_inset Text
4200
4201 \begin_layout Plain Layout
4202 -
4203 \end_layout
4204
4205 \end_inset
4206 </cell>
4207 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4208 \begin_inset Text
4209
4210 \begin_layout Plain Layout
4211
4212 \end_layout
4213
4214 \end_inset
4215 </cell>
4216 </row>
4217 <row>
4218 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4219 \begin_inset Text
4220
4221 \begin_layout Plain Layout
4222 No
4223 \end_layout
4224
4225 \end_inset
4226 </cell>
4227 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4228 \begin_inset Text
4229
4230 \begin_layout Plain Layout
4231 If Yes,
4232 \begin_inset Newline newline
4233 \end_inset
4234
4235 add label
4236 \begin_inset Newline newline
4237 \end_inset
4238
4239 'unreliable'
4240 \end_layout
4241
4242 \end_inset
4243 </cell>
4244 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4245 \begin_inset Text
4246
4247 \begin_layout Plain Layout
4248 Yes
4249 \end_layout
4250
4251 \end_inset
4252 </cell>
4253 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4254 \begin_inset Text
4255
4256 \begin_layout Plain Layout
4257 Yes
4258 \end_layout
4259
4260 \end_inset
4261 </cell>
4262 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4263 \begin_inset Text
4264
4265 \begin_layout Plain Layout
4266 -
4267 \end_layout
4268
4269 \end_inset
4270 </cell>
4271 <cell alignment="center" valignment="top" topline="true" usebox="none">
4272 \begin_inset Text
4273
4274 \begin_layout Plain Layout
4275 -
4276 \end_layout
4277
4278 \end_inset
4279 </cell>
4280 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4281 \begin_inset Text
4282
4283 \begin_layout Plain Layout
4284 +
4285 \end_layout
4286
4287 \end_inset
4288 </cell>
4289 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4290 \begin_inset Text
4291
4292 \begin_layout Plain Layout
4293 WILL_FAIL
4294 \end_layout
4295
4296 \end_inset
4297 </cell>
4298 </row>
4299 <row>
4300 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4301 \begin_inset Text
4302
4303 \begin_layout Plain Layout
4304
4305 \end_layout
4306
4307 \end_inset
4308 </cell>
4309 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4310 \begin_inset Text
4311
4312 \begin_layout Plain Layout
4313
4314 \end_layout
4315
4316 \end_inset
4317 </cell>
4318 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4319 \begin_inset Text
4320
4321 \begin_layout Plain Layout
4322
4323 \end_layout
4324
4325 \end_inset
4326 </cell>
4327 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4328 \begin_inset Text
4329
4330 \begin_layout Plain Layout
4331 No
4332 \end_layout
4333
4334 \end_inset
4335 </cell>
4336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4337 \begin_inset Text
4338
4339 \begin_layout Plain Layout
4340 +
4341 \end_layout
4342
4343 \end_inset
4344 </cell>
4345 <cell alignment="center" valignment="top" topline="true" usebox="none">
4346 \begin_inset Text
4347
4348 \begin_layout Plain Layout
4349 +
4350 \end_layout
4351
4352 \end_inset
4353 </cell>
4354 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4355 \begin_inset Text
4356
4357 \begin_layout Plain Layout
4358 -
4359 \end_layout
4360
4361 \end_inset
4362 </cell>
4363 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4364 \begin_inset Text
4365
4366 \begin_layout Plain Layout
4367 WILL_FAIL
4368 \end_layout
4369
4370 \end_inset
4371 </cell>
4372 </row>
4373 <row>
4374 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4375 \begin_inset Text
4376
4377 \begin_layout Plain Layout
4378
4379 \end_layout
4380
4381 \end_inset
4382 </cell>
4383 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4384 \begin_inset Text
4385
4386 \begin_layout Plain Layout
4387
4388 \end_layout
4389
4390 \end_inset
4391 </cell>
4392 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4393 \begin_inset Text
4394
4395 \begin_layout Plain Layout
4396 No
4397 \end_layout
4398
4399 \end_inset
4400 </cell>
4401 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4402 \begin_inset Text
4403
4404 \begin_layout Plain Layout
4405 -
4406 \end_layout
4407
4408 \end_inset
4409 </cell>
4410 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4411 \begin_inset Text
4412
4413 \begin_layout Plain Layout
4414 +
4415 \end_layout
4416
4417 \end_inset
4418 </cell>
4419 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4420 \begin_inset Text
4421
4422 \begin_layout Plain Layout
4423 -
4424 \end_layout
4425
4426 \end_inset
4427 </cell>
4428 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4429 \begin_inset Text
4430
4431 \begin_layout Plain Layout
4432 -
4433 \end_layout
4434
4435 \end_inset
4436 </cell>
4437 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4438 \begin_inset Text
4439
4440 \begin_layout Plain Layout
4441
4442 \end_layout
4443
4444 \end_inset
4445 </cell>
4446 </row>
4447 </lyxtabular>
4448
4449 \end_inset
4450
4451
4452 \end_layout
4453
4454 \begin_layout Standard
4455 \begin_inset Note Note
4456 status open
4457
4458 \begin_layout Plain Layout
4459 Without the
4460 \begin_inset Quotes eld
4461 \end_inset
4462
4463 suspendedTests
4464 \begin_inset Quotes erd
4465 \end_inset
4466
4467  filter, this would be far less complicated:
4468 \end_layout
4469
4470 \begin_layout Plain Layout
4471 \begin_inset Tabular
4472 <lyxtabular version="3" rows="6" columns="7">
4473 <features tabularvalignment="middle">
4474 <column alignment="left" valignment="top" width="0pt">
4475 <column alignment="left" valignment="top" width="0pt">
4476 <column alignment="left" valignment="top" width="0pt">
4477 <column alignment="center" valignment="top">
4478 <column alignment="center" valignment="top">
4479 <column alignment="center" valignment="top">
4480 <column alignment="center" valignment="top">
4481 <row>
4482 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4483 \begin_inset Text
4484
4485 \begin_layout Plain Layout
4486 Test matching pattern in file:
4487 \end_layout
4488
4489 \end_inset
4490 </cell>
4491 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4492 \begin_inset Text
4493
4494 \begin_layout Plain Layout
4495
4496 \end_layout
4497
4498 \end_inset
4499 </cell>
4500 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4501 \begin_inset Text
4502
4503 \begin_layout Plain Layout
4504
4505 \end_layout
4506
4507 \end_inset
4508 </cell>
4509 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4510 \begin_inset Text
4511
4512 \begin_layout Plain Layout
4513 Label
4514 \end_layout
4515
4516 \end_inset
4517 </cell>
4518 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4519 \begin_inset Text
4520
4521 \begin_layout Plain Layout
4522
4523 \end_layout
4524
4525 \end_inset
4526 </cell>
4527 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4528 \begin_inset Text
4529
4530 \begin_layout Plain Layout
4531
4532 \end_layout
4533
4534 \end_inset
4535 </cell>
4536 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4537 \begin_inset Text
4538
4539 \begin_layout Plain Layout
4540 test property
4541 \end_layout
4542
4543 \end_inset
4544 </cell>
4545 </row>
4546 <row>
4547 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4548 \begin_inset Text
4549
4550 \begin_layout Plain Layout
4551 ignoredTests
4552 \end_layout
4553
4554 \end_inset
4555 </cell>
4556 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4557 \begin_inset Text
4558
4559 \begin_layout Plain Layout
4560 unreliableTests
4561 \end_layout
4562
4563 \end_inset
4564 </cell>
4565 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4566 \begin_inset Text
4567
4568 \begin_layout Plain Layout
4569 invertedTests
4570 \end_layout
4571
4572 \end_inset
4573 </cell>
4574 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4575 \begin_inset Text
4576
4577 \begin_layout Plain Layout
4578 export
4579 \end_layout
4580
4581 \end_inset
4582 </cell>
4583 <cell alignment="center" valignment="top" topline="true" usebox="none">
4584 \begin_inset Text
4585
4586 \begin_layout Plain Layout
4587 unreliable
4588 \end_layout
4589
4590 \end_inset
4591 </cell>
4592 <cell alignment="center" valignment="top" topline="true" usebox="none">
4593 \begin_inset Text
4594
4595 \begin_layout Plain Layout
4596 inverted
4597 \end_layout
4598
4599 \end_inset
4600 </cell>
4601 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4602 \begin_inset Text
4603
4604 \begin_layout Plain Layout
4605
4606 \end_layout
4607
4608 \end_inset
4609 </cell>
4610 </row>
4611 <row>
4612 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4613 \begin_inset Text
4614
4615 \begin_layout Plain Layout
4616 Yes
4617 \end_layout
4618
4619 \end_inset
4620 </cell>
4621 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4622 \begin_inset Text
4623
4624 \begin_layout Plain Layout
4625 -
4626 \end_layout
4627
4628 \end_inset
4629 </cell>
4630 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4631 \begin_inset Text
4632
4633 \begin_layout Plain Layout
4634 -
4635 \end_layout
4636
4637 \end_inset
4638 </cell>
4639 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4640 \begin_inset Text
4641
4642 \begin_layout Plain Layout
4643 -
4644 \end_layout
4645
4646 \end_inset
4647 </cell>
4648 <cell alignment="center" valignment="top" topline="true" usebox="none">
4649 \begin_inset Text
4650
4651 \begin_layout Plain Layout
4652
4653 \end_layout
4654
4655 \end_inset
4656 </cell>
4657 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4658 \begin_inset Text
4659
4660 \begin_layout Plain Layout
4661 -
4662 \end_layout
4663
4664 \end_inset
4665 </cell>
4666 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4667 \begin_inset Text
4668
4669 \begin_layout Plain Layout
4670
4671 \end_layout
4672
4673 \end_inset
4674 </cell>
4675 </row>
4676 <row>
4677 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4678 \begin_inset Text
4679
4680 \begin_layout Plain Layout
4681 No
4682 \end_layout
4683
4684 \end_inset
4685 </cell>
4686 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4687 \begin_inset Text
4688
4689 \begin_layout Plain Layout
4690 Yes
4691 \end_layout
4692
4693 \end_inset
4694 </cell>
4695 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4696 \begin_inset Text
4697
4698 \begin_layout Plain Layout
4699 -
4700 \end_layout
4701
4702 \end_inset
4703 </cell>
4704 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4705 \begin_inset Text
4706
4707 \begin_layout Plain Layout
4708 -
4709 \end_layout
4710
4711 \end_inset
4712 </cell>
4713 <cell alignment="center" valignment="top" topline="true" usebox="none">
4714 \begin_inset Text
4715
4716 \begin_layout Plain Layout
4717 +
4718 \end_layout
4719
4720 \end_inset
4721 </cell>
4722 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4723 \begin_inset Text
4724
4725 \begin_layout Plain Layout
4726 -
4727 \end_layout
4728
4729 \end_inset
4730 </cell>
4731 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4732 \begin_inset Text
4733
4734 \begin_layout Plain Layout
4735
4736 \end_layout
4737
4738 \end_inset
4739 </cell>
4740 </row>
4741 <row>
4742 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4743 \begin_inset Text
4744
4745 \begin_layout Plain Layout
4746
4747 \end_layout
4748
4749 \end_inset
4750 </cell>
4751 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4752 \begin_inset Text
4753
4754 \begin_layout Plain Layout
4755 No
4756 \end_layout
4757
4758 \end_inset
4759 </cell>
4760 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4761 \begin_inset Text
4762
4763 \begin_layout Plain Layout
4764 Yes
4765 \end_layout
4766
4767 \end_inset
4768 </cell>
4769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4770 \begin_inset Text
4771
4772 \begin_layout Plain Layout
4773 +
4774 \end_layout
4775
4776 \end_inset
4777 </cell>
4778 <cell alignment="center" valignment="top" topline="true" usebox="none">
4779 \begin_inset Text
4780
4781 \begin_layout Plain Layout
4782 -
4783 \end_layout
4784
4785 \end_inset
4786 </cell>
4787 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4788 \begin_inset Text
4789
4790 \begin_layout Plain Layout
4791 +
4792 \end_layout
4793
4794 \end_inset
4795 </cell>
4796 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4797 \begin_inset Text
4798
4799 \begin_layout Plain Layout
4800 WILL_FAIL
4801 \end_layout
4802
4803 \end_inset
4804 </cell>
4805 </row>
4806 <row>
4807 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4808 \begin_inset Text
4809
4810 \begin_layout Plain Layout
4811
4812 \end_layout
4813
4814 \end_inset
4815 </cell>
4816 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4817 \begin_inset Text
4818
4819 \begin_layout Plain Layout
4820
4821 \end_layout
4822
4823 \end_inset
4824 </cell>
4825 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4826 \begin_inset Text
4827
4828 \begin_layout Plain Layout
4829 No
4830 \end_layout
4831
4832 \end_inset
4833 </cell>
4834 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4835 \begin_inset Text
4836
4837 \begin_layout Plain Layout
4838 +
4839 \end_layout
4840
4841 \end_inset
4842 </cell>
4843 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4844 \begin_inset Text
4845
4846 \begin_layout Plain Layout
4847 -
4848 \end_layout
4849
4850 \end_inset
4851 </cell>
4852 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4853 \begin_inset Text
4854
4855 \begin_layout Plain Layout
4856 -
4857 \end_layout
4858
4859 \end_inset
4860 </cell>
4861 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4862 \begin_inset Text
4863
4864 \begin_layout Plain Layout
4865
4866 \end_layout
4867
4868 \end_inset
4869 </cell>
4870 </row>
4871 </lyxtabular>
4872
4873 \end_inset
4874
4875
4876 \end_layout
4877
4878 \end_inset
4879
4880
4881 \end_layout
4882
4883 \begin_layout Subsubsection
4884 check_load tests
4885 \end_layout
4886
4887 \begin_layout Standard
4888 These tests check whether a .lyx file loads without any terminal messages.
4889  They correspond to the manual operations of simply opening a .lyx file on
4890  the terminal, exiting LyX once the file is loaded, and then checking whether
4891  there is any output from the terminal.
4892  These tests are useful for catching malformed .lyx files and parsing bugs.
4893  They can also be used to find a .lyx file in which an instance of something
4894  happens.
4895  To do this, compile LyX with a local patch that outputs something to the
4896  terminal when an instance is found, and then run the check_load tests to
4897  see if any fail, which would mean that the situation occurs in the LyX
4898  documentation files corresponding to the failed tests.
4899  These tests are expectedly fragile: any LyX diagnostic message, which is
4900  not necessarily an error, would cause the tests to fail.
4901  Similarly, any message output by a library (e.g.
4902  Qt) would also cause failure.
4903  There are some messages that the check_load tests are instructed to ignore,
4904  which are stored in the file
4905 \begin_inset Flex Code
4906 status collapsed
4907
4908 \begin_layout Plain Layout
4909 development/autotests/filterCheckWarnings
4910 \end_layout
4911
4912 \end_inset
4913
4914 .
4915 \end_layout
4916
4917 \begin_layout Standard
4918 Under cmake, the tests are labeled as 'load'.
4919 \end_layout
4920
4921 \begin_layout Subsubsection
4922 Keytests
4923 \end_layout
4924
4925 \begin_layout Standard
4926 Automated tests based on the "MonKey Testing" keytest program are enabled
4927  if the necessary dependencies are found and if the CMake flag
4928 \begin_inset Flex Code
4929 status collapsed
4930
4931 \begin_layout Plain Layout
4932 -DLYX_ENABLE_KEYTESTS=ON
4933 \end_layout
4934
4935 \end_inset
4936
4937  is used.
4938  They are documented in the README document in
4939 \begin_inset Flex Code
4940 status collapsed
4941
4942 \begin_layout Plain Layout
4943 development/autotests
4944 \end_layout
4945
4946 \end_inset
4947
4948  subfolder of the \SpecialChar LyX
4949  source code distribution.
4950 \end_layout
4951
4952 \begin_layout Subsubsection
4953 lyx21 tests
4954 \end_layout
4955
4956 \begin_layout Standard
4957 These tests combine lyx2lyx tests with check_load tests.
4958  They fail if either fails.
4959 \end_layout
4960
4961 \begin_layout Subsubsection
4962 URL tests
4963 \end_layout
4964
4965 \begin_layout Standard
4966 The URL tests are enabled with the
4967 \begin_inset Flex Code
4968 status collapsed
4969
4970 \begin_layout Plain Layout
4971 -DLYX_ENABLE_URLTESTS=ON
4972 \end_layout
4973
4974 \end_inset
4975
4976  CMake flag and are useful for finding broken links in our documentation
4977  files.
4978  If a URL test fails, to see which link in particular was reported as broken,
4979  see the output in
4980 \begin_inset Flex Code
4981 status collapsed
4982
4983 \begin_layout Plain Layout
4984 LastTest.log
4985 \end_layout
4986
4987 \end_inset
4988
4989 .
4990  These tests are extremely fragile (e.g.
4991  a test can depend on your Internet connection) and a failed URL test should
4992  not be taken too seriously.
4993  URL tests are labeled as
4994 \family typewriter
4995 'url'.
4996 \end_layout
4997
4998 \begin_layout Paragraph
4999 Running URL tests
5000 \end_layout
5001
5002 \begin_layout Standard
5003 cmake is required to run the \SpecialChar LyX
5004  tests, running them is not implemented for
5005  autotools.
5006 \end_layout
5007
5008 \begin_layout Standard
5009 The appropriate commands are:
5010 \end_layout
5011
5012 \begin_layout Itemize
5013
5014 \family typewriter
5015 ctest -L url
5016 \family default
5017
5018 \begin_inset Newline newline
5019 \end_inset
5020
5021 runs all tests with label
5022 \family typewriter
5023 'url'
5024 \end_layout
5025
5026 \begin_layout Itemize
5027
5028 \family typewriter
5029 ctest -R 'check_.*urls'
5030 \family default
5031
5032 \begin_inset Newline newline
5033 \end_inset
5034
5035 runs the tests 'check_accessible_urls'
5036 \end_layout
5037
5038 \begin_layout Standard
5039 Associated test results can be examined in ctest-log directory in files
5040  of the form 'LastFailed.*URLS.log'
5041 \end_layout
5042
5043 \begin_layout Section
5044 Development policies
5045 \end_layout
5046
5047 \begin_layout Standard
5048 This chapter lists some guidelines that should be followed.
5049  This list is not complete, and many guidelines are in separate chapters,
5050  such as
5051 \begin_inset Quotes eld
5052 \end_inset
5053
5054 When is an update of the .lyx file format number needed?
5055 \begin_inset Quotes erd
5056 \end_inset
5057
5058  in Section
5059 \begin_inset CommandInset ref
5060 LatexCommand ref
5061 reference "sec:When-is-an"
5062
5063 \end_inset
5064
5065 .
5066 \end_layout
5067
5068 \begin_layout Subsection
5069 When to set a fixed milestone?
5070 \end_layout
5071
5072 \begin_layout Standard
5073 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5074  holds:
5075 \end_layout
5076
5077 \begin_layout Enumerate
5078 Somebody is actively working on a fix.
5079 \end_layout
5080
5081 \begin_layout Enumerate
5082 The bug is so severe that it would block the release if it is not fixed.
5083 \end_layout
5084
5085 \begin_layout Standard
5086 If a bug is important, but nobody is working on it, and it is no showstopper,
5087  use a milestone like 2.1.x or 2.2.x.
5088  For all other bugs, do not set a milestone at all.
5089 \end_layout
5090
5091 \begin_layout Subsection
5092 Can we add rc entries in stable branch?
5093 \end_layout
5094
5095 \begin_layout Standard
5096 No.
5097  We are supposed to increase the prefs2prefs version number with such things.
5098 \end_layout
5099
5100 \begin_layout Section
5101 \begin_inset CommandInset label
5102 LatexCommand label
5103 name "sec:Documentation-policies"
5104
5105 \end_inset
5106
5107 Documentation policies
5108 \end_layout
5109
5110 \begin_layout Subsection
5111 Rules
5112 \end_layout
5113
5114 \begin_layout Standard
5115 There are 6
5116 \begin_inset space ~
5117 \end_inset
5118
5119 rules in editing the docs:
5120 \end_layout
5121
5122 \begin_layout Enumerate
5123 \begin_inset CommandInset label
5124 LatexCommand label
5125 name "enu:If-you-are"
5126
5127 \end_inset
5128
5129 If you are not the maintainer of a doc file or a chapter/section, you MUST
5130  use change tracking so that the maintainer could review your changes
5131 \end_layout
5132
5133 \begin_layout Enumerate
5134 Respect the formatting of the document.
5135  The different files use different formatting styles.
5136  That is OK and has historic reasons nobody fully knows ;-).
5137  But it is important to be consistent within one file.
5138 \end_layout
5139
5140 \begin_layout Enumerate
5141 All changes you make to a file in one language MUST also go the file in
5142  the other actively maintained languages.
5143  Normally the maintainer does this for you, if you are the maintainer, you
5144  must do this by copying or changing the changed or added text to the other
5145  files so that the translators sees the blue underlined text and know what
5146  they have to translate and what was changed.
5147 \end_layout
5148
5149 \begin_layout Enumerate
5150 You MUST assure that the document is compilable as
5151 \begin_inset Quotes eld
5152 \end_inset
5153
5154 PDF (pdflatex)
5155 \begin_inset Quotes erd
5156 \end_inset
5157
5158  or the document's default output format after your changes.
5159 \end_layout
5160
5161 \begin_layout Enumerate
5162 All fixes (typos, compilation fixes, updates info etc.) go at first into
5163  the current GIT branch because the user should benefit from all fixes with
5164  every minor release.
5165  Feel free to commit directly to branch as long as you follow rule
5166 \begin_inset space ~
5167 \end_inset
5168
5169
5170 \begin_inset CommandInset ref
5171 LatexCommand ref
5172 reference "enu:If-you-are"
5173
5174 \end_inset
5175
5176 .
5177  You can immediately commit to master as well.
5178 \end_layout
5179
5180 \begin_layout Enumerate
5181 \begin_inset CommandInset label
5182 LatexCommand label
5183 name "enu:The-fileformat-of"
5184
5185 \end_inset
5186
5187 The fileformat of a file must not be changed unless you document a new feature
5188  in LyX that requires a new fileformat.
5189  The reason for this rule is to keep it easy for the doc maintainers to
5190  port/backport changes to from master/branch.
5191 \end_layout
5192
5193 \begin_layout Standard
5194 The main documentation consists of these files:
5195 \end_layout
5196
5197 \begin_layout Description
5198 splash.lyx it is the first file you see after an installation.
5199  We assume that a new user sees this.
5200  It is therefore designed to be as simple as possible.
5201  Therefore please don't add any new formatting, only fix typos etc.
5202  Splash.lyx is up to date for \SpecialChar LyX
5203  2.1.x, currently maintained by Uwe Stöhr.
5204 \end_layout
5205
5206 \begin_layout Description
5207 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5208 .
5209  It therefore uses a limited set of formatting.
5210  For example a standard document class.
5211  Since new users will first learn about the formatting possibilities of
5212  \SpecialChar LyX
5213  please keep this file that simple.
5214  Intro.lyx is up to date for \SpecialChar LyX
5215  2.1.x, currently maintained by Uwe Stöhr.
5216 \end_layout
5217
5218 \begin_layout Description
5219 Tutorial.lyx our tutorial.
5220  It must be always up to date.
5221  Normally there is nothing to add since we don't want to overwhelm new users
5222  with too much details.
5223  The will learn these details while using \SpecialChar LyX
5224  and we have special manuals.
5225  Tutorial.lyx is up to date for \SpecialChar LyX
5226  2.1.x, currently maintained by Uwe Stöhr.
5227 \end_layout
5228
5229 \begin_layout Description
5230 UserGuide.lyx our main user guide.
5231  It covers a mixture of basic and detailed information.
5232  Some information is also in the Math and EmbeddedObjects manual so that
5233  the UserGuide refers to these files.
5234  UserGuide.lyx is up to date for \SpecialChar LyX
5235  2.1.x, currently maintained by Uwe Stöhr.
5236 \end_layout
5237
5238 \begin_layout Description
5239 EmbeddedObjects.lyx a special manual to explain things like tables floats
5240  boxes etc.
5241  in all detail.
5242  EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5243  2.1.x, currently maintained by Uwe
5244  Stöhr.
5245 \end_layout
5246
5247 \begin_layout Description
5248 Math.lyx a special manual to explain everything regarding math in all detail.
5249  Math.lyx is up to date for \SpecialChar LyX
5250  2.1.x, currently maintained by Uwe Stöhr.
5251 \end_layout
5252
5253 \begin_layout Description
5254 Additional.lyx this manual covers information that would be too much detail
5255  for the UserGuide or would make the UserGuide uncompilable or only compilable
5256  when installing a lot of special \SpecialChar LaTeX
5257 -packages.
5258  What should be in the UserGuide or better in Additional is a matter of
5259  taste.
5260  it is up to you to decide that.
5261  Additional.lyx is not completely up to date for \SpecialChar LyX
5262  2.1.x.
5263  Only chapter
5264 \begin_inset space ~
5265 \end_inset
5266
5267 8 is up to date and currently maintained by Uwe Stöhr.
5268  It certainly needs a rewrite and update.
5269  For example many info in chapter
5270 \begin_inset space ~
5271 \end_inset
5272
5273 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5274  manual.
5275 \end_layout
5276
5277 \begin_layout Description
5278 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5279  for certain
5280  output formats, operating systems, languages etc.
5281  It is currently completely out of date and needs a major rewrite and update.
5282  If you do this please assure that your information are given for all OSes
5283  and \SpecialChar LaTeX
5284  distributions (meaning be as objective as possible).
5285 \end_layout
5286
5287 \end_body
5288 \end_document