lib/doc/Development.lyx

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