lib/doc/Development.lyx

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