lib/doc/Development.lyx

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