lib/doc/Development.lyx

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