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,
3373 \emph on
3374 uninvert
3375 \emph default
3376  the test by removing the pattern from the
3377 \begin_inset Quotes eld
3378 \end_inset
3379
3380 invertedTests
3381 \begin_inset Quotes erd
3382 \end_inset
3383
3384  file (see
3385 \begin_inset CommandInset ref
3386 LatexCommand ref
3387 reference "par:Inverted-tests"
3388
3389 \end_inset
3390
3391 ).
3392 \end_layout
3393
3394 \begin_layout Itemize
3395 If the export did not fail previously but led to wrong output (PDF, say),
3396 \begin_inset Foot
3397 status collapsed
3398
3399 \begin_layout Plain Layout
3400 Non-failing test with wrong output should be labeled as
3401 \begin_inset Quotes eld
3402 \end_inset
3403
3404 unreliable:wrong_output
3405 \begin_inset Quotes erd
3406 \end_inset
3407
3408  (
3409 \begin_inset CommandInset ref
3410 LatexCommand ref
3411 reference "par:Unreliable-tests"
3412
3413 \end_inset
3414
3415 ).
3416 \end_layout
3417
3418 \end_inset
3419
3420  it is in fact an improvement when the test now fails.
3421
3422 \emph on
3423 Invert
3424 \emph default
3425  the failing test case (see
3426 \begin_inset CommandInset ref
3427 LatexCommand ref
3428 reference "par:Inverted-tests"
3429
3430 \end_inset
3431
3432 ).
3433 \end_layout
3434
3435 \begin_layout Itemize
3436 In case of tests failing due to missing requirements (tests labeled
3437 \begin_inset Quotes eld
3438 \end_inset
3439
3440 unreliable:nonstandard
3441 \begin_inset Quotes erd
3442 \end_inset
3443
3444  or testing on a system with only a subset of TeXLive installed), ignore
3445  the failure, ask for someone else to run the test, or install the missing
3446  resources and try again.
3447 \end_layout
3448
3449 \begin_layout Itemize
3450 Check the log file Testing/Temporary/LastTest.log.
3451  In case of latex-errors rerun the failing test with environment variable
3452  'LYX_DEBUG_LATEX' set to '1'.
3453  This will include latex messages in LastTest.log, so it should be easier
3454  to interpret the fail-reason.
3455 \end_layout
3456
3457 \begin_layout Paragraph
3458 \begin_inset CommandInset label
3459 LatexCommand label
3460 name "par:Inverted-tests"
3461
3462 \end_inset
3463
3464 Inverted tests
3465 \end_layout
3466
3467 \begin_layout Standard
3468 Test cases whose name matches a pattern in the file
3469 \begin_inset Flex Code
3470 status collapsed
3471
3472 \begin_layout Plain Layout
3473 development/autotests/invertedTests
3474 \end_layout
3475
3476 \end_inset
3477
3478  get the label
3479 \emph on
3480 inverted
3481 \emph default
3482 .
3483  They get also the test property
3484 \begin_inset Flex Code
3485 status collapsed
3486
3487 \begin_layout Plain Layout
3488 WILL_FAIL
3489 \end_layout
3490
3491 \end_inset
3492
3493 , i.e.
3494  they are reported as failing if the export works without error
3495 \begin_inset Flex URL
3496 status collapsed
3497
3498 \begin_layout Plain Layout
3499
3500 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3501 \end_layout
3502
3503 \end_inset
3504
3505 .
3506 \end_layout
3507
3508 \begin_layout Standard
3509 Add failing cases to this file, if they cannot be solved
3510 \begin_inset Quotes eld
3511 \end_inset
3512
3513 immediately
3514 \begin_inset Quotes erd
3515 \end_inset
3516
3517  but it is expected that the export will work in a foreseeable future, e.g.
3518  low priority issues like failures to export to a non-target format (for
3519  the manuals everything except pdf2).
3520 \end_layout
3521
3522 \begin_layout Standard
3523 The following sublabels are currently present in
3524 \begin_inset Flex Code
3525 status collapsed
3526
3527 \begin_layout Plain Layout
3528 invertedTests
3529 \end_layout
3530
3531 \end_inset
3532
3533 :
3534 \end_layout
3535
3536 \begin_layout Description
3537 todo test failures that require attention:
3538 \end_layout
3539
3540 \begin_deeper
3541 \begin_layout Itemize
3542 minor issues to explore and properly sort later,
3543 \end_layout
3544
3545 \begin_layout Itemize
3546 easyfix issues,
3547 \end_layout
3548
3549 \begin_layout Itemize
3550 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3551 \end_layout
3552
3553 \end_deeper
3554 \begin_layout Description
3555 lyxbugs LyX bugs with a Trac number.
3556 \end_layout
3557
3558 \begin_layout Description
3559 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3560 \end_layout
3561
3562 \begin_deeper
3563 \begin_layout Standard
3564 "Wontfix" if demonstrating correct use and OK in the default output format.
3565 \end_layout
3566
3567 \end_deeper
3568 \begin_layout Description
3569 texissues Export fails due to LaTeX limitations like non-ASCII characters
3570  in verbatim or listings, incompatible packages, ...
3571 \end_layout
3572
3573 \begin_deeper
3574 \begin_layout Standard
3575 "Wontfix" if documents demonstrate correct use in the default output format:
3576 \end_layout
3577
3578 \begin_layout Itemize
3579 If the source can be made more robust without becoming "hackish", fix the
3580  source,
3581 \end_layout
3582
3583 \begin_layout Itemize
3584 if LyX could be enhanced to care for a permanent TeX limitation, file a
3585  ticket at trac and add a pattern under lyxbugs,
3586 \end_layout
3587
3588 \begin_layout Itemize
3589 otherwise, add a pattern here.
3590 \end_layout
3591
3592 \end_deeper
3593 \begin_layout Description
3594 attic Documents in the attic (kept for reference and format conversion test).
3595  Usually
3596 \begin_inset Quotes eld
3597 \end_inset
3598
3599 Wontfix
3600 \begin_inset Quotes erd
3601 \end_inset
3602
3603 .
3604 \end_layout
3605
3606 \begin_layout Subparagraph
3607 suspended tests
3608 \end_layout
3609
3610 \begin_layout Standard
3611 Test cases whose name additionally matches a pattern in the file
3612 \begin_inset Flex Code
3613 status collapsed
3614
3615 \begin_layout Plain Layout
3616 development/autotests/suspendedTests
3617 \end_layout
3618
3619 \end_inset
3620
3621  get the label
3622 \emph on
3623 suspended
3624 \emph default
3625 (instead of
3626 \emph on
3627 export
3628 \emph default
3629 and
3630 \emph on
3631  inverted
3632 \emph default
3633 ).
3634  This means they are not executed using
3635 \begin_inset Flex Code
3636 status collapsed
3637
3638 \begin_layout Plain Layout
3639 ctest -L export
3640 \end_layout
3641
3642 \end_inset
3643
3644  or
3645 \begin_inset Flex Code
3646 status collapsed
3647
3648 \begin_layout Plain Layout
3649 ctest -L inverted
3650 \end_layout
3651
3652 \end_inset
3653
3654 .
3655  However, they also get the test property
3656 \begin_inset Flex Code
3657 status collapsed
3658
3659 \begin_layout Plain Layout
3660 WILL_FAIL
3661 \end_layout
3662
3663 \end_inset
3664
3665 , i.e.
3666  they are reported as failing if the export works without error.
3667  From time to time they still have to be checked using
3668 \begin_inset Flex Code
3669 status collapsed
3670
3671 \begin_layout Plain Layout
3672 ctest -L suspended
3673 \end_layout
3674
3675 \end_inset
3676
3677 .
3678 \end_layout
3679
3680 \begin_layout Standard
3681 These tests are suspended, because the export fails for known reasons which
3682  cannot ATM be resolved.
3683  But it is expected the reason might disappear in the future.
3684  Be it new TL or better handling in \SpecialChar LyX
3685 .
3686 \end_layout
3687
3688 \begin_layout Standard
3689 For ctest commands without the
3690 \begin_inset Flex Code
3691 status collapsed
3692
3693 \begin_layout Plain Layout
3694 -L
3695 \end_layout
3696
3697 \end_inset
3698
3699  parameter nothing changes.
3700  Suspended or not, tests will be executed depending only on the selecting
3701  regular expression given to the ctest command (see
3702 \begin_inset CommandInset ref
3703 LatexCommand ref
3704 reference "par:ctest-options"
3705
3706 \end_inset
3707
3708 ).
3709 \end_layout
3710
3711 \begin_layout Paragraph
3712 \begin_inset CommandInset label
3713 LatexCommand label
3714 name "par:Unreliable-tests"
3715
3716 \end_inset
3717
3718 Unreliable tests
3719 \end_layout
3720
3721 \begin_layout Standard
3722 Test cases whose name matches a pattern in the file
3723 \begin_inset Flex Code
3724 status collapsed
3725
3726 \begin_layout Plain Layout
3727 development/autotests/unreliableTests
3728 \end_layout
3729
3730 \end_inset
3731
3732  get the label
3733 \emph on
3734 unreliable
3735 \emph default
3736 .
3737 \end_layout
3738
3739 \begin_layout Standard
3740 These tests are not executed using
3741 \begin_inset Flex Code
3742 status collapsed
3743
3744 \begin_layout Plain Layout
3745 ctest -L export
3746 \end_layout
3747
3748 \end_inset
3749
3750  or
3751 \begin_inset Flex Code
3752 status collapsed
3753
3754 \begin_layout Plain Layout
3755 ctest -L inverted
3756 \end_layout
3757
3758 \end_inset
3759
3760 .
3761
3762 \end_layout
3763
3764 \begin_layout Standard
3765 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3766  or pass but should rather fail (wrong output).
3767
3768 \begin_inset Note Note
3769 status collapsed
3770
3771 \begin_layout Plain Layout
3772 *invalid* tests (wrong output) are not *unreliable*.
3773  # Use "unfit" or "unapplicable" as better label and name of pattern file?
3774
3775 \end_layout
3776
3777 \end_inset
3778
3779
3780 \end_layout
3781
3782 \begin_layout Standard
3783 The following sublabels are currently present in
3784 \begin_inset Flex Code
3785 status collapsed
3786
3787 \begin_layout Plain Layout
3788 unreliableTests
3789 \end_layout
3790
3791 \end_inset
3792
3793 :
3794 \end_layout
3795
3796 \begin_layout Description
3797 nonstandard Documents with additional requirements, e.g.
3798  a class or package file not in TeXLive.
3799
3800 \begin_inset Note Note
3801 status open
3802
3803 \begin_layout Plain Layout
3804 TODO: rename to
3805 \begin_inset Quotes eld
3806 \end_inset
3807
3808 extra
3809 \begin_inset Quotes erd
3810 \end_inset
3811
3812  or
3813 \begin_inset Quotes eld
3814 \end_inset
3815
3816 exotic
3817 \begin_inset Quotes erd
3818 \end_inset
3819
3820 ?
3821 \end_layout
3822
3823 \end_inset
3824
3825
3826 \end_layout
3827
3828 \begin_layout Description
3829 erratic Tests depending on local configuration or the phase of the moon.
3830
3831 \end_layout
3832
3833 \begin_layout Description
3834 varying_versions Tests depending on e.g.
3835  OS or version of a non-TeX-Live dependency.
3836  Note that a full, up-to-date TeX Live installation is required so this
3837  sublabel is about versions of other dependencies.
3838 \end_layout
3839
3840 \begin_layout Description
3841 wrong
3842 \begin_inset space ~
3843 \end_inset
3844
3845 output Export does not fail but the resulting document has (undetected)
3846  errors.
3847 \end_layout
3848
3849 \begin_deeper
3850 \begin_layout Standard
3851 \paragraph_spacing single
3852 \begin_inset Note Note
3853 status open
3854
3855 \begin_layout Plain Layout
3856 \paragraph_spacing single
3857 These tests are in a strict sense not unreliable but
3858 \emph on
3859 invalid
3860 \emph default
3861  (not measuring what they should measure).
3862 \end_layout
3863
3864 \end_inset
3865
3866
3867 \end_layout
3868
3869 \end_deeper
3870 \begin_layout Paragraph
3871 \begin_inset CommandInset label
3872 LatexCommand label
3873 name "par:Export-test-filtering"
3874
3875 \end_inset
3876
3877 Export test filtering
3878 \end_layout
3879
3880 \begin_layout Standard
3881 The assignment of a label to a test is controlled by a set of files with
3882  regular expressions that are matched against the test names.
3883 \end_layout
3884
3885 \begin_layout Description
3886 ignoredTests (small file)
3887 \begin_inset Newline newline
3888 \end_inset
3889
3890 Tests selected here are withdrawn in the configuration step (cf.
3891
3892 \begin_inset CommandInset ref
3893 LatexCommand ref
3894 reference "par:Configuring-ctests"
3895
3896 \end_inset
3897
3898 ).
3899 \end_layout
3900
3901 \begin_deeper
3902 \begin_layout Labeling
3903 \labelwidthstring 00.00.0000
3904 Input Test of any export combination
3905 \end_layout
3906
3907 \begin_layout Labeling
3908 \labelwidthstring 00.00.0000
3909 Output Stop if tests not selected here
3910 \end_layout
3911
3912 \end_deeper
3913 \begin_layout Description
3914 unreliableTests: Tests selected pass or fail dependent on the system where
3915  the test is run.
3916  Selected tests gain the label 'unreliable'.
3917 \end_layout
3918
3919 \begin_deeper
3920 \begin_layout Labeling
3921 \labelwidthstring 00.00.0000
3922 Input Each test which passed 'ignoredTests'
3923 \end_layout
3924
3925 \begin_layout Labeling
3926 \labelwidthstring 00.00.0000
3927 Output Gain label 'unreliable', proceed with checking for 'inverted'.
3928 \end_layout
3929
3930 \end_deeper
3931 \begin_layout Description
3932 invertedTests
3933 \begin_inset space \space{}
3934 \end_inset
3935
3936
3937 \end_layout
3938
3939 \begin_deeper
3940 \begin_layout Labeling
3941 \labelwidthstring 00.00.0000
3942 Input Each test which passed 'ignoredTests'
3943 \end_layout
3944
3945 \begin_layout Labeling
3946 \labelwidthstring 00.00.0000
3947 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3948  tests are reported as failing if the export works without error.) If no
3949  subselection applies, gain labels 'export' and 'inverted'.
3950 \end_layout
3951
3952 \begin_layout Standard
3953 The following filter perfoms a subselection of 'invertedTests':
3954 \end_layout
3955
3956 \begin_layout Description
3957 suspendedTests Tests selected here gain the label 'suspended' but _not_
3958  'export' or 'inverted', although in ctest they remain inverted.
3959  ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3960 \end_layout
3961
3962 \begin_deeper
3963 \begin_layout Labeling
3964 \labelwidthstring 00.00.0000
3965 Input Each test selected by 'invertedTests'
3966 \end_layout
3967
3968 \begin_layout Labeling
3969 \labelwidthstring 00.00.0000
3970 Output Selected test gains label 'suspended'.
3971
3972 \end_layout
3973
3974 \end_deeper
3975 \end_deeper
3976 \begin_layout Standard
3977 The following table may clarify label assignement
3978 \end_layout
3979
3980 \begin_layout Standard
3981 \begin_inset space \hspace{}
3982 \length -3cm
3983 \end_inset
3984
3985
3986 \begin_inset Tabular
3987 <lyxtabular version="3" rows="6" columns="8">
3988 <features tabularvalignment="middle">
3989 <column alignment="left" valignment="top" width="2cm">
3990 <column alignment="left" valignment="top" width="2.5cm">
3991 <column alignment="left" valignment="top" width="2cm">
3992 <column alignment="center" valignment="top" width="2.5cm">
3993 <column alignment="center" valignment="top">
3994 <column alignment="center" valignment="top">
3995 <column alignment="center" valignment="top">
3996 <column alignment="center" valignment="top">
3997 <row>
3998 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3999 \begin_inset Text
4000
4001 \begin_layout Plain Layout
4002 Test matching pattern in file:
4003 \end_layout
4004
4005 \end_inset
4006 </cell>
4007 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4008 \begin_inset Text
4009
4010 \begin_layout Plain Layout
4011
4012 \end_layout
4013
4014 \end_inset
4015 </cell>
4016 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4017 \begin_inset Text
4018
4019 \begin_layout Plain Layout
4020
4021 \end_layout
4022
4023 \end_inset
4024 </cell>
4025 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4026 \begin_inset Text
4027
4028 \begin_layout Plain Layout
4029
4030 \end_layout
4031
4032 \end_inset
4033 </cell>
4034 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4035 \begin_inset Text
4036
4037 \begin_layout Plain Layout
4038 Assigned label
4039 \end_layout
4040
4041 \end_inset
4042 </cell>
4043 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4044 \begin_inset Text
4045
4046 \begin_layout Plain Layout
4047
4048 \end_layout
4049
4050 \end_inset
4051 </cell>
4052 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4053 \begin_inset Text
4054
4055 \begin_layout Plain Layout
4056
4057 \end_layout
4058
4059 \end_inset
4060 </cell>
4061 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4062 \begin_inset Text
4063
4064 \begin_layout Plain Layout
4065 test property
4066 \end_layout
4067
4068 \end_inset
4069 </cell>
4070 </row>
4071 <row>
4072 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4073 \begin_inset Text
4074
4075 \begin_layout Plain Layout
4076 ignored\SpecialChar softhyphen
4077 Tests
4078 \end_layout
4079
4080 \end_inset
4081 </cell>
4082 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4083 \begin_inset Text
4084
4085 \begin_layout Plain Layout
4086 unreliable\SpecialChar softhyphen
4087 Tests
4088 \end_layout
4089
4090 \end_inset
4091 </cell>
4092 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4093 \begin_inset Text
4094
4095 \begin_layout Plain Layout
4096 inverted\SpecialChar softhyphen
4097 Tests
4098 \end_layout
4099
4100 \end_inset
4101 </cell>
4102 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4103 \begin_inset Text
4104
4105 \begin_layout Plain Layout
4106 suspended\SpecialChar softhyphen
4107 Tests
4108 \end_layout
4109
4110 \end_inset
4111 </cell>
4112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4113 \begin_inset Text
4114
4115 \begin_layout Plain Layout
4116 export
4117 \end_layout
4118
4119 \end_inset
4120 </cell>
4121 <cell alignment="center" valignment="top" topline="true" usebox="none">
4122 \begin_inset Text
4123
4124 \begin_layout Plain Layout
4125 inverted
4126 \end_layout
4127
4128 \end_inset
4129 </cell>
4130 <cell alignment="center" valignment="top" topline="true" usebox="none">
4131 \begin_inset Text
4132
4133 \begin_layout Plain Layout
4134 suspended
4135 \end_layout
4136
4137 \end_inset
4138 </cell>
4139 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4140 \begin_inset Text
4141
4142 \begin_layout Plain Layout
4143
4144 \end_layout
4145
4146 \end_inset
4147 </cell>
4148 </row>
4149 <row>
4150 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4151 \begin_inset Text
4152
4153 \begin_layout Plain Layout
4154 Yes
4155 \end_layout
4156
4157 \end_inset
4158 </cell>
4159 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4160 \begin_inset Text
4161
4162 \begin_layout Plain Layout
4163 -
4164 \end_layout
4165
4166 \end_inset
4167 </cell>
4168 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4169 \begin_inset Text
4170
4171 \begin_layout Plain Layout
4172 -
4173 \end_layout
4174
4175 \end_inset
4176 </cell>
4177 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4178 \begin_inset Text
4179
4180 \begin_layout Plain Layout
4181 -
4182 \end_layout
4183
4184 \end_inset
4185 </cell>
4186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4187 \begin_inset Text
4188
4189 \begin_layout Plain Layout
4190 -
4191 \end_layout
4192
4193 \end_inset
4194 </cell>
4195 <cell alignment="center" valignment="top" topline="true" usebox="none">
4196 \begin_inset Text
4197
4198 \begin_layout Plain Layout
4199 -
4200 \end_layout
4201
4202 \end_inset
4203 </cell>
4204 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4205 \begin_inset Text
4206
4207 \begin_layout Plain Layout
4208 -
4209 \end_layout
4210
4211 \end_inset
4212 </cell>
4213 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4214 \begin_inset Text
4215
4216 \begin_layout Plain Layout
4217
4218 \end_layout
4219
4220 \end_inset
4221 </cell>
4222 </row>
4223 <row>
4224 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4225 \begin_inset Text
4226
4227 \begin_layout Plain Layout
4228 No
4229 \end_layout
4230
4231 \end_inset
4232 </cell>
4233 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4234 \begin_inset Text
4235
4236 \begin_layout Plain Layout
4237 If Yes,
4238 \begin_inset Newline newline
4239 \end_inset
4240
4241 add label
4242 \begin_inset Newline newline
4243 \end_inset
4244
4245 'unreliable'
4246 \end_layout
4247
4248 \end_inset
4249 </cell>
4250 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4251 \begin_inset Text
4252
4253 \begin_layout Plain Layout
4254 Yes
4255 \end_layout
4256
4257 \end_inset
4258 </cell>
4259 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4260 \begin_inset Text
4261
4262 \begin_layout Plain Layout
4263 Yes
4264 \end_layout
4265
4266 \end_inset
4267 </cell>
4268 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4269 \begin_inset Text
4270
4271 \begin_layout Plain Layout
4272 -
4273 \end_layout
4274
4275 \end_inset
4276 </cell>
4277 <cell alignment="center" valignment="top" topline="true" usebox="none">
4278 \begin_inset Text
4279
4280 \begin_layout Plain Layout
4281 -
4282 \end_layout
4283
4284 \end_inset
4285 </cell>
4286 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4287 \begin_inset Text
4288
4289 \begin_layout Plain Layout
4290 +
4291 \end_layout
4292
4293 \end_inset
4294 </cell>
4295 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4296 \begin_inset Text
4297
4298 \begin_layout Plain Layout
4299 WILL_FAIL
4300 \end_layout
4301
4302 \end_inset
4303 </cell>
4304 </row>
4305 <row>
4306 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4307 \begin_inset Text
4308
4309 \begin_layout Plain Layout
4310
4311 \end_layout
4312
4313 \end_inset
4314 </cell>
4315 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4316 \begin_inset Text
4317
4318 \begin_layout Plain Layout
4319
4320 \end_layout
4321
4322 \end_inset
4323 </cell>
4324 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4325 \begin_inset Text
4326
4327 \begin_layout Plain Layout
4328
4329 \end_layout
4330
4331 \end_inset
4332 </cell>
4333 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4334 \begin_inset Text
4335
4336 \begin_layout Plain Layout
4337 No
4338 \end_layout
4339
4340 \end_inset
4341 </cell>
4342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4343 \begin_inset Text
4344
4345 \begin_layout Plain Layout
4346 +
4347 \end_layout
4348
4349 \end_inset
4350 </cell>
4351 <cell alignment="center" valignment="top" topline="true" usebox="none">
4352 \begin_inset Text
4353
4354 \begin_layout Plain Layout
4355 +
4356 \end_layout
4357
4358 \end_inset
4359 </cell>
4360 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4361 \begin_inset Text
4362
4363 \begin_layout Plain Layout
4364 -
4365 \end_layout
4366
4367 \end_inset
4368 </cell>
4369 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4370 \begin_inset Text
4371
4372 \begin_layout Plain Layout
4373 WILL_FAIL
4374 \end_layout
4375
4376 \end_inset
4377 </cell>
4378 </row>
4379 <row>
4380 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4381 \begin_inset Text
4382
4383 \begin_layout Plain Layout
4384
4385 \end_layout
4386
4387 \end_inset
4388 </cell>
4389 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4390 \begin_inset Text
4391
4392 \begin_layout Plain Layout
4393
4394 \end_layout
4395
4396 \end_inset
4397 </cell>
4398 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4399 \begin_inset Text
4400
4401 \begin_layout Plain Layout
4402 No
4403 \end_layout
4404
4405 \end_inset
4406 </cell>
4407 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4408 \begin_inset Text
4409
4410 \begin_layout Plain Layout
4411 -
4412 \end_layout
4413
4414 \end_inset
4415 </cell>
4416 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4417 \begin_inset Text
4418
4419 \begin_layout Plain Layout
4420 +
4421 \end_layout
4422
4423 \end_inset
4424 </cell>
4425 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4426 \begin_inset Text
4427
4428 \begin_layout Plain Layout
4429 -
4430 \end_layout
4431
4432 \end_inset
4433 </cell>
4434 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4435 \begin_inset Text
4436
4437 \begin_layout Plain Layout
4438 -
4439 \end_layout
4440
4441 \end_inset
4442 </cell>
4443 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4444 \begin_inset Text
4445
4446 \begin_layout Plain Layout
4447
4448 \end_layout
4449
4450 \end_inset
4451 </cell>
4452 </row>
4453 </lyxtabular>
4454
4455 \end_inset
4456
4457
4458 \end_layout
4459
4460 \begin_layout Standard
4461 \begin_inset Note Note
4462 status open
4463
4464 \begin_layout Plain Layout
4465 Without the
4466 \begin_inset Quotes eld
4467 \end_inset
4468
4469 suspendedTests
4470 \begin_inset Quotes erd
4471 \end_inset
4472
4473  filter, this would be far less complicated:
4474 \end_layout
4475
4476 \begin_layout Plain Layout
4477 \begin_inset Tabular
4478 <lyxtabular version="3" rows="6" columns="7">
4479 <features tabularvalignment="middle">
4480 <column alignment="left" valignment="top" width="0pt">
4481 <column alignment="left" valignment="top" width="0pt">
4482 <column alignment="left" valignment="top" width="0pt">
4483 <column alignment="center" valignment="top">
4484 <column alignment="center" valignment="top">
4485 <column alignment="center" valignment="top">
4486 <column alignment="center" valignment="top">
4487 <row>
4488 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4489 \begin_inset Text
4490
4491 \begin_layout Plain Layout
4492 Test matching pattern in file:
4493 \end_layout
4494
4495 \end_inset
4496 </cell>
4497 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4498 \begin_inset Text
4499
4500 \begin_layout Plain Layout
4501
4502 \end_layout
4503
4504 \end_inset
4505 </cell>
4506 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4507 \begin_inset Text
4508
4509 \begin_layout Plain Layout
4510
4511 \end_layout
4512
4513 \end_inset
4514 </cell>
4515 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4516 \begin_inset Text
4517
4518 \begin_layout Plain Layout
4519 Label
4520 \end_layout
4521
4522 \end_inset
4523 </cell>
4524 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4525 \begin_inset Text
4526
4527 \begin_layout Plain Layout
4528
4529 \end_layout
4530
4531 \end_inset
4532 </cell>
4533 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4534 \begin_inset Text
4535
4536 \begin_layout Plain Layout
4537
4538 \end_layout
4539
4540 \end_inset
4541 </cell>
4542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4543 \begin_inset Text
4544
4545 \begin_layout Plain Layout
4546 test property
4547 \end_layout
4548
4549 \end_inset
4550 </cell>
4551 </row>
4552 <row>
4553 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4554 \begin_inset Text
4555
4556 \begin_layout Plain Layout
4557 ignoredTests
4558 \end_layout
4559
4560 \end_inset
4561 </cell>
4562 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4563 \begin_inset Text
4564
4565 \begin_layout Plain Layout
4566 unreliableTests
4567 \end_layout
4568
4569 \end_inset
4570 </cell>
4571 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4572 \begin_inset Text
4573
4574 \begin_layout Plain Layout
4575 invertedTests
4576 \end_layout
4577
4578 \end_inset
4579 </cell>
4580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4581 \begin_inset Text
4582
4583 \begin_layout Plain Layout
4584 export
4585 \end_layout
4586
4587 \end_inset
4588 </cell>
4589 <cell alignment="center" valignment="top" topline="true" usebox="none">
4590 \begin_inset Text
4591
4592 \begin_layout Plain Layout
4593 unreliable
4594 \end_layout
4595
4596 \end_inset
4597 </cell>
4598 <cell alignment="center" valignment="top" topline="true" usebox="none">
4599 \begin_inset Text
4600
4601 \begin_layout Plain Layout
4602 inverted
4603 \end_layout
4604
4605 \end_inset
4606 </cell>
4607 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4608 \begin_inset Text
4609
4610 \begin_layout Plain Layout
4611
4612 \end_layout
4613
4614 \end_inset
4615 </cell>
4616 </row>
4617 <row>
4618 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4619 \begin_inset Text
4620
4621 \begin_layout Plain Layout
4622 Yes
4623 \end_layout
4624
4625 \end_inset
4626 </cell>
4627 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4628 \begin_inset Text
4629
4630 \begin_layout Plain Layout
4631 -
4632 \end_layout
4633
4634 \end_inset
4635 </cell>
4636 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4637 \begin_inset Text
4638
4639 \begin_layout Plain Layout
4640 -
4641 \end_layout
4642
4643 \end_inset
4644 </cell>
4645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4646 \begin_inset Text
4647
4648 \begin_layout Plain Layout
4649 -
4650 \end_layout
4651
4652 \end_inset
4653 </cell>
4654 <cell alignment="center" valignment="top" topline="true" usebox="none">
4655 \begin_inset Text
4656
4657 \begin_layout Plain Layout
4658
4659 \end_layout
4660
4661 \end_inset
4662 </cell>
4663 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4664 \begin_inset Text
4665
4666 \begin_layout Plain Layout
4667 -
4668 \end_layout
4669
4670 \end_inset
4671 </cell>
4672 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4673 \begin_inset Text
4674
4675 \begin_layout Plain Layout
4676
4677 \end_layout
4678
4679 \end_inset
4680 </cell>
4681 </row>
4682 <row>
4683 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4684 \begin_inset Text
4685
4686 \begin_layout Plain Layout
4687 No
4688 \end_layout
4689
4690 \end_inset
4691 </cell>
4692 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4693 \begin_inset Text
4694
4695 \begin_layout Plain Layout
4696 Yes
4697 \end_layout
4698
4699 \end_inset
4700 </cell>
4701 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4702 \begin_inset Text
4703
4704 \begin_layout Plain Layout
4705 -
4706 \end_layout
4707
4708 \end_inset
4709 </cell>
4710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4711 \begin_inset Text
4712
4713 \begin_layout Plain Layout
4714 -
4715 \end_layout
4716
4717 \end_inset
4718 </cell>
4719 <cell alignment="center" valignment="top" topline="true" usebox="none">
4720 \begin_inset Text
4721
4722 \begin_layout Plain Layout
4723 +
4724 \end_layout
4725
4726 \end_inset
4727 </cell>
4728 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4729 \begin_inset Text
4730
4731 \begin_layout Plain Layout
4732 -
4733 \end_layout
4734
4735 \end_inset
4736 </cell>
4737 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4738 \begin_inset Text
4739
4740 \begin_layout Plain Layout
4741
4742 \end_layout
4743
4744 \end_inset
4745 </cell>
4746 </row>
4747 <row>
4748 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4749 \begin_inset Text
4750
4751 \begin_layout Plain Layout
4752
4753 \end_layout
4754
4755 \end_inset
4756 </cell>
4757 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4758 \begin_inset Text
4759
4760 \begin_layout Plain Layout
4761 No
4762 \end_layout
4763
4764 \end_inset
4765 </cell>
4766 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4767 \begin_inset Text
4768
4769 \begin_layout Plain Layout
4770 Yes
4771 \end_layout
4772
4773 \end_inset
4774 </cell>
4775 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4776 \begin_inset Text
4777
4778 \begin_layout Plain Layout
4779 +
4780 \end_layout
4781
4782 \end_inset
4783 </cell>
4784 <cell alignment="center" valignment="top" topline="true" usebox="none">
4785 \begin_inset Text
4786
4787 \begin_layout Plain Layout
4788 -
4789 \end_layout
4790
4791 \end_inset
4792 </cell>
4793 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4794 \begin_inset Text
4795
4796 \begin_layout Plain Layout
4797 +
4798 \end_layout
4799
4800 \end_inset
4801 </cell>
4802 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4803 \begin_inset Text
4804
4805 \begin_layout Plain Layout
4806 WILL_FAIL
4807 \end_layout
4808
4809 \end_inset
4810 </cell>
4811 </row>
4812 <row>
4813 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4814 \begin_inset Text
4815
4816 \begin_layout Plain Layout
4817
4818 \end_layout
4819
4820 \end_inset
4821 </cell>
4822 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4823 \begin_inset Text
4824
4825 \begin_layout Plain Layout
4826
4827 \end_layout
4828
4829 \end_inset
4830 </cell>
4831 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4832 \begin_inset Text
4833
4834 \begin_layout Plain Layout
4835 No
4836 \end_layout
4837
4838 \end_inset
4839 </cell>
4840 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4841 \begin_inset Text
4842
4843 \begin_layout Plain Layout
4844 +
4845 \end_layout
4846
4847 \end_inset
4848 </cell>
4849 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4850 \begin_inset Text
4851
4852 \begin_layout Plain Layout
4853 -
4854 \end_layout
4855
4856 \end_inset
4857 </cell>
4858 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4859 \begin_inset Text
4860
4861 \begin_layout Plain Layout
4862 -
4863 \end_layout
4864
4865 \end_inset
4866 </cell>
4867 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4868 \begin_inset Text
4869
4870 \begin_layout Plain Layout
4871
4872 \end_layout
4873
4874 \end_inset
4875 </cell>
4876 </row>
4877 </lyxtabular>
4878
4879 \end_inset
4880
4881
4882 \end_layout
4883
4884 \end_inset
4885
4886
4887 \end_layout
4888
4889 \begin_layout Subsubsection
4890 check_load tests
4891 \end_layout
4892
4893 \begin_layout Standard
4894 These tests check whether a .lyx file loads without any terminal messages.
4895  They correspond to the manual operations of simply opening a .lyx file on
4896  the terminal, exiting LyX once the file is loaded, and then checking whether
4897  there is any output from the terminal.
4898  These tests are useful for catching malformed .lyx files and parsing bugs.
4899  They can also be used to find a .lyx file in which an instance of something
4900  happens.
4901  To do this, compile LyX with a local patch that outputs something to the
4902  terminal when an instance is found, and then run the check_load tests to
4903  see if any fail, which would mean that the situation occurs in the LyX
4904  documentation files corresponding to the failed tests.
4905  These tests are expectedly fragile: any LyX diagnostic message, which is
4906  not necessarily an error, would cause the tests to fail.
4907  Similarly, any message output by a library (e.g.
4908  Qt) would also cause failure.
4909  There are some messages that the check_load tests are instructed to ignore,
4910  which are stored in the file
4911 \begin_inset Flex Code
4912 status collapsed
4913
4914 \begin_layout Plain Layout
4915 development/autotests/filterCheckWarnings
4916 \end_layout
4917
4918 \end_inset
4919
4920 .
4921 \end_layout
4922
4923 \begin_layout Standard
4924 Under cmake, the tests are labeled as 'load'.
4925 \end_layout
4926
4927 \begin_layout Subsubsection
4928 Keytests
4929 \end_layout
4930
4931 \begin_layout Standard
4932 Automated tests based on the "MonKey Testing" keytest program are enabled
4933  if the necessary dependencies are found and if the CMake flag
4934 \begin_inset Flex Code
4935 status collapsed
4936
4937 \begin_layout Plain Layout
4938 -DLYX_ENABLE_KEYTESTS=ON
4939 \end_layout
4940
4941 \end_inset
4942
4943  is used.
4944  They are documented in the README document in
4945 \begin_inset Flex Code
4946 status collapsed
4947
4948 \begin_layout Plain Layout
4949 development/autotests
4950 \end_layout
4951
4952 \end_inset
4953
4954  subfolder of the \SpecialChar LyX
4955  source code distribution.
4956 \end_layout
4957
4958 \begin_layout Subsubsection
4959 lyx21 tests
4960 \end_layout
4961
4962 \begin_layout Standard
4963 These tests combine lyx2lyx tests with check_load tests.
4964  They fail if either fails.
4965 \end_layout
4966
4967 \begin_layout Subsubsection
4968 URL tests
4969 \end_layout
4970
4971 \begin_layout Standard
4972 The URL tests are enabled with the
4973 \begin_inset Flex Code
4974 status collapsed
4975
4976 \begin_layout Plain Layout
4977 -DLYX_ENABLE_URLTESTS=ON
4978 \end_layout
4979
4980 \end_inset
4981
4982  CMake flag and are useful for finding broken links in our documentation
4983  files.
4984  If a URL test fails, to see which link in particular was reported as broken,
4985  see the output in
4986 \begin_inset Flex Code
4987 status collapsed
4988
4989 \begin_layout Plain Layout
4990 LastTest.log
4991 \end_layout
4992
4993 \end_inset
4994
4995 .
4996  These tests are extremely fragile (e.g.
4997  a test can depend on your Internet connection) and a failed URL test should
4998  not be taken too seriously.
4999  URL tests are labeled as
5000 \family typewriter
5001 'url'.
5002 \end_layout
5003
5004 \begin_layout Paragraph
5005 Running URL tests
5006 \end_layout
5007
5008 \begin_layout Standard
5009 cmake is required to run the \SpecialChar LyX
5010  tests, running them is not implemented for
5011  autotools.
5012 \end_layout
5013
5014 \begin_layout Standard
5015 The appropriate commands are:
5016 \end_layout
5017
5018 \begin_layout Itemize
5019
5020 \family typewriter
5021 ctest -L url
5022 \family default
5023
5024 \begin_inset Newline newline
5025 \end_inset
5026
5027 runs all tests with label
5028 \family typewriter
5029 'url'
5030 \end_layout
5031
5032 \begin_layout Itemize
5033
5034 \family typewriter
5035 ctest -R 'check_.*urls'
5036 \family default
5037
5038 \begin_inset Newline newline
5039 \end_inset
5040
5041 runs the tests 'check_accessible_urls'
5042 \end_layout
5043
5044 \begin_layout Standard
5045 Associated test results can be examined in ctest-log directory in files
5046  of the form 'LastFailed.*URLS.log'
5047 \end_layout
5048
5049 \begin_layout Section
5050 Development policies
5051 \end_layout
5052
5053 \begin_layout Standard
5054 This chapter lists some guidelines that should be followed.
5055  This list is not complete, and many guidelines are in separate chapters,
5056  such as
5057 \begin_inset Quotes eld
5058 \end_inset
5059
5060 When is an update of the .lyx file format number needed?
5061 \begin_inset Quotes erd
5062 \end_inset
5063
5064  in Section
5065 \begin_inset CommandInset ref
5066 LatexCommand ref
5067 reference "sec:When-is-an"
5068
5069 \end_inset
5070
5071 .
5072 \end_layout
5073
5074 \begin_layout Subsection
5075 When to set a fixed milestone?
5076 \end_layout
5077
5078 \begin_layout Standard
5079 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5080  holds:
5081 \end_layout
5082
5083 \begin_layout Enumerate
5084 Somebody is actively working on a fix.
5085 \end_layout
5086
5087 \begin_layout Enumerate
5088 The bug is so severe that it would block the release if it is not fixed.
5089 \end_layout
5090
5091 \begin_layout Standard
5092 If a bug is important, but nobody is working on it, and it is no showstopper,
5093  use a milestone like 2.1.x or 2.2.x.
5094  For all other bugs, do not set a milestone at all.
5095 \end_layout
5096
5097 \begin_layout Subsection
5098 Can we add rc entries in stable branch?
5099 \end_layout
5100
5101 \begin_layout Standard
5102 No.
5103  We are supposed to increase the prefs2prefs version number with such things.
5104 \end_layout
5105
5106 \begin_layout Section
5107 \begin_inset CommandInset label
5108 LatexCommand label
5109 name "sec:Documentation-policies"
5110
5111 \end_inset
5112
5113 Documentation policies
5114 \end_layout
5115
5116 \begin_layout Subsection
5117 Rules
5118 \end_layout
5119
5120 \begin_layout Standard
5121 There are 6
5122 \begin_inset space ~
5123 \end_inset
5124
5125 rules in editing the docs:
5126 \end_layout
5127
5128 \begin_layout Enumerate
5129 \begin_inset CommandInset label
5130 LatexCommand label
5131 name "enu:If-you-are"
5132
5133 \end_inset
5134
5135 If you are not the maintainer of a doc file or a chapter/section, you MUST
5136  use change tracking so that the maintainer could review your changes
5137 \end_layout
5138
5139 \begin_layout Enumerate
5140 Respect the formatting of the document.
5141  The different files use different formatting styles.
5142  That is OK and has historic reasons nobody fully knows ;-).
5143  But it is important to be consistent within one file.
5144 \end_layout
5145
5146 \begin_layout Enumerate
5147 All changes you make to a file in one language MUST also go the file in
5148  the other actively maintained languages.
5149  Normally the maintainer does this for you, if you are the maintainer, you
5150  must do this by copying or changing the changed or added text to the other
5151  files so that the translators sees the blue underlined text and know what
5152  they have to translate and what was changed.
5153 \end_layout
5154
5155 \begin_layout Enumerate
5156 You MUST assure that the document is compilable as
5157 \begin_inset Quotes eld
5158 \end_inset
5159
5160 PDF (pdflatex)
5161 \begin_inset Quotes erd
5162 \end_inset
5163
5164  or the document's default output format after your changes.
5165 \end_layout
5166
5167 \begin_layout Enumerate
5168 All fixes (typos, compilation fixes, updates info etc.) go at first into
5169  the current GIT branch because the user should benefit from all fixes with
5170  every minor release.
5171  Feel free to commit directly to branch as long as you follow rule
5172 \begin_inset space ~
5173 \end_inset
5174
5175
5176 \begin_inset CommandInset ref
5177 LatexCommand ref
5178 reference "enu:If-you-are"
5179
5180 \end_inset
5181
5182 .
5183  You can immediately commit to master as well.
5184 \end_layout
5185
5186 \begin_layout Enumerate
5187 \begin_inset CommandInset label
5188 LatexCommand label
5189 name "enu:The-fileformat-of"
5190
5191 \end_inset
5192
5193 The fileformat of a file must not be changed unless you document a new feature
5194  in LyX that requires a new fileformat.
5195  The reason for this rule is to keep it easy for the doc maintainers to
5196  port/backport changes to from master/branch.
5197 \end_layout
5198
5199 \begin_layout Standard
5200 The main documentation consists of these files:
5201 \end_layout
5202
5203 \begin_layout Description
5204 splash.lyx it is the first file you see after an installation.
5205  We assume that a new user sees this.
5206  It is therefore designed to be as simple as possible.
5207  Therefore please don't add any new formatting, only fix typos etc.
5208  Splash.lyx is up to date for \SpecialChar LyX
5209  2.1.x, currently maintained by Uwe Stöhr.
5210 \end_layout
5211
5212 \begin_layout Description
5213 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5214 .
5215  It therefore uses a limited set of formatting.
5216  For example a standard document class.
5217  Since new users will first learn about the formatting possibilities of
5218  \SpecialChar LyX
5219  please keep this file that simple.
5220  Intro.lyx is up to date for \SpecialChar LyX
5221  2.1.x, currently maintained by Uwe Stöhr.
5222 \end_layout
5223
5224 \begin_layout Description
5225 Tutorial.lyx our tutorial.
5226  It must be always up to date.
5227  Normally there is nothing to add since we don't want to overwhelm new users
5228  with too much details.
5229  The will learn these details while using \SpecialChar LyX
5230  and we have special manuals.
5231  Tutorial.lyx is up to date for \SpecialChar LyX
5232  2.1.x, currently maintained by Uwe Stöhr.
5233 \end_layout
5234
5235 \begin_layout Description
5236 UserGuide.lyx our main user guide.
5237  It covers a mixture of basic and detailed information.
5238  Some information is also in the Math and EmbeddedObjects manual so that
5239  the UserGuide refers to these files.
5240  UserGuide.lyx is up to date for \SpecialChar LyX
5241  2.1.x, currently maintained by Uwe Stöhr.
5242 \end_layout
5243
5244 \begin_layout Description
5245 EmbeddedObjects.lyx a special manual to explain things like tables floats
5246  boxes etc.
5247  in all detail.
5248  EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5249  2.1.x, currently maintained by Uwe
5250  Stöhr.
5251 \end_layout
5252
5253 \begin_layout Description
5254 Math.lyx a special manual to explain everything regarding math in all detail.
5255  Math.lyx is up to date for \SpecialChar LyX
5256  2.1.x, currently maintained by Uwe Stöhr.
5257 \end_layout
5258
5259 \begin_layout Description
5260 Additional.lyx this manual covers information that would be too much detail
5261  for the UserGuide or would make the UserGuide uncompilable or only compilable
5262  when installing a lot of special \SpecialChar LaTeX
5263 -packages.
5264  What should be in the UserGuide or better in Additional is a matter of
5265  taste.
5266  it is up to you to decide that.
5267  Additional.lyx is not completely up to date for \SpecialChar LyX
5268  2.1.x.
5269  Only chapter
5270 \begin_inset space ~
5271 \end_inset
5272
5273 8 is up to date and currently maintained by Uwe Stöhr.
5274  It certainly needs a rewrite and update.
5275  For example many info in chapter
5276 \begin_inset space ~
5277 \end_inset
5278
5279 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5280  manual.
5281 \end_layout
5282
5283 \begin_layout Description
5284 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5285  for certain
5286  output formats, operating systems, languages etc.
5287  It is currently completely out of date and needs a major rewrite and update.
5288  If you do this please assure that your information are given for all OSes
5289  and \SpecialChar LaTeX
5290  distributions (meaning be as objective as possible).
5291 \end_layout
5292
5293 \end_body
5294 \end_document