lib/doc/Development.lyx

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