lib/doc/Development.lyx

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