lib/doc/Development.lyx

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