lib/doc/Development.lyx

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