lib/doc/Development.lyx

   1 #LyX 2.4 created this file. For more info see https://www.lyx.org/
   2 \lyxformat 600
   3 \begin_document
   4 \begin_header
   5 \save_transient_properties true
   6 \origin /systemlyxdir/doc/
   7 \textclass scrbook
   8 \options BCOR8mm,captions=tableheading
   9 \use_default_options false
  10 \begin_modules
  11 logicalmkup
  12 \end_modules
  13 \maintain_unincluded_children no
  14 \language english
  15 \language_package default
  16 \inputencoding utf8
  17 \fontencoding auto
  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_roman_osf false
  26 \font_sans_osf false
  27 \font_typewriter_osf false
  28 \font_sf_scale 100 100
  29 \font_tt_scale 100 100
  30 \use_microtype false
  31 \use_dash_ligatures true
  32 \graphics default
  33 \default_output_format pdf2
  34 \output_sync 1
  35 \bibtex_command default
  36 \index_command default
  37 \float_placement class
  38 \float_alignment class
  39 \paperfontsize 12
  40 \spacing single
  41 \use_hyperref true
  42 \pdf_title "LyX's Development manual"
  43 \pdf_author "LyX Team"
  44 \pdf_subject "LyX's development documentation"
  45 \pdf_keywords "LyX, Documentation, Development"
  46 \pdf_bookmarks true
  47 \pdf_bookmarksnumbered true
  48 \pdf_bookmarksopen true
  49 \pdf_bookmarksopenlevel 1
  50 \pdf_breaklinks false
  51 \pdf_pdfborder false
  52 \pdf_colorlinks true
  53 \pdf_backref false
  54 \pdf_pdfusetitle false
  55 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
  56 \papersize a4
  57 \use_geometry false
  58 \use_package amsmath 1
  59 \use_package amssymb 1
  60 \use_package cancel 1
  61 \use_package esint 1
  62 \use_package mathdots 1
  63 \use_package mathtools 1
  64 \use_package mhchem 1
  65 \use_package stackrel 1
  66 \use_package stmaryrd 1
  67 \use_package undertilde 1
  68 \cite_engine basic
  69 \cite_engine_type default
  70 \biblio_style plain
  71 \use_bibtopic false
  72 \use_indices false
  73 \paperorientation portrait
  74 \suppress_date false
  75 \justification true
  76 \use_refstyle 0
  77 \use_minted 0
  78 \use_lineno 0
  79 \notefontcolor #0000ff
  80 \index Index
  81 \shortcut idx
  82 \color #008000
  83 \end_index
  84 \secnumdepth 4
  85 \tocdepth 2
  86 \paragraph_separation indent
  87 \paragraph_indentation default
  88 \is_math_indent 0
  89 \math_numbering_side default
  90 \quotes_style english
  91 \dynamic_quotes 0
  92 \papercolumns 1
  93 \papersides 2
  94 \paperpagestyle headings
  95 \tablestyle default
  96 \tracking_changes false
  97 \output_changes false
  98 \change_bars false
  99 \postpone_fragile_content false
 100 \html_math_output 0
 101 \html_css_as_file 0
 102 \html_be_strict true
 103 \docbook_table_output 0
 104 \end_header
 105
 106 \begin_body
 107
 108 \begin_layout Title
 109 Developing \SpecialChar LyX
 110
 111 \end_layout
 112
 113 \begin_layout Subtitle
 114 Version 2.4.x
 115 \end_layout
 116
 117 \begin_layout Author
 118 by the \SpecialChar LyX
 119  Team
 120 \begin_inset Foot
 121 status collapsed
 122
 123 \begin_layout Plain Layout
 124 If you have comments on or error corrections to this documentation, please
 125  send them to the \SpecialChar LyX
 126  Documentation mailing list:
 127 \begin_inset CommandInset href
 128 LatexCommand href
 129 target "lyx-docs@lists.lyx.org"
 130 type "mailto:"
 131 literal "false"
 132
 133 \end_inset
 134
 135
 136 \end_layout
 137
 138 \end_inset
 139
 140
 141 \end_layout
 142
 143 \begin_layout Standard
 144 \begin_inset CommandInset toc
 145 LatexCommand tableofcontents
 146
 147 \end_inset
 148
 149
 150 \end_layout
 151
 152 \begin_layout Chapter
 153 Introduction
 154 \end_layout
 155
 156 \begin_layout Standard
 157 This manual documents some aspects of \SpecialChar LyX
 158  development.
 159  It is currently rather incomplete, but will hopefully be extended in the
 160  future.
 161  Meanwhile, additional information can be found in the
 162 \begin_inset Flex Code
 163 status collapsed
 164
 165 \begin_layout Plain Layout
 166 development
 167 \end_layout
 168
 169 \end_inset
 170
 171  subfolder of the \SpecialChar LyX
 172  source code distribution.
 173  This document is not translated, since the development language of \SpecialChar LyX
 174  is
 175  English.
 176  If you just want to use \SpecialChar LyX
 177 , then you don't need to read this manual.
 178  However, if you want to learn more about how \SpecialChar LyX
 179  is developed, or even want
 180  to participate in \SpecialChar LyX
 181  development, you may find some interesting information
 182  here.
 183 \end_layout
 184
 185 \begin_layout Chapter
 186 File formats
 187 \end_layout
 188
 189 \begin_layout Standard
 190 \SpecialChar LyX
 191  uses several custom file formats for configuration files and documents.
 192  This chapter contains some background concerning these file formats.
 193  Several file formats are also described in detail in the regular user documenta
 194 tion.
 195 \end_layout
 196
 197 \begin_layout Section
 198 File Format Numbers
 199 \end_layout
 200
 201 \begin_layout Section
 202 When is an update of the .lyx file format number needed?
 203 \begin_inset CommandInset label
 204 LatexCommand label
 205 name "sec:When-is-an"
 206
 207 \end_inset
 208
 209
 210 \end_layout
 211
 212 \begin_layout Standard
 213 When you are working on a new feature you may ask yourself whether it needs
 214  an update of the .lyx file format number.
 215  Whether an update is needed or not is not always obvious.
 216  Rule of thumb:
 217 \end_layout
 218
 219 \begin_layout Quote
 220 Whenever there is the danger that a previous version of LyX cannot open
 221  a file using the new feature, a file format update is needed.
 222 \end_layout
 223
 224 \begin_layout Standard
 225 The file format change allows lyx2lyx rules to implement backwards compatibility.
 226  Below you can find a list of reasons for file format updates with explanations:
 227 \end_layout
 228
 229 \begin_layout Description
 230 New
 231 \begin_inset space ~
 232 \end_inset
 233
 234 document
 235 \begin_inset space ~
 236 \end_inset
 237
 238 setting Whenever you introduce a new setting that is stored in the document
 239  header, a file format update is needed.
 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 valid
 261 \begin_inset space ~
 262 \end_inset
 263
 264 value
 265 \begin_inset space ~
 266 \end_inset
 267
 268 for
 269 \begin_inset space ~
 270 \end_inset
 271
 272 an
 273 \begin_inset space ~
 274 \end_inset
 275
 276 existing
 277 \begin_inset space ~
 278 \end_inset
 279
 280 setting, e.
 281 \begin_inset space \thinspace{}
 282 \end_inset
 283
 284 g.
 285 \end_layout
 286
 287 \begin_deeper
 288 \begin_layout Description
 289 \paragraph_spacing single
 290 Automatically
 291 \begin_inset space ~
 292 \end_inset
 293
 294 loaded
 295 \begin_inset space ~
 296 \end_inset
 297
 298 math
 299 \begin_inset space ~
 300 \end_inset
 301
 302 package The reason for this is that there is no true ERT inset for math
 303  formulas: Each command is parsed, and if a user happens to define a local
 304  command with the same name as a command that triggers an automatic load
 305  of a package, they need to be able to switch off the automatic loading
 306  of that package.
 307  This switch is stored by the
 308 \begin_inset Flex Code
 309 status collapsed
 310
 311 \begin_layout Plain Layout
 312 use_package
 313 \end_layout
 314
 315 \end_inset
 316
 317  header setting.
 318 \end_layout
 319
 320 \begin_layout Description
 321 New
 322 \begin_inset space ~
 323 \end_inset
 324
 325 language that is stored in
 326 \begin_inset Flex Code
 327 status collapsed
 328
 329 \begin_layout Plain Layout
 330
 331 \backslash
 332 language
 333 \end_layout
 334
 335 \end_inset
 336
 337 .
 338
 339 \begin_inset Note Note
 340 status collapsed
 341
 342 \begin_layout Plain Layout
 343 This requirement is under discussion.
 344 \end_layout
 345
 346 \end_inset
 347
 348
 349 \end_layout
 350
 351 \end_deeper
 352 \begin_layout Description
 353 New
 354 \begin_inset space ~
 355 \end_inset
 356
 357 inset Of course a new inset requires a file format update.
 358 \end_layout
 359
 360 \begin_layout Description
 361 New
 362 \begin_inset space ~
 363 \end_inset
 364
 365 style If a new style or inset layout is added to any layout file or module
 366  shipped with \SpecialChar LyX
 367 , then a new file format is needed in the master (development)
 368  branch.
 369  It is possible to backport new styles to the stable version without a file
 370  format change.
 371  See
 372 \begin_inset CommandInset ref
 373 LatexCommand ref
 374 reference "subsec:Backporting-new-styles"
 375
 376 \end_inset
 377
 378  for more information.
 379 \end_layout
 380
 381 \begin_layout Description
 382 Removed
 383 \begin_inset space ~
 384 \end_inset
 385
 386 style If a style or inset layout is removed in any layout file or module
 387  shipped with \SpecialChar LyX
 388 , a new file format is required.
 389 \end_layout
 390
 391 \begin_layout Standard
 392 However,
 393 \series bold
 394 new
 395 \series default
 396  layouts and modules do
 397 \series bold
 398 not
 399 \series default
 400  require a file format update (changed 03/16, see
 401 \begin_inset CommandInset ref
 402 LatexCommand ref
 403 reference "subsec:New-layouts"
 404
 405 \end_inset
 406
 407 ).
 408
 409 \end_layout
 410
 411 \begin_layout Standard
 412 If you are still unsure, please ask on the development list.
 413 \end_layout
 414
 415 \begin_layout Section
 416 \begin_inset CommandInset label
 417 LatexCommand label
 418 name "subsec:update_lyx_files"
 419
 420 \end_inset
 421
 422 How to update the file format number of .lyx files
 423 \end_layout
 424
 425 \begin_layout Standard
 426 Once you come to the conclusion that a file format update is needed, you
 427  should use the following procedure to perform the update:
 428 \end_layout
 429
 430 \begin_layout Enumerate
 431 Implement and test the new feature, including the reading and writing of
 432  .lyx files.
 433  Note that any file produced at this stage does not use a valid format,
 434  so do not use this version of \SpecialChar LyX
 435  for working on any important documents.
 436 \end_layout
 437
 438 \begin_layout Enumerate
 439 \begin_inset CommandInset label
 440 LatexCommand label
 441 name "enu:Describe_format"
 442
 443 \end_inset
 444
 445 Describe the new format in
 446 \begin_inset Flex Code
 447 status collapsed
 448
 449 \begin_layout Plain Layout
 450 development/FORMAT
 451 \end_layout
 452
 453 \end_inset
 454
 455 .
 456 \end_layout
 457
 458 \begin_layout Enumerate
 459 Update the \SpecialChar LyX
 460  file format number in
 461 \begin_inset Flex Code
 462 status collapsed
 463
 464 \begin_layout Plain Layout
 465 src/version.h
 466 \end_layout
 467
 468 \end_inset
 469
 470 .
 471 \end_layout
 472
 473 \begin_layout Enumerate
 474 \begin_inset CommandInset label
 475 LatexCommand label
 476 name "enu:Add-an-entry"
 477
 478 \end_inset
 479
 480 Add an entry to both format lists (for conversion and reversion) in
 481 \begin_inset Newline newline
 482 \end_inset
 483
 484
 485 \begin_inset Flex Code
 486 status collapsed
 487
 488 \begin_layout Plain Layout
 489 lib/lyx2lyx/lyx_2_4.py
 490 \end_layout
 491
 492 \end_inset
 493
 494 .
 495  Add a conversion routine if needed (e.
 496 \begin_inset space \thinspace{}
 497 \end_inset
 498
 499 g., a new header setting always needs a conversion that adds the new setting,
 500  but a new document language does not need one).
 501  Add a reversion routine if needed.
 502
 503 \begin_inset Newline newline
 504 \end_inset
 505
 506 While the conversion routine is required to produce a document that is equivalen
 507 t to the old version, the requirements of the reversion are not that strict.
 508  If possible, try to produce a proper reversion, using ERT if needed, but
 509  for some features this might be too complicated.
 510  In this case, the minimum requirement of the reversion routine is that
 511  it produces a valid document which can be read by an older \SpecialChar LyX
 512 .
 513  If absolutely needed, even data loss is allowed for the reversion.
 514  (In that case, you might want to add a LyX comment that indicates what
 515  you have had to do, so the user is at least warned).
 516 \end_layout
 517
 518 \begin_layout Enumerate
 519 Since tex2lyx has several implicit file format dependencies caused by sharing
 520  code with \SpecialChar LyX
 521 , updating the file format of .lyx files produced by tex2lyx at
 522  the same time as updating the main .lyx file format is strongly recommended.
 523  Therefore, a compiler warning will be issued if the \SpecialChar LyX
 524  and tex2lyx .lyx file
 525  format numbers differ.
 526  In many cases the tex2lyx update requires only the first and last item
 527  of the list below:
 528 \end_layout
 529
 530 \begin_deeper
 531 \begin_layout Enumerate
 532 Update the tex2lyx file format number in
 533 \begin_inset Flex Code
 534 status collapsed
 535
 536 \begin_layout Plain Layout
 537 src/version.h
 538 \end_layout
 539
 540 \end_inset
 541
 542 .
 543 \end_layout
 544
 545 \begin_layout Enumerate
 546 If the lyx2lyx conversion from the old to the new format is empty, or if
 547  tex2lyx does not yet output the changed feature, you do not need any further
 548  tex2lyx changes.
 549  Otherwise, search for the changed feature in tex2lyx, and adjust the output
 550  according to the lyx2lyx changes.
 551 \end_layout
 552
 553 \begin_layout Enumerate
 554 Update the tex2lyx test references as described in
 555 \begin_inset CommandInset ref
 556 LatexCommand formatted
 557 reference "sec:Updating-test-references"
 558
 559 \end_inset
 560
 561 .
 562 \end_layout
 563
 564 \end_deeper
 565 \begin_layout Enumerate
 566 If you did not implement full tex2lyx support for the new feature, add a
 567  line to
 568 \begin_inset Flex Code
 569 status collapsed
 570
 571 \begin_layout Plain Layout
 572 src/tex2lyx/TODO.txt
 573 \end_layout
 574
 575 \end_inset
 576
 577  describing the missing bits.
 578  Note that it is perfectly fine if you do not add full tex2lyx support for
 579  a new feature: The updating recommendation above is only issued for the
 580  syntax of the produced .lyx file.
 581  It is no problem if some features supported by \SpecialChar LyX
 582  are still output as ERT
 583  by tex2lyx.
 584  The problems in the past that resulted in the update recommendation were
 585  related to mixed version syntax, not ERT.
 586 \end_layout
 587
 588 \begin_layout Enumerate
 589 It would be nice if you could create a .lyx test file which contains instances
 590  of all changed or added features.
 591  This could then be used to test lyx2lyx and tex2lyx.
 592  Test samples are collected under the corresponding subdirectories of
 593 \family typewriter
 594 /autotests
 595 \family default
 596 .
 597 \end_layout
 598
 599 \begin_layout Enumerate
 600 \begin_inset CommandInset label
 601 LatexCommand label
 602 name "enu:updatefiles"
 603
 604 \end_inset
 605
 606 Test your lyx2lyx code by updating LyX's .lyx documentation files to the
 607  new format.
 608  The developer who makes the change knows best what changes to expect when
 609  inspecting the resulting diff.
 610  Because of this, you might be able to catch a bug in the lyx2lyx code that
 611  updates the format just by taking a quick scan through the large diff that
 612  is the result.
 613 \begin_inset Note Note
 614 status collapsed
 615
 616 \begin_layout Plain Layout
 617 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
 618  see which layout update made an unexpected change by looking at the git
 619  log of a .lyx file that suffers the problem.
 620 \end_layout
 621
 622 \end_inset
 623
 624  To do this, first make sure that there are no changes to the git repository
 625  that you will not want to commit (this is needed because it will be convenient
 626  to commit with the command
 627 \begin_inset Flex Code
 628 status collapsed
 629
 630 \begin_layout Plain Layout
 631 git commit -a
 632 \end_layout
 633
 634 \end_inset
 635
 636 ).
 637  Then run the following command in the root folder of the source:
 638 \begin_inset Flex Code
 639 status collapsed
 640
 641 \begin_layout Plain Layout
 642 python development/tools/updatedocs.py
 643 \end_layout
 644
 645 \end_inset
 646
 647 .
 648  Look at the resulting changes using the command
 649 \begin_inset Flex Code
 650 status collapsed
 651
 652 \begin_layout Plain Layout
 653 git diff
 654 \end_layout
 655
 656 \end_inset
 657
 658 .
 659  If anything looks surprising, please investigate.
 660  Keep in mind that the case of
 661 \begin_inset Flex Code
 662 status collapsed
 663
 664 \begin_layout Plain Layout
 665 LFUNs.lyx
 666 \end_layout
 667
 668 \end_inset
 669
 670  is special, because it is first generated with
 671 \begin_inset Flex Code
 672 status collapsed
 673
 674 \begin_layout Plain Layout
 675 gen_lfuns.py
 676 \end_layout
 677
 678 \end_inset
 679
 680  before being converted to the latest format.
 681 \begin_inset Newline newline
 682 \end_inset
 683
 684
 685 \begin_inset Note Greyedout
 686 status open
 687
 688 \begin_layout Plain Layout
 689
 690 \series bold
 691 Note:
 692 \series default
 693  Only commit file format changes in the doc files if these files are using
 694  the new feature of the new file format.
 695  The reason is rule
 696 \begin_inset space ~
 697 \end_inset
 698
 699
 700 \begin_inset CommandInset ref
 701 LatexCommand ref
 702 reference "enu:The-fileformat-of"
 703
 704 \end_inset
 705
 706  of the documentation policies described in sec.
 707 \begin_inset space ~
 708 \end_inset
 709
 710
 711 \begin_inset CommandInset ref
 712 LatexCommand ref
 713 reference "sec:Documentation-policies"
 714
 715 \end_inset
 716
 717 .
 718 \end_layout
 719
 720 \end_inset
 721
 722
 723 \end_layout
 724
 725 \begin_layout Enumerate
 726 Finally, commit using
 727 \begin_inset Flex Code
 728 status collapsed
 729
 730 \begin_layout Plain Layout
 731 git commit -a
 732 \end_layout
 733
 734 \end_inset
 735
 736 .
 737 \end_layout
 738
 739 \begin_layout Section
 740 Updating the file format number of layout files
 741 \end_layout
 742
 743 \begin_layout Standard
 744 The procedure for updating the layout files is similar to that in step
 745 \begin_inset CommandInset ref
 746 LatexCommand ref
 747 reference "enu:updatefiles"
 748
 749 \end_inset
 750
 751  in section
 752 \begin_inset CommandInset ref
 753 LatexCommand ref
 754 reference "subsec:update_lyx_files"
 755
 756 \end_inset
 757
 758 .
 759  One need only run
 760 \begin_inset Flex Code
 761 status collapsed
 762
 763 \begin_layout Plain Layout
 764 python development/tools/updatelayouts.py
 765 \end_layout
 766
 767 \end_inset
 768
 769  instead of
 770 \begin_inset Flex Code
 771 status collapsed
 772
 773 \begin_layout Plain Layout
 774 updatedocs.py
 775 \end_layout
 776
 777 \end_inset
 778
 779 .
 780 \end_layout
 781
 782 \begin_layout Standard
 783 Note that we do not automatically update any local layout used in the
 784 \begin_inset Flex Code
 785 status collapsed
 786
 787 \begin_layout Plain Layout
 788 .lyx
 789 \end_layout
 790
 791 \end_inset
 792
 793  files shipped with \SpecialChar LyX
 794  because users would then not be able to export to older
 795  formats.
 796  For example, if a 2.2.0 user exported a template to 2.1.x format and tried
 797  to open the file in \SpecialChar LyX
 798  2.1.x, there would be an error because the file would
 799  contain a local layout whose format is too new.
 800  The root reason for this is that we do not support converting layouts to
 801  older layout formats, as we do for the
 802 \begin_inset Flex Code
 803 status collapsed
 804
 805 \begin_layout Plain Layout
 806 .lyx
 807 \end_layout
 808
 809 \end_inset
 810
 811  file format.
 812 \end_layout
 813
 814 \begin_layout Section
 815 Updating the file format number of bind/ui files
 816 \end_layout
 817
 818 \begin_layout Standard
 819 A change to the functionality of existing LFUNs can require a conversion
 820  of
 821 \begin_inset Flex Code
 822 status collapsed
 823
 824 \begin_layout Plain Layout
 825 .bind
 826 \end_layout
 827
 828 \end_inset
 829
 830  and
 831 \begin_inset Flex Code
 832 status collapsed
 833
 834 \begin_layout Plain Layout
 835 .ui
 836 \end_layout
 837
 838 \end_inset
 839
 840  files, and therefore an increment of the LFUN format, as well as a conversion
 841  of Info insets in
 842 \begin_inset Flex Code
 843 status collapsed
 844
 845 \begin_layout Plain Layout
 846 .lyx
 847 \end_layout
 848
 849 \end_inset
 850
 851  files for manuals.
 852  The latter cannot be done automatically and also requires an update of
 853  the \SpecialChar LyX
 854  file format.
 855  (Think e.g.
 856 \begin_inset space \space{}
 857 \end_inset
 858
 859 of someone who might have made a set of \SpecialChar LyX
 860  teaching manuals for use in their
 861  own group.)
 862 \begin_inset Foot
 863 status open
 864
 865 \begin_layout Plain Layout
 866 \begin_inset Flex URL
 867 status open
 868
 869 \begin_layout Plain Layout
 870
 871 https://www.lyx.org/trac/ticket/9794
 872 \end_layout
 873
 874 \end_inset
 875
 876
 877 \end_layout
 878
 879 \end_inset
 880
 881
 882 \end_layout
 883
 884 \begin_layout Standard
 885 To update the LFUN format:
 886 \end_layout
 887
 888 \begin_layout Enumerate
 889 Increment the LFUN file format number in
 890 \begin_inset Flex Code
 891 status collapsed
 892
 893 \begin_layout Plain Layout
 894 src/LyXAction.h
 895 \end_layout
 896
 897 \end_inset
 898
 899 .
 900 \end_layout
 901
 902 \begin_layout Enumerate
 903 Implement the LFUN conversion in
 904 \begin_inset Flex Code
 905 status collapsed
 906
 907 \begin_layout Plain Layout
 908 lib/scripts/prefs2prefs_lfuns.py
 909 \end_layout
 910
 911 \end_inset
 912
 913 .
 914 \end_layout
 915
 916 \begin_layout Enumerate
 917 See step
 918 \begin_inset CommandInset ref
 919 LatexCommand ref
 920 reference "enu:updatefiles"
 921
 922 \end_inset
 923
 924  in section
 925 \begin_inset CommandInset ref
 926 LatexCommand ref
 927 reference "subsec:update_lyx_files"
 928
 929 \end_inset
 930
 931  but instead of the
 932 \begin_inset Flex Code
 933 status collapsed
 934
 935 \begin_layout Plain Layout
 936 updatedocs.py
 937 \end_layout
 938
 939 \end_inset
 940
 941  command, use this command:
 942 \begin_inset Flex Code
 943 status collapsed
 944
 945 \begin_layout Plain Layout
 946 bash development/tools/updatelfuns.sh
 947 \end_layout
 948
 949 \end_inset
 950
 951 .
 952
 953 \begin_inset Note Note
 954 status open
 955
 956 \begin_layout Plain Layout
 957 This file should really be converted to python.
 958 \end_layout
 959
 960 \end_inset
 961
 962
 963 \end_layout
 964
 965 \begin_layout Enumerate
 966 Update Info insets in
 967 \begin_inset Flex Code
 968 status collapsed
 969
 970 \begin_layout Plain Layout
 971 .lyx
 972 \end_layout
 973
 974 \end_inset
 975
 976  files.
 977  To do so, increment the \SpecialChar LyX
 978  format and proceed as in
 979 \begin_inset CommandInset ref
 980 LatexCommand ref
 981 reference "subsec:update_lyx_files"
 982
 983 \end_inset
 984
 985 , steps
 986 \begin_inset CommandInset ref
 987 LatexCommand ref
 988 reference "enu:Describe_format"
 989
 990 \end_inset
 991
 992 –
 993 \begin_inset CommandInset ref
 994 LatexCommand ref
 995 reference "enu:updatefiles"
 996
 997 \end_inset
 998
 999 .
1000  In the lyx2lyx implementation (step
1001 \begin_inset CommandInset ref
1002 LatexCommand ref
1003 reference "enu:Add-an-entry"
1004
1005 \end_inset
1006
1007 ), implement a conversion similar to the one in
1008 \begin_inset Flex Code
1009 status collapsed
1010
1011 \begin_layout Plain Layout
1012 prefs2prefs_lfuns.py
1013 \end_layout
1014
1015 \end_inset
1016
1017  above, as well as a corresponding reversion; for this one can use
1018 \begin_inset Flex Code
1019 status collapsed
1020
1021 \begin_layout Plain Layout
1022 convert_info_insets
1023 \end_layout
1024
1025 \end_inset
1026
1027  from
1028 \begin_inset Flex Code
1029 status collapsed
1030
1031 \begin_layout Plain Layout
1032 lib/lyx2lyx/lyx2lyx_tools.py
1033 \end_layout
1034
1035 \end_inset
1036
1037 .
1038
1039 \end_layout
1040
1041 \begin_layout Section
1042 Backporting new styles to the stable version
1043 \begin_inset CommandInset label
1044 LatexCommand label
1045 name "subsec:Backporting-new-styles"
1046
1047 \end_inset
1048
1049
1050 \end_layout
1051
1052 \begin_layout Standard
1053 Starting with the stable \SpecialChar LyX
1054  2.1 branch, there is a mechanism in place to backport
1055  new styles to the stable version without the need to update the file format.
1056  The basic idea is that the new style definition is automatically copied
1057  to the document preamble so that it can even be used by older minor versions
1058  that did not yet include the style.
1059  To backport a new style to the stable version, the following steps are
1060  needed:
1061 \end_layout
1062
1063 \begin_layout Enumerate
1064 Add the line
1065 \begin_inset Flex Code
1066 status collapsed
1067
1068 \begin_layout Plain Layout
1069 ForceLocal -1
1070 \end_layout
1071
1072 \end_inset
1073
1074  to the style definition in the development version.
1075 \end_layout
1076
1077 \begin_layout Enumerate
1078 Copy the style definition to the stable version, but use
1079 \begin_inset Flex Code
1080 status collapsed
1081
1082 \begin_layout Plain Layout
1083 ForceLocal 1
1084 \end_layout
1085
1086 \end_inset
1087
1088  instead.
1089  If needed adjust the format to the one used by the stable version (see
1090  the customization manual for details of the layout file format).
1091 \end_layout
1092
1093 \begin_layout Enumerate
1094 For each update of the style in a later stable version, increase the argument
1095  of
1096 \begin_inset Flex Code
1097 status collapsed
1098
1099 \begin_layout Plain Layout
1100 ForceLocal
1101 \end_layout
1102
1103 \end_inset
1104
1105  by one.
1106  (In the stable version, the development version should not be touched.)
1107 \end_layout
1108
1109 \begin_layout Standard
1110 For details about the
1111 \begin_inset Flex Code
1112 status collapsed
1113
1114 \begin_layout Plain Layout
1115 ForceLocal
1116 \end_layout
1117
1118 \end_inset
1119
1120  flag see the customization manual.
1121  No
1122 \begin_inset Flex Code
1123 status collapsed
1124
1125 \begin_layout Plain Layout
1126 lyx2lyx
1127 \end_layout
1128
1129 \end_inset
1130
1131  support is needed for backported styles: Since the style of the development
1132  version has an infinite version number, it will always be used.
1133  Furthermore, since its version number is less than one, the style will
1134  not be written anymore to the document header for files saved by the new
1135  version.
1136 \end_layout
1137
1138 \begin_layout Chapter
1139 New layouts and modules
1140 \end_layout
1141
1142 \begin_layout Section
1143 \begin_inset CommandInset label
1144 LatexCommand label
1145 name "subsec:New-layouts"
1146
1147 \end_inset
1148
1149 New layouts
1150 \end_layout
1151
1152 \begin_layout Standard
1153 Adding a new layout file to the \SpecialChar LyX
1154  library makes it an
1155 \begin_inset Quotes eld
1156 \end_inset
1157
1158 officially supported
1159 \begin_inset Quotes erd
1160 \end_inset
1161
1162  layout.
1163  You should therefore think carefully about whether you really want to do
1164  this and discuss it on lyx-devel, since you will need to be prepared to
1165  update and fix the layout if necessary.
1166  If the layout is experimental or for a rarely used document class, then
1167  it may be better to add it to the relevant portion of the \SpecialChar LyX
1168  wiki, as a user
1169  contribution.
1170  See
1171 \begin_inset CommandInset href
1172 LatexCommand href
1173 target "https://wiki.lyx.org/Layouts/Layouts"
1174 literal "false"
1175
1176 \end_inset
1177
1178 .
1179 \end_layout
1180
1181 \begin_layout Standard
1182 In older versions of this document, it was stated that new layout files
1183  require a file format change.
1184  After some discussion, it was decided that this is not needed.
1185 \begin_inset Foot
1186 status open
1187
1188 \begin_layout Plain Layout
1189 See
1190 \begin_inset CommandInset href
1191 LatexCommand href
1192 name "the thread “Proposal for a guide on updating layouts”"
1193 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1194 literal "false"
1195
1196 \end_inset
1197
1198 .
1199 \end_layout
1200
1201 \end_inset
1202
1203
1204 \end_layout
1205
1206 \begin_layout Quote
1207 For reference, here are the arguments on each side
1208 \end_layout
1209
1210 \begin_deeper
1211 \begin_layout Description
1212 Pro
1213 \begin_inset Quotes eld
1214 \end_inset
1215
1216 New layout files are a file format change
1217 \begin_inset Quotes erd
1218 \end_inset
1219
1220
1221 \end_layout
1222
1223 \begin_layout Itemize
1224 All documents produced by 2.2.
1225 \begin_inset Formula $x$
1226 \end_inset
1227
1228  can always be edited and exported even if
1229 \begin_inset Formula $x$
1230 \end_inset
1231
1232  is different.
1233  This is important for people using different machines, or exchanging work
1234  with colleagues.
1235 \end_layout
1236
1237 \begin_layout Description
1238 Con
1239 \begin_inset Quotes eld
1240 \end_inset
1241
1242 New layout files are not a file format change
1243 \begin_inset Quotes erd
1244 \end_inset
1245
1246
1247 \end_layout
1248
1249 \begin_layout Itemize
1250 No new LaTeX classes can be supported in a stable version, and stable versions
1251  have a typical lifetime of 2–3 years.
1252 \end_layout
1253
1254 \begin_layout Itemize
1255 We have the same situation already with custom layout files: If a document
1256  using a custom layout file is moved between machines or people, then the
1257  layout file needs to be exchanged as well.
1258  If that is not done, then we have a fallback implemented so that such documents
1259  can still be edited, but not exported, and the user gets a warning.
1260
1261 \end_layout
1262
1263 \begin_layout Itemize
1264 The lyx2lyx script cannot do anything useful in such a case.
1265 \end_layout
1266
1267 \end_deeper
1268 \begin_layout Standard
1269 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1270  itself,
1271  then, you should do the following:
1272 \end_layout
1273
1274 \begin_layout Enumerate
1275 Put your new layout file in
1276 \begin_inset Flex Code
1277 status collapsed
1278
1279 \begin_layout Plain Layout
1280 lib/layouts/
1281 \end_layout
1282
1283 \end_inset
1284
1285  and add it to Git (
1286 \begin_inset Flex Code
1287 status collapsed
1288
1289 \begin_layout Plain Layout
1290 git add lib/layouts/newlayout.layout
1291 \end_layout
1292
1293 \end_inset
1294
1295 ) so that it will be committed.
1296 \end_layout
1297
1298 \begin_layout Enumerate
1299 Add an entry in
1300 \begin_inset Flex Code
1301 status collapsed
1302
1303 \begin_layout Plain Layout
1304 lib/Makefile.am
1305 \end_layout
1306
1307 \end_inset
1308
1309 , so that the new layout actually gets installed.
1310 \end_layout
1311
1312 \begin_layout Enumerate
1313 Add an entry in
1314 \begin_inset Flex Code
1315 status collapsed
1316
1317 \begin_layout Plain Layout
1318 lib/doc/LaTeXConfig.lyx
1319 \end_layout
1320
1321 \end_inset
1322
1323  containing in particular a line like
1324 \end_layout
1325
1326 \begin_deeper
1327 \begin_layout Quote
1328 Found: [InsetInfo]
1329 \end_layout
1330
1331 \begin_layout Standard
1332 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1333 \begin_inset Flex Code
1334 status collapsed
1335
1336 \begin_layout Plain Layout
1337 info-insert textclass <name>
1338 \end_layout
1339
1340 \end_inset
1341
1342 .
1343  This inset will automatically display a boxed
1344 \begin_inset Quotes eld
1345 \end_inset
1346
1347 yes
1348 \begin_inset Quotes erd
1349 \end_inset
1350
1351  or
1352 \begin_inset Quotes eld
1353 \end_inset
1354
1355 no
1356 \begin_inset Quotes erd
1357 \end_inset
1358
1359  depending on the availability of the package.
1360 \end_layout
1361
1362 \end_deeper
1363 \begin_layout Enumerate
1364 A template or example is strongly encouraged (but not necessarily required).
1365  It is also possible to provide both.
1366  Add them to
1367 \begin_inset Flex Code
1368 status collapsed
1369
1370 \begin_layout Plain Layout
1371 lib/templates/
1372 \end_layout
1373
1374 \end_inset
1375
1376  or
1377 \begin_inset Flex Code
1378 status collapsed
1379
1380 \begin_layout Plain Layout
1381 lib/examples/
1382 \end_layout
1383
1384 \end_inset
1385
1386 , respectively.
1387 \end_layout
1388
1389 \begin_layout Enumerate
1390 Reconfigure \SpecialChar LyX
1391 .
1392 \end_layout
1393
1394 \begin_layout Enumerate
1395 Ensure the autotests for the new layout pass (see
1396 \begin_inset CommandInset ref
1397 LatexCommand ref
1398 reference "par:when-to-run-an-export-test"
1399
1400 \end_inset
1401
1402 ).
1403 \end_layout
1404
1405 \begin_layout Section
1406 New modules
1407 \end_layout
1408
1409 \begin_layout Standard
1410 Adding a new module is very similar to adding a new layout.
1411  Therefore, the previous section applies to new modules as well, with two
1412  exceptions:
1413 \end_layout
1414
1415 \begin_layout Enumerate
1416 You only need to add an entry to
1417 \begin_inset Flex Code
1418 status collapsed
1419
1420 \begin_layout Plain Layout
1421 lib/doc/LaTeXConfig.lyx
1422 \end_layout
1423
1424 \end_inset
1425
1426  if the module requires a LaTeX package.
1427  In that case, the command for entering the InsetInfo is:
1428 \begin_inset Flex Code
1429 status collapsed
1430
1431 \begin_layout Plain Layout
1432 info-insert package <name>
1433 \end_layout
1434
1435 \end_inset
1436
1437
1438 \end_layout
1439
1440 \begin_layout Enumerate
1441 Modules do not need a template, only an example, which is strongly encouraged
1442  but not necessarily required.
1443 \end_layout
1444
1445 \begin_layout Section
1446 Layouts for document classes with incompatible versions
1447 \end_layout
1448
1449 \begin_layout Standard
1450 \begin_inset Note Greyedout
1451 status open
1452
1453 \begin_layout Description
1454 Note: This section is currently only a proposal under discussion.
1455  Please correct/amend as suited.
1456  Remove this note once a consensus is found.
1457 \end_layout
1458
1459 \begin_layout Plain Layout
1460 See the thread
1461 \begin_inset Quotes eld
1462 \end_inset
1463
1464 Proposal for a guide on updating layouts
1465 \begin_inset Quotes erd
1466 \end_inset
1467
1468  for details and background
1469 \end_layout
1470
1471 \begin_layout Plain Layout
1472 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1473 \end_layout
1474
1475 \end_inset
1476
1477
1478 \end_layout
1479
1480 \begin_layout Standard
1481 Every now and then, there are changes to LaTeX document classes that break
1482  backwards compatibility.
1483 \begin_inset Foot
1484 status collapsed
1485
1486 \begin_layout Plain Layout
1487 Uwe has suggested we implement automatic detection of changes in class files.
1488  This could be done by running a script every month that checks if a document
1489  class was changed at CTAN and at the homepages of the scientific journals.
1490  If it reports a change, we can check if our template and layout file are
1491  still usable with the changed document class.
1492  (This is different from the autotests insofar, as this would also catch
1493  changes that do not result in compilation errors.)
1494 \end_layout
1495
1496 \end_inset
1497
1498  Reasons can be a new name for the
1499 \begin_inset Flex Code
1500 status collapsed
1501
1502 \begin_layout Plain Layout
1503 *.cls
1504 \end_layout
1505
1506 \end_inset
1507
1508  file, removed \SpecialChar LaTeX
1509  commands, or both.
1510  How should this best be handled in \SpecialChar LyX
1511 ?
1512 \end_layout
1513
1514 \begin_layout Standard
1515 The idea is to support the new version with a new \SpecialChar LyX
1516  layout so that:
1517 \end_layout
1518
1519 \begin_layout Itemize
1520 Existing documents can still be opened in \SpecialChar LyX
1521  and will continue to work on
1522  systems where the old version is still installed.
1523
1524 \end_layout
1525
1526 \begin_layout Itemize
1527 With differently named
1528 \begin_inset Flex Code
1529 status collapsed
1530
1531 \begin_layout Plain Layout
1532 *.cls
1533 \end_layout
1534
1535 \end_inset
1536
1537  files, \SpecialChar LyX
1538  can check for the availability of the particular version and reflect
1539  this in the GUI.
1540  Different document class versions with the same file name are currently
1541  (2.2.x) not detected by the configuration script.
1542  This is planned for 2.3.
1543 \begin_inset Foot
1544 status collapsed
1545
1546 \begin_layout Plain Layout
1547 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1548 \end_layout
1549
1550 \begin_layout Plain Layout
1551 However, what we really need is version detection for the configuration,
1552  so that the user can be warned if the required class file has the wrong
1553  version.
1554  (If the class file keeps the name over the version change, only one of
1555  the two layout files generates compilable documents.)
1556 \end_layout
1557
1558 \begin_layout Plain Layout
1559 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1560 798
1561 \end_layout
1562
1563 \end_inset
1564
1565
1566 \end_layout
1567
1568 \begin_layout Itemize
1569 The new layout can be added both to the master and the stable branches,
1570  in accord with the policy discussed in
1571 \begin_inset CommandInset ref
1572 LatexCommand formatted
1573 reference "subsec:New-layouts"
1574
1575 \end_inset
1576
1577 .
1578  No lyx2lyx conversion is then required when a new major version is released.
1579 \end_layout
1580
1581 \begin_layout Standard
1582 The user can move an existing document to the new version simply by selecting
1583  a new document class.
1584  This step is well supported by \SpecialChar LyX
1585 , with established methods for handling
1586  unsupported styles and other changes.
1587  This way, no lyx2lyx code is required.
1588 \end_layout
1589
1590 \begin_layout Standard
1591 The steps to support a new version of an existing document class are thus:
1592 \end_layout
1593
1594 \begin_layout Itemize
1595 Create a new layout file including the upstream version in the name (avoid
1596  special characters like spaces and dots), e.g.
1597
1598 \begin_inset Flex Code
1599 status collapsed
1600
1601 \begin_layout Plain Layout
1602 acmsiggraph-v0-92.layout
1603 \end_layout
1604
1605 \end_inset
1606
1607 .
1608 \end_layout
1609
1610 \begin_layout Itemize
1611 Include the name of the
1612 \begin_inset Flex Code
1613 status collapsed
1614
1615 \begin_layout Plain Layout
1616 *.cls
1617 \end_layout
1618
1619 \end_inset
1620
1621  file as an optional argument in the
1622 \begin_inset Flex Code
1623 status collapsed
1624
1625 \begin_layout Plain Layout
1626
1627 \backslash
1628 DeclareLaTeXClass
1629 \end_layout
1630
1631 \end_inset
1632
1633  line and include the version number in the GUI name:
1634 \begin_inset Newline newline
1635 \end_inset
1636
1637
1638 \begin_inset Flex Code
1639 status collapsed
1640
1641 \begin_layout Plain Layout
1642
1643 \backslash
1644 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1645 \begin_inset space ~
1646 \end_inset
1647
1648 0.92)}
1649 \end_layout
1650
1651 \end_inset
1652
1653
1654 \end_layout
1655
1656 \begin_layout Itemize
1657 Update the GUI name in the old layout file (whose name should not be changed),
1658  e.g.:
1659 \begin_inset Newline newline
1660 \end_inset
1661
1662
1663 \begin_inset Flex Code
1664 status collapsed
1665
1666 \begin_layout Plain Layout
1667
1668 \backslash
1669 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1670 \begin_inset space ~
1671 \end_inset
1672
1673 0.91, obsolete)}
1674 \end_layout
1675
1676 \end_inset
1677
1678
1679 \end_layout
1680
1681 \begin_layout Itemize
1682 To avoid duplicate definitions, the new layout can
1683 \begin_inset Flex Code
1684 status collapsed
1685
1686 \begin_layout Plain Layout
1687 Input
1688 \end_layout
1689
1690 \end_inset
1691
1692  the old layout file and add\SpecialChar breakableslash
1693 remove\SpecialChar breakableslash
1694 obsolete\SpecialChar breakableslash
1695 modify settings and styles (similar
1696  to the inclusion of
1697 \begin_inset Flex Code
1698 status collapsed
1699
1700 \begin_layout Plain Layout
1701 *.inc
1702 \end_layout
1703
1704 \end_inset
1705
1706  files).
1707 \end_layout
1708
1709 \begin_deeper
1710 \begin_layout Standard
1711 It may be tempting to let the new layout be the
1712 \begin_inset Quotes eld
1713 \end_inset
1714
1715 master version
1716 \begin_inset Quotes erd
1717 \end_inset
1718
1719  and have the old layout import it.
1720  However, this should not be done because any changes to the new layout
1721  would need undo steps in the importing old layout.
1722 \end_layout
1723
1724 \end_deeper
1725 \begin_layout Itemize
1726 If the new LaTeX document class obsoletes the old one, update the example
1727  and template files to use the new layout.
1728  Add a note about the changes (preferably with a pointer to the documentation
1729  of the changes).
1730 \end_layout
1731
1732 \begin_deeper
1733 \begin_layout Standard
1734 This way, new documents based on the template or example will use the up-to-date
1735  document class version.
1736 \end_layout
1737
1738 \end_deeper
1739 \begin_layout Standard
1740 \begin_inset Newpage newpage
1741 \end_inset
1742
1743
1744 \end_layout
1745
1746 \begin_layout Chapter
1747 Tests
1748 \end_layout
1749
1750 \begin_layout Standard
1751 Automated tests are an important tool to detect bugs and regressions in
1752  software development.
1753  Some projects like gcc even require each bug fix to be accompanied by a
1754  test case for the automatic test suite, that would detect this bug.
1755  Testing interactive features automatically is of course very hard, but
1756  core functionality like document import and export can be tested quite
1757  easily, and some tests of this kind exist.
1758 \end_layout
1759
1760 \begin_layout Section
1761 unit tests
1762 \end_layout
1763
1764 \begin_layout Standard
1765 There are attempts to set up a suite of unit tests for LyX.
1766 \end_layout
1767
1768 \begin_layout Standard
1769 TODO: describe what is done and what is still to do.
1770 \end_layout
1771
1772 \begin_layout Section
1773 tex2lyx tests
1774 \end_layout
1775
1776 \begin_layout Standard
1777 The tex2lyx tests are located in the
1778 \begin_inset Flex Code
1779 status collapsed
1780
1781 \begin_layout Plain Layout
1782 src/tex2lyx/test
1783 \end_layout
1784
1785 \end_inset
1786
1787  subfolder of the \SpecialChar LyX
1788  source code distribution.
1789  The actual testing is performed by the simple python script
1790 \begin_inset Flex Code
1791 status collapsed
1792
1793 \begin_layout Plain Layout
1794 src/tex2lyx/test/runtests.py
1795 \end_layout
1796
1797 \end_inset
1798
1799 .
1800  Each test consists of two files:
1801 \begin_inset Flex Code
1802 status collapsed
1803
1804 \begin_layout Plain Layout
1805 <test name>.tex
1806 \end_layout
1807
1808 \end_inset
1809
1810  contains the \SpecialChar LaTeX
1811  code that should be tested.
1812
1813 \begin_inset Flex Code
1814 status collapsed
1815
1816 \begin_layout Plain Layout
1817 <test name>.lyx.lyx
1818 \end_layout
1819
1820 \end_inset
1821
1822  contains the expected output of tex2lyx.
1823  When a test is run, the actual produced output is compared with the stored
1824  reference output.
1825  The test passes if both are identical.
1826  The test machinery is also able to generate a file
1827 \begin_inset Flex Code
1828 status collapsed
1829
1830 \begin_layout Plain Layout
1831 <test name>.lyx.tex
1832 \end_layout
1833
1834 \end_inset
1835
1836  by exporting the produced .lyx file with \SpecialChar LyX
1837  again.
1838  This may be useful for roundtrip comparisons.
1839 \end_layout
1840
1841 \begin_layout Subsection
1842 Running the tests
1843 \end_layout
1844
1845 \begin_layout Standard
1846 The tex2lyx tests can be run in several ways.
1847  When in the
1848 \begin_inset Flex Code
1849 status collapsed
1850
1851 \begin_layout Plain Layout
1852 src/tex2lyx
1853 \end_layout
1854
1855 \end_inset
1856
1857  subfolder of the build directory, the commands
1858 \begin_inset Flex Code
1859 status collapsed
1860
1861 \begin_layout Plain Layout
1862 ctest
1863 \end_layout
1864
1865 \end_inset
1866
1867  (cmake, all platforms),
1868 \begin_inset Flex Code
1869 status collapsed
1870
1871 \begin_layout Plain Layout
1872 make test
1873 \end_layout
1874
1875 \end_inset
1876
1877  (cmake, when using a make based build system and not MSVC) or
1878 \begin_inset Flex Code
1879 status collapsed
1880
1881 \begin_layout Plain Layout
1882 make alltests
1883 \end_layout
1884
1885 \end_inset
1886
1887  (autotools) will run the tex2lyx tests.
1888  Alternatively, in the root of the build directory, the command
1889 \begin_inset Flex Code
1890 status collapsed
1891
1892 \begin_layout Plain Layout
1893 ctest -R tex2lyx
1894 \end_layout
1895
1896 \end_inset
1897
1898  runs all tests whose names match the regex
1899 \begin_inset Quotes eld
1900 \end_inset
1901
1902 tex2lyx
1903 \begin_inset Quotes erd
1904 \end_inset
1905
1906 .
1907  Another way to run the tex2lyx tests in the root build directory is to
1908  instead use the command
1909 \begin_inset Flex Code
1910 status collapsed
1911
1912 \begin_layout Plain Layout
1913 ctest -L '(cmplyx|roundtrip)'
1914 \end_layout
1915
1916 \end_inset
1917
1918 , which runs all tests categorized with the label
1919 \begin_inset Quotes eld
1920 \end_inset
1921
1922 roundtrip
1923 \begin_inset Quotes erd
1924 \end_inset
1925
1926  or
1927 \begin_inset Quotes eld
1928 \end_inset
1929
1930 cmplyx
1931 \begin_inset Quotes erd
1932 \end_inset
1933
1934 .
1935  If a test fails, the differences between the expected and actual results
1936  are output in unified diff format.
1937 \end_layout
1938
1939 \begin_layout Subsection
1940 Updating test references
1941 \begin_inset CommandInset label
1942 LatexCommand label
1943 name "sec:Updating-test-references"
1944
1945 \end_inset
1946
1947
1948 \end_layout
1949
1950 \begin_layout Standard
1951 In some cases a changed tex2lyx output is not a test failure, but wanted,
1952  e.
1953 \begin_inset space \thinspace{}
1954 \end_inset
1955
1956 g.
1957 \begin_inset space \space{}
1958 \end_inset
1959
1960 if a tex2lyx bug was fixed, or a new feature was added.
1961  In these cases the stored references need to be updated.
1962  To do so if using autotools, call
1963 \begin_inset Flex Code
1964 status collapsed
1965
1966 \begin_layout Plain Layout
1967 make updatetests
1968 \end_layout
1969
1970 \end_inset
1971
1972  in the
1973 \begin_inset Flex Code
1974 status collapsed
1975
1976 \begin_layout Plain Layout
1977 src/tex2lyx
1978 \end_layout
1979
1980 \end_inset
1981
1982  subdirectory of the build directory.
1983  If instead using CMake, call
1984 \begin_inset Flex Code
1985 status collapsed
1986
1987 \begin_layout Plain Layout
1988 make updatetex2lyxtests
1989 \end_layout
1990
1991 \end_inset
1992
1993  in the build directory or in the
1994 \begin_inset Flex Code
1995 status collapsed
1996
1997 \begin_layout Plain Layout
1998 src/tex2lyx/test
1999 \end_layout
2000
2001 \end_inset
2002
2003  subdirectory of the build directory.
2004 \begin_inset Foot
2005 status collapsed
2006
2007 \begin_layout Plain Layout
2008 Note that this is a case where a make target in the build directory can
2009  affect the source directory, which might not be advisable.
2010 \end_layout
2011
2012 \end_inset
2013
2014  On Windows do the following:
2015 \end_layout
2016
2017 \begin_layout Itemize
2018 Assure that the path to the python.exe is in your system PATH variable.
2019 \end_layout
2020
2021 \begin_layout Itemize
2022 Double-click on the file
2023 \begin_inset Flex Code
2024 status collapsed
2025
2026 \begin_layout Plain Layout
2027 updatetex2lyxtests.vcxproj
2028 \end_layout
2029
2030 \end_inset
2031
2032  in the build directory or in the
2033 \begin_inset Flex Code
2034 status collapsed
2035
2036 \begin_layout Plain Layout
2037 src/tex2lyx/test
2038 \end_layout
2039
2040 \end_inset
2041
2042  subdirectory of your build directory.
2043 \end_layout
2044
2045 \begin_layout Itemize
2046 In the appearing MSVC program assure that you build the
2047 \emph on
2048 Release
2049 \emph default
2050  version, then right-click on the project
2051 \family sans
2052 updatetex2lyxtests
2053 \family default
2054  in the project explorer and choose then
2055 \family sans
2056 Project
2057 \begin_inset space ~
2058 \end_inset
2059
2060 Only\SpecialChar menuseparator
2061 Rebuild
2062 \begin_inset space ~
2063 \end_inset
2064
2065 only
2066 \family default
2067 .
2068 \end_layout
2069
2070 \begin_layout Standard
2071 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2072  files.
2073  Please examine the changed output carefully before committing the changed
2074  files to the repository: Since the test machinery does not do a roundtrip
2075  test .tex
2076 \begin_inset Formula $\Rightarrow$
2077 \end_inset
2078
2079  .lyx
2080 \begin_inset Formula $\Rightarrow$
2081 \end_inset
2082
2083  .tex, and does not compare the produced dvi or pdf output, it assumes that
2084  the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2085 .
2086  There is only one chance to detect wrong output: before committing a new
2087  reference.
2088  Once it is committed, it is quite difficult to verify whether it is correct.
2089 \end_layout
2090
2091 \begin_layout Standard
2092 Please
2093 \emph on
2094 do not
2095 \emph default
2096  update the test references by opening them with \SpecialChar LyX
2097  or directly running lyx2lyx
2098  on them.
2099  This would not work, since lyx2lyx and \SpecialChar LyX
2100  produce slightly different files
2101  regarding insignificant whitespace and line breaks.
2102 \end_layout
2103
2104 \begin_layout Subsection
2105 Adding a new test
2106 \end_layout
2107
2108 \begin_layout Standard
2109 In many cases tests for new features may be added to one of the existing
2110  test files, but sometimes this is not possible or not wanted.
2111  Then a new test file needs to be added:
2112 \end_layout
2113
2114 \begin_layout Enumerate
2115 Create the new file
2116 \begin_inset Flex Code
2117 status collapsed
2118
2119 \begin_layout Plain Layout
2120 src/tex2lyx/test/<test name>.tex
2121 \end_layout
2122
2123 \end_inset
2124
2125  and run tex2lyx in roundtrip mode to produce the file
2126 \begin_inset Flex Code
2127 status collapsed
2128
2129 \begin_layout Plain Layout
2130 src/tex2lyx/test/<test name>.lyx.lyx
2131 \end_layout
2132
2133 \end_inset
2134
2135 .
2136  This file will be the new reference.
2137 \end_layout
2138
2139 \begin_layout Enumerate
2140 Once you confirmed that the tex2lyx output is correct, add the new files
2141  to the corresponding lists in
2142 \begin_inset Flex Code
2143 status collapsed
2144
2145 \begin_layout Plain Layout
2146 src/tex2lyx/test/runtests.py
2147 \end_layout
2148
2149 \end_inset
2150
2151 ,
2152 \begin_inset Flex Code
2153 status collapsed
2154
2155 \begin_layout Plain Layout
2156 src/tex2lyx/Makefile.am
2157 \end_layout
2158
2159 \end_inset
2160
2161  and
2162 \begin_inset Flex Code
2163 status collapsed
2164
2165 \begin_layout Plain Layout
2166 src/tex2lyx/test/CMakeLists.txt
2167 \end_layout
2168
2169 \end_inset
2170
2171 .
2172 \end_layout
2173
2174 \begin_layout Enumerate
2175 Commit the changes to the repository, or send a patch to the development
2176  list and ask for committing if you do not have commit rights.
2177 \end_layout
2178
2179 \begin_layout Section
2180 ctest automatic tests
2181 \end_layout
2182
2183 \begin_layout Standard
2184 Some tests are located in the
2185 \begin_inset Flex Code
2186 status collapsed
2187
2188 \begin_layout Plain Layout
2189 development/autotests/
2190 \end_layout
2191
2192 \end_inset
2193
2194  subfolder of the \SpecialChar LyX
2195  source code distribution.
2196
2197 \begin_inset Foot
2198 status open
2199
2200 \begin_layout Plain Layout
2201 The README document in this folder only describes the
2202 \begin_inset Quotes eld
2203 \end_inset
2204
2205 keytests
2206 \begin_inset Quotes erd
2207 \end_inset
2208
2209  subset of autotests!
2210 \end_layout
2211
2212 \end_inset
2213
2214
2215 \end_layout
2216
2217 \begin_layout Standard
2218 These tests can be run by the commands
2219 \begin_inset Flex Code
2220 status collapsed
2221
2222 \begin_layout Plain Layout
2223 ctest
2224 \end_layout
2225
2226 \end_inset
2227
2228  in the
2229 \emph on
2230  build directory
2231 \emph default
2232  (all platforms) or (when using a make based build system and not MSVC)
2233
2234 \begin_inset Flex Code
2235 status collapsed
2236
2237 \begin_layout Plain Layout
2238 make test
2239 \end_layout
2240
2241 \end_inset
2242
2243  in the
2244 \begin_inset Flex Code
2245 status collapsed
2246
2247 \begin_layout Plain Layout
2248 autotests/
2249 \end_layout
2250
2251 \end_inset
2252
2253  subfolder of the
2254 \emph on
2255  build directory
2256 \emph default
2257 .
2258  The test logs are written to the
2259 \begin_inset Flex Code
2260 status collapsed
2261
2262 \begin_layout Plain Layout
2263 Testing/Temporary/
2264 \end_layout
2265
2266 \end_inset
2267
2268  subfolder of the
2269 \emph on
2270
2271 \emph default
2272 build directory.
2273
2274 \end_layout
2275
2276 \begin_layout Subsection
2277 Export tests
2278 \end_layout
2279
2280 \begin_layout Standard
2281 The export tests are integration tests.
2282  They take longer to run and are more likely to break than the tex2lyx tests.
2283  Nevertheless, they have caught many regressions and without a better alternativ
2284 e it is important to keep them up-to-date and understand how they work.
2285 \end_layout
2286
2287 \begin_layout Standard
2288 The export tests
2289 \begin_inset Quotes eld
2290 \end_inset
2291
2292 reuse
2293 \begin_inset Quotes erd
2294 \end_inset
2295
2296  documentation, template, and example documents.
2297  In addition, there are a number of dedicated sample documents in the
2298 \begin_inset Flex Code
2299 status collapsed
2300
2301 \begin_layout Plain Layout
2302 autotests/export/
2303 \end_layout
2304
2305 \end_inset
2306
2307  subfolder of the \SpecialChar LyX
2308  source code distribution.
2309  All samples are (after copying and eventual processing by scripts) exported
2310  to various output formats via the
2311 \begin_inset Flex Code
2312 status collapsed
2313
2314 \begin_layout Plain Layout
2315 —export-to
2316 \end_layout
2317
2318 \end_inset
2319
2320  command line option.
2321  The tests checks for errors reported by LyX.
2322  (However, error-free export is no guarantee for an error-free output document.)
2323 \end_layout
2324
2325 \begin_layout Subsubsection
2326 \begin_inset CommandInset label
2327 LatexCommand label
2328 name "par:when-to-run-an-export-test"
2329
2330 \end_inset
2331
2332 Expectations of LyX developers
2333 \end_layout
2334
2335 \begin_layout Standard
2336 Because the export tests are integration tests and take a long time to run,
2337  LyX developers are rarely expected to run all of the tests.
2338  Here are some good practices to follow by developers:
2339 \end_layout
2340
2341 \begin_layout Itemize
2342 When making a non-trivial change to a .layout file, run the export and layout
2343  tests corresponding with that .layout file.
2344 \end_layout
2345
2346 \begin_layout Itemize
2347 When making non-trivial changes to a .lyx file, run the export tests correspondin
2348 g to that .lyx file.
2349
2350 \begin_inset Foot
2351 status collapsed
2352
2353 \begin_layout Plain Layout
2354 This rule is due to revision.
2355
2356 \end_layout
2357
2358 \begin_layout Plain Layout
2359 There is an objection from the documentation maintainer that working on
2360  the documentation must not be complicated by having to consider non-standard
2361  exports.
2362 \end_layout
2363
2364 \begin_layout Itemize
2365 successful compiling/testing an edited documentation file with pdflatex
2366  suffices to ensure it can be commited, not tests with other exports are
2367  required.
2368 \end_layout
2369
2370 \begin_layout Plain Layout
2371 If sudden failures with other exports due to “half-tested” documentation
2372  updates are a problem for the test maintainer, the test suite should use
2373  copies that are
2374 \end_layout
2375
2376 \begin_layout Itemize
2377 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2378 \end_layout
2379
2380 \begin_layout Itemize
2381 updated regularely (but on a time chosen by the test suite maintainer) from
2382  the originals in lib/doc/
2383 \end_layout
2384
2385 \begin_layout Plain Layout
2386 This way,
2387 \end_layout
2388
2389 \begin_layout Itemize
2390 no test will fail due to ongoing work on documentation,
2391 \end_layout
2392
2393 \begin_layout Itemize
2394 the documentation is still tested in full (with some delay),
2395 \end_layout
2396
2397 \begin_layout Itemize
2398 failures with non-default export can be examined and handled accordingly
2399  in one run with the cache update,
2400 \end_layout
2401
2402 \begin_layout Itemize
2403 “interesting failures” (like the nested-language+polyglossia problem in
2404  es/Customization can be separated and moved into dedicated test samples.
2405 \end_layout
2406
2407 \end_inset
2408
2409
2410 \end_layout
2411
2412 \begin_layout Itemize
2413 When making non-trivial changes to LyX's \SpecialChar LaTeX
2414  export code (e.g.
2415  touching the encoding code or package handling code that you expect will
2416  change the exported \SpecialChar LaTeX
2417  in some way):
2418 \end_layout
2419
2420 \begin_deeper
2421 \begin_layout Standard
2422 \paragraph_spacing single
2423 Consider running all of the export tests before and after your change.
2424  If there are differences, please reconcile these (i.e.
2425  fix the bug or fix the tests)
2426 \emph on
2427 before
2428 \emph default
2429  committing.
2430  Ask for help if you're not sure what to.
2431 \end_layout
2432
2433 \begin_layout Standard
2434 If you do not want to run the tests,
2435 \end_layout
2436
2437 \begin_layout Itemize
2438 post the patch on the list and others will run the tests and eventually
2439  ask for fixes, or
2440 \end_layout
2441
2442 \begin_layout Itemize
2443 commit, but be prepared to fix eventually arising problems or to revert
2444  the commit if there is no easy fix.
2445 \end_layout
2446
2447 \end_deeper
2448 \begin_layout Itemize
2449 Understand how to interpret test failures.
2450  If your commit is found to have broken a test, you should be able to interpret
2451  the test results when made aware of them.
2452  See Section
2453 \begin_inset CommandInset ref
2454 LatexCommand ref
2455 reference "subsec:Interpreting-export-tests"
2456
2457 \end_inset
2458
2459 .
2460 \end_layout
2461
2462 \begin_layout Subsubsection
2463 \begin_inset CommandInset label
2464 LatexCommand label
2465 name "par:export-test-output-formats"
2466
2467 \end_inset
2468
2469 Output formats
2470 \end_layout
2471
2472 \begin_layout Standard
2473 The following output formats are currently tested for each sample document
2474  (see
2475 \begin_inset CommandInset ref
2476 LatexCommand ref
2477 reference "par:Export-test-filtering"
2478
2479 \end_inset
2480
2481  for exceptions):
2482 \end_layout
2483
2484 \begin_layout Labeling
2485 \labelwidthstring 00.00.0000
2486 LyX:
2487 \end_layout
2488
2489 \begin_deeper
2490 \begin_layout Labeling
2491 \labelwidthstring 00.00.0000
2492 lyx16 LyX 1.6 file format (lyx2lyx)
2493 \end_layout
2494
2495 \begin_layout Labeling
2496 \labelwidthstring 00.00.0000
2497 lyx21 LyX 2.1 file format (lyx2lyx)
2498 \end_layout
2499
2500 \begin_layout Labeling
2501 \labelwidthstring 00.00.0000
2502 xhtml LyXHTML (native LyX HTML export)
2503 \end_layout
2504
2505 \end_deeper
2506 \begin_layout Labeling
2507 \labelwidthstring 00.00.0000
2508 LyX
2509 \begin_inset space ~
2510 \end_inset
2511
2512 +
2513 \begin_inset space ~
2514 \end_inset
2515
2516 LaTeX:
2517 \end_layout
2518
2519 \begin_deeper
2520 \begin_layout Labeling
2521 \labelwidthstring pdf5msystemFM
2522 dvi DVI (8-bit latex)
2523 \end_layout
2524
2525 \begin_layout Labeling
2526 \labelwidthstring pdf5msystemFM
2527 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2528 \end_layout
2529
2530 \begin_layout Labeling
2531 \labelwidthstring pdf5msystemFM
2532 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2533 \end_layout
2534
2535 \begin_layout Labeling
2536 \labelwidthstring pdf5msystemFM
2537 pdf2 PDF (pdflatex)
2538 \end_layout
2539
2540 \begin_layout Labeling
2541 \labelwidthstring pdf5msystemFM
2542 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2543 \end_layout
2544
2545 \begin_layout Labeling
2546 \labelwidthstring pdf5msystemFM
2547 pdf4_systemF PDF (XeTeX with Unicode fonts)
2548 \end_layout
2549
2550 \begin_layout Labeling
2551 \labelwidthstring pdf5msystemFM
2552 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2553 \end_layout
2554
2555 \begin_layout Labeling
2556 \labelwidthstring pdf5msystemFM
2557 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2558 \end_layout
2559
2560 \end_deeper
2561 \begin_layout Labeling
2562 \labelwidthstring 00.00.0000
2563 LyX
2564 \begin_inset space ~
2565 \end_inset
2566
2567 +
2568 \begin_inset space ~
2569 \end_inset
2570
2571 LaTeX
2572 \begin_inset space ~
2573 \end_inset
2574
2575 +
2576 \begin_inset space ~
2577 \end_inset
2578
2579 postprocessing:
2580 \end_layout
2581
2582 \begin_deeper
2583 \begin_layout Labeling
2584 \labelwidthstring pdf5msystemFM
2585 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2586 \end_layout
2587
2588 \begin_layout Labeling
2589 \labelwidthstring pdf5msystemFM
2590 pdf3 DVI -> PDF (dvipdfm)
2591 \end_layout
2592
2593 \end_deeper
2594 \begin_layout Labeling
2595 \labelwidthstring 00.00.0000
2596 not
2597 \begin_inset space ~
2598 \end_inset
2599
2600 tested: (or only if set as default output format in the document source)
2601 \end_layout
2602
2603 \begin_deeper
2604 \begin_layout Labeling
2605 \labelwidthstring pdf5msystemFM
2606 latex LaTeX (plain)
2607 \end_layout
2608
2609 \begin_layout Labeling
2610 \labelwidthstring pdf5msystemFM
2611 luatex LaTeX (LuaTeX)
2612 \end_layout
2613
2614 \begin_layout Labeling
2615 \labelwidthstring pdf5msystemFM
2616 dviluatex LaTeX (dviluatex)
2617 \end_layout
2618
2619 \begin_layout Labeling
2620 \labelwidthstring pdf5msystemFM
2621 pdflatex LaTeX (pdflatex)
2622 \end_layout
2623
2624 \begin_layout Labeling
2625 \labelwidthstring pdf5msystemFM
2626 platex LaTeX (pLaTeX)
2627 \end_layout
2628
2629 \begin_layout Labeling
2630 \labelwidthstring pdf5msystemFM
2631 xetex LaTeX (XeTeX)
2632 \end_layout
2633
2634 \begin_layout Labeling
2635 \labelwidthstring pdf5msystemFM
2636 eps3 EPS (encapsulated Postscript) (cropped)
2637 \end_layout
2638
2639 \begin_layout Labeling
2640 \labelwidthstring pdf5msystemFM
2641 ps DVI -> Postscript (dvips)
2642 \end_layout
2643
2644 \begin_layout Labeling
2645 \labelwidthstring pdf5msystemFM
2646 odf
2647 \end_layout
2648
2649 \begin_layout Labeling
2650 \labelwidthstring pdf5msystemFM
2651 text (nor text2, ..., text4)
2652 \end_layout
2653
2654 \begin_layout Labeling
2655 \labelwidthstring pdf5msystemFM
2656 textparagraph
2657 \end_layout
2658
2659 \begin_layout Labeling
2660 \labelwidthstring pdf5msystemFM
2661 word
2662 \end_layout
2663
2664 \begin_layout Labeling
2665 \labelwidthstring pdf5msystemFM
2666 word2
2667 \end_layout
2668
2669 \begin_layout Labeling
2670 \labelwidthstring pdf5msystemFM
2671 wordhtml
2672 \end_layout
2673
2674 \end_deeper
2675 \begin_layout Subsubsection
2676 \begin_inset CommandInset label
2677 LatexCommand label
2678 name "par:Configuring-ctests"
2679
2680 \end_inset
2681
2682 Configuring the tests
2683 \end_layout
2684
2685 \begin_layout Standard
2686 To enable the export autotests, add the
2687 \begin_inset Flex Code
2688 status collapsed
2689
2690 \begin_layout Plain Layout
2691 -DLYX_ENABLE_EXPORT_TESTS=ON
2692 \end_layout
2693
2694 \end_inset
2695
2696  flag.
2697  For example:
2698 \end_layout
2699
2700 \begin_layout Standard
2701 \begin_inset Flex Code
2702 status collapsed
2703
2704 \begin_layout Plain Layout
2705 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2706 \end_layout
2707
2708 \end_inset
2709
2710
2711 \end_layout
2712
2713 \begin_layout Standard
2714 \noindent
2715 This flag will increase the time for the cmake command by several seconds,
2716  mainly because of the process of inverting tests (see Section
2717 \begin_inset CommandInset ref
2718 LatexCommand ref
2719 reference "subsec:Interpreting-export-tests"
2720
2721 \end_inset
2722
2723 ).
2724 \end_layout
2725
2726 \begin_layout Subsubsection
2727 \begin_inset CommandInset label
2728 LatexCommand label
2729 name "par:ctest-options"
2730
2731 \end_inset
2732
2733 Running the tests
2734 \end_layout
2735
2736 \begin_layout Standard
2737 To run all tests, in the build directory simply run the command
2738 \begin_inset Flex Code
2739 status collapsed
2740
2741 \begin_layout Plain Layout
2742 ctest
2743 \end_layout
2744
2745 \end_inset
2746
2747 .
2748  A full, up-to-date TeXLive installation is recommended to run the tests.
2749  Otherwise, some tests will fail.
2750  Tests with additional requirements are labeled
2751 \begin_inset Quotes eld
2752 \end_inset
2753
2754 unreliable:nonstandard
2755 \begin_inset Quotes erd
2756 \end_inset
2757
2758 .
2759
2760 \end_layout
2761
2762 \begin_layout Standard
2763 To run only some of the tests, use command line options (see examples below):
2764 \end_layout
2765
2766 \begin_layout Labeling
2767 \labelwidthstring -R
2768 \begin_inset Flex Code
2769 status collapsed
2770
2771 \begin_layout Plain Layout
2772 -R <pattern>
2773 \end_layout
2774
2775 \end_inset
2776
2777  Run only the tests whose names match the given regular expression.
2778 \end_layout
2779
2780 \begin_layout Labeling
2781 \labelwidthstring -R
2782 \begin_inset Flex Code
2783 status collapsed
2784
2785 \begin_layout Plain Layout
2786 -L <pattern>
2787 \end_layout
2788
2789 \end_inset
2790
2791  Run only the tests whose labels match the given regular expression.
2792  A test may have more that one label.
2793
2794 \end_layout
2795
2796 \begin_layout Labeling
2797 \labelwidthstring -R
2798 \begin_inset Flex Code
2799 status collapsed
2800
2801 \begin_layout Plain Layout
2802 -E <pattern>
2803 \end_layout
2804
2805 \end_inset
2806
2807  Exclude the tests whose names match the given regular expression.
2808 \end_layout
2809
2810 \begin_layout Labeling
2811 \labelwidthstring -R
2812 \begin_inset Flex Code
2813 status collapsed
2814
2815 \begin_layout Plain Layout
2816 -LE <pattern>
2817 \end_layout
2818
2819 \end_inset
2820
2821  Exclude the tests whose labels match the given regular expression.
2822  Cannot be combined with
2823 \begin_inset Flex Code
2824 status collapsed
2825
2826 \begin_layout Plain Layout
2827 -L
2828 \end_layout
2829
2830 \end_inset
2831
2832 .
2833 \end_layout
2834
2835 \begin_layout Standard
2836 The following options help to find good selection patterns:
2837 \end_layout
2838
2839 \begin_layout Labeling
2840 \labelwidthstring -R
2841 \begin_inset Flex Code
2842 status collapsed
2843
2844 \begin_layout Plain Layout
2845 -N
2846 \end_layout
2847
2848 \end_inset
2849
2850  List the tests that would be run but not actually run them.
2851
2852 \end_layout
2853
2854 \begin_deeper
2855 \begin_layout Standard
2856 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2857  to know how many tests there are or whether your
2858 \begin_inset Flex Code
2859 status collapsed
2860
2861 \begin_layout Plain Layout
2862 <pattern>
2863 \end_layout
2864
2865 \end_inset
2866
2867  regular expression did what you expected.
2868 \end_layout
2869
2870 \end_deeper
2871 \begin_layout Labeling
2872 \labelwidthstring -R
2873 \begin_inset Flex Code
2874 status collapsed
2875
2876 \begin_layout Plain Layout
2877 \SpecialChar nobreakdash
2878 \SpecialChar nobreakdash
2879 print-labels
2880 \end_layout
2881
2882 \end_inset
2883
2884  print the list of all labels associated with the test set.
2885  Can also be combined with -R, -L, -E, ...
2886
2887 \end_layout
2888
2889 \begin_layout Standard
2890 Other useful options are:
2891 \end_layout
2892
2893 \begin_layout Labeling
2894 \labelwidthstring -R
2895 \begin_inset Flex Code
2896 status collapsed
2897
2898 \begin_layout Plain Layout
2899 -j <jobs>
2900 \end_layout
2901
2902 \end_inset
2903
2904  Run the tests in parallel using the given number of jobs.
2905 \end_layout
2906
2907 \begin_deeper
2908 \begin_layout Standard
2909 We are still working on getting the tests to run in parallel.
2910  However, when running the tests in parallel, sometimes tests fail that
2911  pass when run sequentially.
2912  A reasonable approach is to first run the tests in parallel and then run
2913  the failed tests sequentially.
2914 \end_layout
2915
2916 \begin_layout Standard
2917 For example, to run 8 jobs at a time:
2918 \end_layout
2919
2920 \begin_layout Standard
2921 \begin_inset Flex Code
2922 status collapsed
2923
2924 \begin_layout Plain Layout
2925 ctest -j8
2926 \end_layout
2927
2928 \end_inset
2929
2930
2931 \end_layout
2932
2933 \begin_layout Standard
2934 \begin_inset Flex Code
2935 status collapsed
2936
2937 \begin_layout Plain Layout
2938 ctest \SpecialChar nobreakdash
2939 \SpecialChar nobreakdash
2940 rerun-failed
2941 \end_layout
2942
2943 \end_inset
2944
2945
2946 \end_layout
2947
2948 \begin_layout Standard
2949 When specifying a subset of the tests (e.g.
2950  using
2951 \begin_inset Flex Code
2952 status collapsed
2953
2954 \begin_layout Plain Layout
2955 \SpecialChar nobreakdash
2956 R <pattern>
2957 \end_layout
2958
2959 \end_inset
2960
2961 ), the same subset must be specified when using the
2962 \begin_inset Flex Code
2963 status collapsed
2964
2965 \begin_layout Plain Layout
2966 \SpecialChar nobreakdash
2967 \SpecialChar nobreakdash
2968 rerun-failed
2969 \end_layout
2970
2971 \end_inset
2972
2973  option because it is the test numbers that are used to index which tests
2974  failed on the previous run.
2975 \end_layout
2976
2977 \begin_layout Standard
2978 \noindent
2979 Note that some tests cannot be run in parallel.
2980  These tests are marked in the code with the
2981 \begin_inset Flex Code
2982 status collapsed
2983
2984 \begin_layout Plain Layout
2985 RUN_SERIAL ON
2986 \end_layout
2987
2988 \end_inset
2989
2990  CMake property.
2991 \end_layout
2992
2993 \end_deeper
2994 \begin_layout Labeling
2995 \labelwidthstring -R
2996 \begin_inset Flex Code
2997 status collapsed
2998
2999 \begin_layout Plain Layout
3000 \SpecialChar nobreakdash
3001 \SpecialChar nobreakdash
3002 timeout <seconds>
3003 \end_layout
3004
3005 \end_inset
3006
3007  Set a global timeout on all tests that do not already have a timeout set
3008  on them.
3009 \end_layout
3010
3011 \begin_deeper
3012 \begin_layout Standard
3013 There have been bugs in LyX and in \SpecialChar LaTeX
3014  which cause compilation to hang, and
3015  without a timeout a test might never stop (in one case there was even a
3016  memory leak).
3017  If a test times out, the
3018 \begin_inset Flex Code
3019 status collapsed
3020
3021 \begin_layout Plain Layout
3022 ctest
3023 \end_layout
3024
3025 \end_inset
3026
3027  command exits with error, but you can distinguish between a timed out test
3028  and a failed test in the output reported at the end of the
3029 \begin_inset Flex Code
3030 status collapsed
3031
3032 \begin_layout Plain Layout
3033 ctest
3034 \end_layout
3035
3036 \end_inset
3037
3038  command.
3039 \end_layout
3040
3041 \end_deeper
3042 \begin_layout Standard
3043 See the manual (
3044 \begin_inset Flex Code
3045 status collapsed
3046
3047 \begin_layout Plain Layout
3048 man ctest
3049 \end_layout
3050
3051 \end_inset
3052
3053 ) the full list of command line options.
3054 \end_layout
3055
3056 \begin_layout Subsubsection
3057 Examples
3058 \end_layout
3059
3060 \begin_layout Itemize
3061 run only the export tests:
3062 \begin_inset Flex Code
3063 status collapsed
3064
3065 \begin_layout Plain Layout
3066 ctest -L export
3067 \end_layout
3068
3069 \end_inset
3070
3071
3072 \end_layout
3073
3074 \begin_layout Itemize
3075 run inverted tests:
3076 \begin_inset Flex Code
3077 status collapsed
3078
3079 \begin_layout Plain Layout
3080 ctest -L "inverted|suspended"
3081 \end_layout
3082
3083 \end_inset
3084
3085
3086 \end_layout
3087
3088 \begin_layout Itemize
3089 list all export tests which match any of the labelling patterns:
3090 \begin_inset Flex Code
3091 status collapsed
3092
3093 \begin_layout Plain Layout
3094 ctest -N -R "
3095 \backslash
3096 ..*_export/"
3097 \end_layout
3098
3099 \end_inset
3100
3101
3102 \end_layout
3103
3104 \begin_layout Itemize
3105 exclude rarely used output formats and post-processing tests
3106 \begin_inset Flex Code
3107 status collapsed
3108
3109 \begin_layout Plain Layout
3110 ctest -L export -E "_(texF|dvi3|pdf3?)"
3111 \end_layout
3112
3113 \end_inset
3114
3115
3116 \end_layout
3117
3118 \begin_layout Subsubsection
3119 \begin_inset CommandInset label
3120 LatexCommand label
3121 name "subsec:Interpreting-export-tests"
3122
3123 \end_inset
3124
3125 Interpreting the export test results
3126 \end_layout
3127
3128 \begin_layout Standard
3129 A test can fail for several reasons, not all of them bad.
3130 \end_layout
3131
3132 \begin_layout Enumerate
3133 A new or edited sample document may be incompatible with some output formats.
3134 \end_layout
3135
3136 \begin_layout Enumerate
3137 A dependency is not met (e.g.
3138  the \SpecialChar LaTeX
3139  class file).
3140  One hint that this is the case is that the corresponding
3141 \begin_inset Flex Code
3142 status collapsed
3143
3144 \begin_layout Plain Layout
3145 check_load
3146 \end_layout
3147
3148 \end_inset
3149
3150  test will likely also fail.
3151 \end_layout
3152
3153 \begin_layout Enumerate
3154 An inverted test fails to fail (i.e.
3155  export that previously failed now works).
3156 \end_layout
3157
3158 \begin_layout Enumerate
3159 An external dependency was updated (e.g.
3160  \SpecialChar TeX
3161  Live).
3162 \end_layout
3163
3164 \begin_layout Enumerate
3165 A recent code change introduced a bug.
3166 \end_layout
3167
3168 \begin_layout Enumerate
3169 \begin_inset CommandInset label
3170 LatexCommand label
3171 name "enu:exposed"
3172
3173 \end_inset
3174
3175 A change in a document exposed a previously unknown bug or an incompatibility
3176  with an export format (e.g.
3177  Lua\SpecialChar LaTeX
3178 ).
3179 \end_layout
3180
3181 \begin_layout Standard
3182 Because the .lyx files are exported in several formats, it is not surprising
3183  that many of the exports fail.
3184  This expectation of failure is addressed by
3185 \begin_inset Quotes eld
3186 \end_inset
3187
3188 inverting
3189 \begin_inset Quotes erd
3190 \end_inset
3191
3192  the tests, that is, by marking the test as
3193 \begin_inset Quotes eld
3194 \end_inset
3195
3196 passing
3197 \begin_inset Quotes erd
3198 \end_inset
3199
3200  if the export exits with error and as
3201 \begin_inset Quotes eld
3202 \end_inset
3203
3204 failing
3205 \begin_inset Quotes erd
3206 \end_inset
3207
3208  if the export succeeds
3209 \emph on
3210 .
3211
3212 \emph default
3213  It follows that these expected failures will not show up as failed tests
3214  in the test results and thus will not pollute the
3215 \begin_inset Quotes eld
3216 \end_inset
3217
3218 good
3219 \begin_inset Quotes erd
3220 \end_inset
3221
3222  tests.
3223  If the export actually succeeds, then the test will fail.
3224  The purpose of this failure is to get your attention—something has changed,
3225  possibly for the better.
3226 \end_layout
3227
3228 \begin_layout Standard
3229 We try to document why a test is inverted or ignored.
3230  See the comment (prefixed with
3231 \begin_inset Flex Code
3232 status collapsed
3233
3234 \begin_layout Plain Layout
3235 #
3236 \end_layout
3237
3238 \end_inset
3239
3240 ) above the block in which the test is listed as inverted or ignored in
3241  the files
3242 \begin_inset Flex Code
3243 status collapsed
3244
3245 \begin_layout Plain Layout
3246 development/autotests/invertedTests
3247 \end_layout
3248
3249 \end_inset
3250
3251 ,
3252 \begin_inset Flex Code
3253 status collapsed
3254
3255 \begin_layout Plain Layout
3256 development/autotests/unreliableTests
3257 \end_layout
3258
3259 \end_inset
3260
3261  and
3262 \begin_inset Flex Code
3263 status collapsed
3264
3265 \begin_layout Plain Layout
3266 development/autotests/ignoredTests
3267 \end_layout
3268
3269 \end_inset
3270
3271 .
3272
3273 \end_layout
3274
3275 \begin_layout Standard
3276 A good question is why do we enable the tests for non-default formats? The
3277  answer is that if a non-default route is broken it is often because a bug
3278  was introduced in LyX and not because a document-specific change was made
3279  that is not supported by the route.
3280  In other words, there is a high signal/noise ratio in the export tests
3281  for some non-default formats.
3282
3283 \end_layout
3284
3285 \begin_layout Standard
3286 When a test or several tests fail, consider checking the files in the
3287 \begin_inset Flex Code
3288 status collapsed
3289
3290 \begin_layout Plain Layout
3291 Testing/Temporary/
3292 \end_layout
3293
3294 \end_inset
3295
3296  subdirectory of your build directory.
3297  In this subdirectory are three files: the file
3298 \begin_inset Flex Code
3299 status collapsed
3300
3301 \begin_layout Plain Layout
3302 LastTestsFailed.log
3303 \end_layout
3304
3305 \end_inset
3306
3307  simply lists the tests that failed on your last
3308 \begin_inset Flex Code
3309 status collapsed
3310
3311 \begin_layout Plain Layout
3312 ctest
3313 \end_layout
3314
3315 \end_inset
3316
3317  command; the
3318 \begin_inset Flex Code
3319 status collapsed
3320
3321 \begin_layout Plain Layout
3322 LastTest.log
3323 \end_layout
3324
3325 \end_inset
3326
3327  file contains the output from the tests (and often has details explaining
3328  why a test failed); and the
3329 \begin_inset Flex Code
3330 status collapsed
3331
3332 \begin_layout Plain Layout
3333 CTestCostData.txt
3334 \end_layout
3335
3336 \end_inset
3337
3338  file lists the times that it took to run the tests.
3339 \end_layout
3340
3341 \begin_layout Subsubsection
3342 What action should you take if a test fails?
3343 \end_layout
3344
3345 \begin_layout Standard
3346 \paragraph_spacing single
3347 It is always good to check manually why something fails and if it passes
3348  if the PDF output is good.
3349 \end_layout
3350
3351 \begin_layout Itemize
3352 Generally, if a change breaks compilation for the target format (for the
3353  manuals pdf2) without solving some important other issue,
3354 \emph on
3355 fix or revert the commit
3356 \emph default
3357  that led to failure.
3358 \end_layout
3359
3360 \begin_layout Itemize
3361 If it is not possible to (immediately) fix the failure but there are reasons
3362  not to revert the commit (e.g.
3363  it fixes another more important issue),
3364 \emph on
3365 invert
3366 \emph default
3367  the failing test case (see
3368 \begin_inset CommandInset ref
3369 LatexCommand ref
3370 reference "par:Inverted-tests"
3371
3372 \end_inset
3373
3374 ).
3375 \end_layout
3376
3377 \begin_layout Itemize
3378 If an
3379 \emph on
3380 inverted
3381 \emph default
3382  test case fails because the export now works, first confirm that the output
3383  of the corresponding export looks good (e.g., not garbled text).
3384  Then,
3385 \emph on
3386 uninvert
3387 \emph default
3388  the test by removing the pattern from the
3389 \begin_inset Quotes eld
3390 \end_inset
3391
3392 invertedTests
3393 \begin_inset Quotes erd
3394 \end_inset
3395
3396  file (see
3397 \begin_inset CommandInset ref
3398 LatexCommand ref
3399 reference "par:Inverted-tests"
3400
3401 \end_inset
3402
3403 ).
3404 \end_layout
3405
3406 \begin_layout Itemize
3407 If the export did not fail previously but led to wrong output (PDF, say),
3408 \begin_inset Foot
3409 status collapsed
3410
3411 \begin_layout Plain Layout
3412 Non-failing test with wrong output should be labeled as
3413 \begin_inset Quotes eld
3414 \end_inset
3415
3416 unreliable:wrong_output
3417 \begin_inset Quotes erd
3418 \end_inset
3419
3420  (
3421 \begin_inset CommandInset ref
3422 LatexCommand ref
3423 reference "par:Unreliable-tests"
3424
3425 \end_inset
3426
3427 ).
3428 \end_layout
3429
3430 \end_inset
3431
3432  it is in fact an improvement when the test now fails.
3433
3434 \emph on
3435 Invert
3436 \emph default
3437  the failing test case (see
3438 \begin_inset CommandInset ref
3439 LatexCommand ref
3440 reference "par:Inverted-tests"
3441
3442 \end_inset
3443
3444 ).
3445 \end_layout
3446
3447 \begin_layout Itemize
3448 In case of tests failing due to missing requirements (tests labeled
3449 \begin_inset Quotes eld
3450 \end_inset
3451
3452 unreliable:nonstandard
3453 \begin_inset Quotes erd
3454 \end_inset
3455
3456  or testing on a system with only a subset of TeXLive installed), ignore
3457  the failure, ask for someone else to run the test, or install the missing
3458  resources and try again.
3459 \end_layout
3460
3461 \begin_layout Itemize
3462 Check the log file Testing/Temporary/LastTest.log.
3463  In case of latex-errors rerun the failing test with environment variable
3464  'LYX_DEBUG_LATEX' set to '1'.
3465  This will include latex messages in LastTest.log, so it should be easier
3466  to interpret the fail-reason.
3467 \end_layout
3468
3469 \begin_layout Subsubsection
3470 \begin_inset CommandInset label
3471 LatexCommand label
3472 name "par:Inverted-tests"
3473
3474 \end_inset
3475
3476 Inverted tests
3477 \end_layout
3478
3479 \begin_layout Standard
3480 Test cases whose name matches a pattern in the file
3481 \begin_inset Flex Code
3482 status collapsed
3483
3484 \begin_layout Plain Layout
3485 development/autotests/invertedTests
3486 \end_layout
3487
3488 \end_inset
3489
3490  get the label
3491 \emph on
3492 inverted
3493 \emph default
3494 .
3495  They get also the test property
3496 \begin_inset Flex Code
3497 status collapsed
3498
3499 \begin_layout Plain Layout
3500 WILL_FAIL
3501 \end_layout
3502
3503 \end_inset
3504
3505 , i.e.
3506  they are reported as failing if the export works without error
3507 \begin_inset Flex URL
3508 status collapsed
3509
3510 \begin_layout Plain Layout
3511
3512 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3513 \end_layout
3514
3515 \end_inset
3516
3517 .
3518 \end_layout
3519
3520 \begin_layout Standard
3521 Add failing cases to this file, if they cannot be solved
3522 \begin_inset Quotes eld
3523 \end_inset
3524
3525 immediately
3526 \begin_inset Quotes erd
3527 \end_inset
3528
3529  but it is expected that the export will work in a foreseeable future, e.g.
3530  low priority issues like failures to export to a non-target format (for
3531  the manuals everything except pdf2).
3532 \end_layout
3533
3534 \begin_layout Standard
3535 The following sublabels are currently present in
3536 \begin_inset Flex Code
3537 status collapsed
3538
3539 \begin_layout Plain Layout
3540 invertedTests
3541 \end_layout
3542
3543 \end_inset
3544
3545 :
3546 \end_layout
3547
3548 \begin_layout Description
3549 todo test failures that require attention:
3550 \end_layout
3551
3552 \begin_deeper
3553 \begin_layout Itemize
3554 minor issues to explore and properly sort later,
3555 \end_layout
3556
3557 \begin_layout Itemize
3558 easyfix issues,
3559 \end_layout
3560
3561 \begin_layout Itemize
3562 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3563 \end_layout
3564
3565 \end_deeper
3566 \begin_layout Description
3567 lyxbugs LyX bugs with a Trac number.
3568 \end_layout
3569
3570 \begin_layout Description
3571 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3572 \end_layout
3573
3574 \begin_deeper
3575 \begin_layout Standard
3576 "Wontfix" if demonstrating correct use and OK in the default output format.
3577 \end_layout
3578
3579 \end_deeper
3580 \begin_layout Description
3581 texissues Export fails due to LaTeX limitations like non-ASCII characters
3582  in verbatim or listings, incompatible packages, ...
3583 \end_layout
3584
3585 \begin_deeper
3586 \begin_layout Standard
3587 "Wontfix" if documents demonstrate correct use in the default output format:
3588 \end_layout
3589
3590 \begin_layout Itemize
3591 If the source can be made more robust without becoming "hackish", fix the
3592  source,
3593 \end_layout
3594
3595 \begin_layout Itemize
3596 if LyX could be enhanced to care for a permanent TeX limitation, file a
3597  ticket at trac and add a pattern under lyxbugs,
3598 \end_layout
3599
3600 \begin_layout Itemize
3601 otherwise, add a pattern here.
3602 \end_layout
3603
3604 \end_deeper
3605 \begin_layout Description
3606 attic Documents in the attic (kept for reference and format conversion test).
3607  Usually
3608 \begin_inset Quotes eld
3609 \end_inset
3610
3611 Wontfix
3612 \begin_inset Quotes erd
3613 \end_inset
3614
3615 .
3616 \end_layout
3617
3618 \begin_layout Paragraph
3619 suspended tests
3620 \end_layout
3621
3622 \begin_layout Standard
3623 Test cases whose name additionally matches a pattern in the file
3624 \begin_inset Flex Code
3625 status collapsed
3626
3627 \begin_layout Plain Layout
3628 development/autotests/suspendedTests
3629 \end_layout
3630
3631 \end_inset
3632
3633  get the label
3634 \emph on
3635 suspended
3636 \emph default
3637 (instead of
3638 \emph on
3639 export
3640 \emph default
3641 and
3642 \emph on
3643  inverted
3644 \emph default
3645 ).
3646  This means they are not executed using
3647 \begin_inset Flex Code
3648 status collapsed
3649
3650 \begin_layout Plain Layout
3651 ctest -L export
3652 \end_layout
3653
3654 \end_inset
3655
3656  or
3657 \begin_inset Flex Code
3658 status collapsed
3659
3660 \begin_layout Plain Layout
3661 ctest -L inverted
3662 \end_layout
3663
3664 \end_inset
3665
3666 .
3667  However, they also get the test property
3668 \begin_inset Flex Code
3669 status collapsed
3670
3671 \begin_layout Plain Layout
3672 WILL_FAIL
3673 \end_layout
3674
3675 \end_inset
3676
3677 , i.e.
3678  they are reported as failing if the export works without error.
3679  From time to time they still have to be checked using
3680 \begin_inset Flex Code
3681 status collapsed
3682
3683 \begin_layout Plain Layout
3684 ctest -L suspended
3685 \end_layout
3686
3687 \end_inset
3688
3689 .
3690 \end_layout
3691
3692 \begin_layout Standard
3693 These tests are suspended, because the export fails for known reasons which
3694  cannot ATM be resolved.
3695  But it is expected the reason might disappear in the future.
3696  Be it new TL or better handling in \SpecialChar LyX
3697 .
3698 \end_layout
3699
3700 \begin_layout Standard
3701 For ctest commands without the
3702 \begin_inset Flex Code
3703 status collapsed
3704
3705 \begin_layout Plain Layout
3706 -L
3707 \end_layout
3708
3709 \end_inset
3710
3711  parameter nothing changes.
3712  Suspended or not, tests will be executed depending only on the selecting
3713  regular expression given to the ctest command (see
3714 \begin_inset CommandInset ref
3715 LatexCommand ref
3716 reference "par:ctest-options"
3717
3718 \end_inset
3719
3720 ).
3721 \end_layout
3722
3723 \begin_layout Subsubsection
3724 \begin_inset CommandInset label
3725 LatexCommand label
3726 name "par:Unreliable-tests"
3727
3728 \end_inset
3729
3730 Unreliable tests
3731 \end_layout
3732
3733 \begin_layout Standard
3734 Test cases whose name matches a pattern in the file
3735 \begin_inset Flex Code
3736 status collapsed
3737
3738 \begin_layout Plain Layout
3739 development/autotests/unreliableTests
3740 \end_layout
3741
3742 \end_inset
3743
3744  get the label
3745 \emph on
3746 unreliable
3747 \emph default
3748 .
3749 \end_layout
3750
3751 \begin_layout Standard
3752 These tests are not executed using
3753 \begin_inset Flex Code
3754 status collapsed
3755
3756 \begin_layout Plain Layout
3757 ctest -L export
3758 \end_layout
3759
3760 \end_inset
3761
3762  or
3763 \begin_inset Flex Code
3764 status collapsed
3765
3766 \begin_layout Plain Layout
3767 ctest -L inverted
3768 \end_layout
3769
3770 \end_inset
3771
3772 .
3773
3774 \end_layout
3775
3776 \begin_layout Standard
3777 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3778  or pass but should rather fail (wrong output).
3779
3780 \begin_inset Note Note
3781 status collapsed
3782
3783 \begin_layout Plain Layout
3784 *invalid* tests (wrong output) are not *unreliable*.
3785  # Use "unfit" or "unapplicable" as better label and name of pattern file?
3786
3787 \end_layout
3788
3789 \end_inset
3790
3791
3792 \end_layout
3793
3794 \begin_layout Standard
3795 The following sublabels are currently present in
3796 \begin_inset Flex Code
3797 status collapsed
3798
3799 \begin_layout Plain Layout
3800 unreliableTests
3801 \end_layout
3802
3803 \end_inset
3804
3805 :
3806 \end_layout
3807
3808 \begin_layout Description
3809 nonstandard Documents with additional requirements, e.g.
3810  a class or package file not in TeXLive.
3811
3812 \begin_inset Note Note
3813 status open
3814
3815 \begin_layout Plain Layout
3816 TODO: rename to
3817 \begin_inset Quotes eld
3818 \end_inset
3819
3820 extra
3821 \begin_inset Quotes erd
3822 \end_inset
3823
3824  or
3825 \begin_inset Quotes eld
3826 \end_inset
3827
3828 exotic
3829 \begin_inset Quotes erd
3830 \end_inset
3831
3832 ?
3833 \end_layout
3834
3835 \end_inset
3836
3837
3838 \end_layout
3839
3840 \begin_layout Description
3841 erratic Tests depending on local configuration or the phase of the moon.
3842
3843 \end_layout
3844
3845 \begin_layout Description
3846 varying_versions Tests depending on e.g.
3847  OS or version of a non-TeX-Live dependency.
3848  Note that a full, up-to-date TeX Live installation is required so this
3849  sublabel is about versions of other dependencies.
3850 \end_layout
3851
3852 \begin_layout Description
3853 wrong
3854 \begin_inset space ~
3855 \end_inset
3856
3857 output Export does not fail but the resulting document has (undetected)
3858  errors.
3859 \end_layout
3860
3861 \begin_deeper
3862 \begin_layout Standard
3863 \paragraph_spacing single
3864 \begin_inset Note Note
3865 status open
3866
3867 \begin_layout Plain Layout
3868 \paragraph_spacing single
3869 These tests are in a strict sense not unreliable but
3870 \emph on
3871 invalid
3872 \emph default
3873  (not measuring what they should measure).
3874 \end_layout
3875
3876 \end_inset
3877
3878
3879 \end_layout
3880
3881 \end_deeper
3882 \begin_layout Subsubsection
3883 \begin_inset CommandInset label
3884 LatexCommand label
3885 name "par:Export-test-filtering"
3886
3887 \end_inset
3888
3889 Export test filtering
3890 \end_layout
3891
3892 \begin_layout Standard
3893 The assignment of a label to a test is controlled by a set of files with
3894  regular expressions that are matched against the test names.
3895 \end_layout
3896
3897 \begin_layout Description
3898 ignoredTests (small file)
3899 \begin_inset Newline newline
3900 \end_inset
3901
3902 Tests selected here are withdrawn in the configuration step (cf.
3903
3904 \begin_inset CommandInset ref
3905 LatexCommand ref
3906 reference "par:Configuring-ctests"
3907
3908 \end_inset
3909
3910 ).
3911 \end_layout
3912
3913 \begin_deeper
3914 \begin_layout Labeling
3915 \labelwidthstring 00.00.0000
3916 Input Test of any export combination
3917 \end_layout
3918
3919 \begin_layout Labeling
3920 \labelwidthstring 00.00.0000
3921 Output Stop if tests not selected here
3922 \end_layout
3923
3924 \end_deeper
3925 \begin_layout Description
3926 unreliableTests: Tests selected pass or fail dependent on the system where
3927  the test is run.
3928  Selected tests gain the label 'unreliable'.
3929 \end_layout
3930
3931 \begin_deeper
3932 \begin_layout Labeling
3933 \labelwidthstring 00.00.0000
3934 Input Each test which passed 'ignoredTests'
3935 \end_layout
3936
3937 \begin_layout Labeling
3938 \labelwidthstring 00.00.0000
3939 Output Gain label 'unreliable', proceed with checking for 'inverted'.
3940 \end_layout
3941
3942 \end_deeper
3943 \begin_layout Description
3944 invertedTests
3945 \begin_inset space \space{}
3946 \end_inset
3947
3948
3949 \end_layout
3950
3951 \begin_deeper
3952 \begin_layout Labeling
3953 \labelwidthstring 00.00.0000
3954 Input Each test which passed 'ignoredTests'
3955 \end_layout
3956
3957 \begin_layout Labeling
3958 \labelwidthstring 00.00.0000
3959 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3960  tests are reported as failing if the export works without error.) If no
3961  subselection applies, gain labels 'export' and 'inverted'.
3962 \end_layout
3963
3964 \begin_layout Standard
3965 The following filter perfoms a subselection of 'invertedTests':
3966 \end_layout
3967
3968 \begin_layout Description
3969 suspendedTests Tests selected here gain the label 'suspended' but _not_
3970  'export' or 'inverted', although in ctest they remain inverted.
3971  ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3972 \end_layout
3973
3974 \begin_deeper
3975 \begin_layout Labeling
3976 \labelwidthstring 00.00.0000
3977 Input Each test selected by 'invertedTests'
3978 \end_layout
3979
3980 \begin_layout Labeling
3981 \labelwidthstring 00.00.0000
3982 Output Selected test gains label 'suspended'.
3983
3984 \end_layout
3985
3986 \end_deeper
3987 \end_deeper
3988 \begin_layout Standard
3989 The following table may clarify label assignement
3990 \end_layout
3991
3992 \begin_layout Standard
3993 \begin_inset space \hspace{}
3994 \length -3cm
3995 \end_inset
3996
3997
3998 \begin_inset Tabular
3999 <lyxtabular version="3" rows="6" columns="8">
4000 <features tabularvalignment="middle">
4001 <column alignment="left" valignment="top" width="2cm">
4002 <column alignment="left" valignment="top" width="2.5cm">
4003 <column alignment="left" valignment="top" width="2cm">
4004 <column alignment="center" valignment="top" width="2.5cm">
4005 <column alignment="center" valignment="top">
4006 <column alignment="center" valignment="top">
4007 <column alignment="center" valignment="top">
4008 <column alignment="center" valignment="top">
4009 <row>
4010 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4011 \begin_inset Text
4012
4013 \begin_layout Plain Layout
4014 Test matching pattern in file:
4015 \end_layout
4016
4017 \end_inset
4018 </cell>
4019 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4020 \begin_inset Text
4021
4022 \begin_layout Plain Layout
4023
4024 \end_layout
4025
4026 \end_inset
4027 </cell>
4028 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4029 \begin_inset Text
4030
4031 \begin_layout Plain Layout
4032
4033 \end_layout
4034
4035 \end_inset
4036 </cell>
4037 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4038 \begin_inset Text
4039
4040 \begin_layout Plain Layout
4041
4042 \end_layout
4043
4044 \end_inset
4045 </cell>
4046 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4047 \begin_inset Text
4048
4049 \begin_layout Plain Layout
4050 Assigned label
4051 \end_layout
4052
4053 \end_inset
4054 </cell>
4055 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4056 \begin_inset Text
4057
4058 \begin_layout Plain Layout
4059
4060 \end_layout
4061
4062 \end_inset
4063 </cell>
4064 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4065 \begin_inset Text
4066
4067 \begin_layout Plain Layout
4068
4069 \end_layout
4070
4071 \end_inset
4072 </cell>
4073 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4074 \begin_inset Text
4075
4076 \begin_layout Plain Layout
4077 test property
4078 \end_layout
4079
4080 \end_inset
4081 </cell>
4082 </row>
4083 <row>
4084 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4085 \begin_inset Text
4086
4087 \begin_layout Plain Layout
4088 ignored\SpecialChar softhyphen
4089 Tests
4090 \end_layout
4091
4092 \end_inset
4093 </cell>
4094 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4095 \begin_inset Text
4096
4097 \begin_layout Plain Layout
4098 unreliable\SpecialChar softhyphen
4099 Tests
4100 \end_layout
4101
4102 \end_inset
4103 </cell>
4104 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4105 \begin_inset Text
4106
4107 \begin_layout Plain Layout
4108 inverted\SpecialChar softhyphen
4109 Tests
4110 \end_layout
4111
4112 \end_inset
4113 </cell>
4114 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4115 \begin_inset Text
4116
4117 \begin_layout Plain Layout
4118 suspended\SpecialChar softhyphen
4119 Tests
4120 \end_layout
4121
4122 \end_inset
4123 </cell>
4124 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4125 \begin_inset Text
4126
4127 \begin_layout Plain Layout
4128 export
4129 \end_layout
4130
4131 \end_inset
4132 </cell>
4133 <cell alignment="center" valignment="top" topline="true" usebox="none">
4134 \begin_inset Text
4135
4136 \begin_layout Plain Layout
4137 inverted
4138 \end_layout
4139
4140 \end_inset
4141 </cell>
4142 <cell alignment="center" valignment="top" topline="true" usebox="none">
4143 \begin_inset Text
4144
4145 \begin_layout Plain Layout
4146 suspended
4147 \end_layout
4148
4149 \end_inset
4150 </cell>
4151 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4152 \begin_inset Text
4153
4154 \begin_layout Plain Layout
4155
4156 \end_layout
4157
4158 \end_inset
4159 </cell>
4160 </row>
4161 <row>
4162 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4163 \begin_inset Text
4164
4165 \begin_layout Plain Layout
4166 Yes
4167 \end_layout
4168
4169 \end_inset
4170 </cell>
4171 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4172 \begin_inset Text
4173
4174 \begin_layout Plain Layout
4175 -
4176 \end_layout
4177
4178 \end_inset
4179 </cell>
4180 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4181 \begin_inset Text
4182
4183 \begin_layout Plain Layout
4184 -
4185 \end_layout
4186
4187 \end_inset
4188 </cell>
4189 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4190 \begin_inset Text
4191
4192 \begin_layout Plain Layout
4193 -
4194 \end_layout
4195
4196 \end_inset
4197 </cell>
4198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4199 \begin_inset Text
4200
4201 \begin_layout Plain Layout
4202 -
4203 \end_layout
4204
4205 \end_inset
4206 </cell>
4207 <cell alignment="center" valignment="top" topline="true" usebox="none">
4208 \begin_inset Text
4209
4210 \begin_layout Plain Layout
4211 -
4212 \end_layout
4213
4214 \end_inset
4215 </cell>
4216 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4217 \begin_inset Text
4218
4219 \begin_layout Plain Layout
4220 -
4221 \end_layout
4222
4223 \end_inset
4224 </cell>
4225 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4226 \begin_inset Text
4227
4228 \begin_layout Plain Layout
4229
4230 \end_layout
4231
4232 \end_inset
4233 </cell>
4234 </row>
4235 <row>
4236 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4237 \begin_inset Text
4238
4239 \begin_layout Plain Layout
4240 No
4241 \end_layout
4242
4243 \end_inset
4244 </cell>
4245 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4246 \begin_inset Text
4247
4248 \begin_layout Plain Layout
4249 If Yes,
4250 \begin_inset Newline newline
4251 \end_inset
4252
4253 add label
4254 \begin_inset Newline newline
4255 \end_inset
4256
4257 'unreliable'
4258 \end_layout
4259
4260 \end_inset
4261 </cell>
4262 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4263 \begin_inset Text
4264
4265 \begin_layout Plain Layout
4266 Yes
4267 \end_layout
4268
4269 \end_inset
4270 </cell>
4271 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4272 \begin_inset Text
4273
4274 \begin_layout Plain Layout
4275 Yes
4276 \end_layout
4277
4278 \end_inset
4279 </cell>
4280 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4281 \begin_inset Text
4282
4283 \begin_layout Plain Layout
4284 -
4285 \end_layout
4286
4287 \end_inset
4288 </cell>
4289 <cell alignment="center" valignment="top" topline="true" usebox="none">
4290 \begin_inset Text
4291
4292 \begin_layout Plain Layout
4293 -
4294 \end_layout
4295
4296 \end_inset
4297 </cell>
4298 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4299 \begin_inset Text
4300
4301 \begin_layout Plain Layout
4302 +
4303 \end_layout
4304
4305 \end_inset
4306 </cell>
4307 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4308 \begin_inset Text
4309
4310 \begin_layout Plain Layout
4311 WILL_FAIL
4312 \end_layout
4313
4314 \end_inset
4315 </cell>
4316 </row>
4317 <row>
4318 <cell multirow="4" alignment="left" 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 multirow="4" alignment="left" valignment="top" topline="true" leftline="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 multirow="4" alignment="left" valignment="top" topline="true" bottomline="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" bottomline="true" leftline="true" usebox="none">
4346 \begin_inset Text
4347
4348 \begin_layout Plain Layout
4349 No
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" rightline="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 WILL_FAIL
4386 \end_layout
4387
4388 \end_inset
4389 </cell>
4390 </row>
4391 <row>
4392 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="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" bottomline="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 alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4411 \begin_inset Text
4412
4413 \begin_layout Plain Layout
4414 No
4415 \end_layout
4416
4417 \end_inset
4418 </cell>
4419 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4420 \begin_inset Text
4421
4422 \begin_layout Plain Layout
4423 -
4424 \end_layout
4425
4426 \end_inset
4427 </cell>
4428 <cell alignment="center" valignment="top" topline="true" bottomline="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" bottomline="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" bottomline="true" rightline="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" bottomline="true" rightline="true" usebox="none">
4456 \begin_inset Text
4457
4458 \begin_layout Plain Layout
4459
4460 \end_layout
4461
4462 \end_inset
4463 </cell>
4464 </row>
4465 </lyxtabular>
4466
4467 \end_inset
4468
4469
4470 \end_layout
4471
4472 \begin_layout Standard
4473 \begin_inset Note Note
4474 status open
4475
4476 \begin_layout Plain Layout
4477 Without the
4478 \begin_inset Quotes eld
4479 \end_inset
4480
4481 suspendedTests
4482 \begin_inset Quotes erd
4483 \end_inset
4484
4485  filter, this would be far less complicated:
4486 \end_layout
4487
4488 \begin_layout Plain Layout
4489 \begin_inset Tabular
4490 <lyxtabular version="3" rows="6" columns="7">
4491 <features tabularvalignment="middle">
4492 <column alignment="left" valignment="top" width="0pt">
4493 <column alignment="left" valignment="top" width="0pt">
4494 <column alignment="left" valignment="top" width="0pt">
4495 <column alignment="center" valignment="top">
4496 <column alignment="center" valignment="top">
4497 <column alignment="center" valignment="top">
4498 <column alignment="center" valignment="top">
4499 <row>
4500 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4501 \begin_inset Text
4502
4503 \begin_layout Plain Layout
4504 Test matching pattern in file:
4505 \end_layout
4506
4507 \end_inset
4508 </cell>
4509 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4510 \begin_inset Text
4511
4512 \begin_layout Plain Layout
4513
4514 \end_layout
4515
4516 \end_inset
4517 </cell>
4518 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4519 \begin_inset Text
4520
4521 \begin_layout Plain Layout
4522
4523 \end_layout
4524
4525 \end_inset
4526 </cell>
4527 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4528 \begin_inset Text
4529
4530 \begin_layout Plain Layout
4531 Label
4532 \end_layout
4533
4534 \end_inset
4535 </cell>
4536 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4537 \begin_inset Text
4538
4539 \begin_layout Plain Layout
4540
4541 \end_layout
4542
4543 \end_inset
4544 </cell>
4545 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4546 \begin_inset Text
4547
4548 \begin_layout Plain Layout
4549
4550 \end_layout
4551
4552 \end_inset
4553 </cell>
4554 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4555 \begin_inset Text
4556
4557 \begin_layout Plain Layout
4558 test property
4559 \end_layout
4560
4561 \end_inset
4562 </cell>
4563 </row>
4564 <row>
4565 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4566 \begin_inset Text
4567
4568 \begin_layout Plain Layout
4569 ignoredTests
4570 \end_layout
4571
4572 \end_inset
4573 </cell>
4574 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4575 \begin_inset Text
4576
4577 \begin_layout Plain Layout
4578 unreliableTests
4579 \end_layout
4580
4581 \end_inset
4582 </cell>
4583 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4584 \begin_inset Text
4585
4586 \begin_layout Plain Layout
4587 invertedTests
4588 \end_layout
4589
4590 \end_inset
4591 </cell>
4592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4593 \begin_inset Text
4594
4595 \begin_layout Plain Layout
4596 export
4597 \end_layout
4598
4599 \end_inset
4600 </cell>
4601 <cell alignment="center" valignment="top" topline="true" usebox="none">
4602 \begin_inset Text
4603
4604 \begin_layout Plain Layout
4605 unreliable
4606 \end_layout
4607
4608 \end_inset
4609 </cell>
4610 <cell alignment="center" valignment="top" topline="true" usebox="none">
4611 \begin_inset Text
4612
4613 \begin_layout Plain Layout
4614 inverted
4615 \end_layout
4616
4617 \end_inset
4618 </cell>
4619 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4620 \begin_inset Text
4621
4622 \begin_layout Plain Layout
4623
4624 \end_layout
4625
4626 \end_inset
4627 </cell>
4628 </row>
4629 <row>
4630 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4631 \begin_inset Text
4632
4633 \begin_layout Plain Layout
4634 Yes
4635 \end_layout
4636
4637 \end_inset
4638 </cell>
4639 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4640 \begin_inset Text
4641
4642 \begin_layout Plain Layout
4643 -
4644 \end_layout
4645
4646 \end_inset
4647 </cell>
4648 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4649 \begin_inset Text
4650
4651 \begin_layout Plain Layout
4652 -
4653 \end_layout
4654
4655 \end_inset
4656 </cell>
4657 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4658 \begin_inset Text
4659
4660 \begin_layout Plain Layout
4661 -
4662 \end_layout
4663
4664 \end_inset
4665 </cell>
4666 <cell alignment="center" valignment="top" topline="true" usebox="none">
4667 \begin_inset Text
4668
4669 \begin_layout Plain Layout
4670
4671 \end_layout
4672
4673 \end_inset
4674 </cell>
4675 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4676 \begin_inset Text
4677
4678 \begin_layout Plain Layout
4679 -
4680 \end_layout
4681
4682 \end_inset
4683 </cell>
4684 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4685 \begin_inset Text
4686
4687 \begin_layout Plain Layout
4688
4689 \end_layout
4690
4691 \end_inset
4692 </cell>
4693 </row>
4694 <row>
4695 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4696 \begin_inset Text
4697
4698 \begin_layout Plain Layout
4699 No
4700 \end_layout
4701
4702 \end_inset
4703 </cell>
4704 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4705 \begin_inset Text
4706
4707 \begin_layout Plain Layout
4708 Yes
4709 \end_layout
4710
4711 \end_inset
4712 </cell>
4713 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4714 \begin_inset Text
4715
4716 \begin_layout Plain Layout
4717 -
4718 \end_layout
4719
4720 \end_inset
4721 </cell>
4722 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4723 \begin_inset Text
4724
4725 \begin_layout Plain Layout
4726 -
4727 \end_layout
4728
4729 \end_inset
4730 </cell>
4731 <cell alignment="center" valignment="top" topline="true" usebox="none">
4732 \begin_inset Text
4733
4734 \begin_layout Plain Layout
4735 +
4736 \end_layout
4737
4738 \end_inset
4739 </cell>
4740 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4741 \begin_inset Text
4742
4743 \begin_layout Plain Layout
4744 -
4745 \end_layout
4746
4747 \end_inset
4748 </cell>
4749 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4750 \begin_inset Text
4751
4752 \begin_layout Plain Layout
4753
4754 \end_layout
4755
4756 \end_inset
4757 </cell>
4758 </row>
4759 <row>
4760 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4761 \begin_inset Text
4762
4763 \begin_layout Plain Layout
4764
4765 \end_layout
4766
4767 \end_inset
4768 </cell>
4769 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4770 \begin_inset Text
4771
4772 \begin_layout Plain Layout
4773 No
4774 \end_layout
4775
4776 \end_inset
4777 </cell>
4778 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4779 \begin_inset Text
4780
4781 \begin_layout Plain Layout
4782 Yes
4783 \end_layout
4784
4785 \end_inset
4786 </cell>
4787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4788 \begin_inset Text
4789
4790 \begin_layout Plain Layout
4791 +
4792 \end_layout
4793
4794 \end_inset
4795 </cell>
4796 <cell alignment="center" valignment="top" topline="true" usebox="none">
4797 \begin_inset Text
4798
4799 \begin_layout Plain Layout
4800 -
4801 \end_layout
4802
4803 \end_inset
4804 </cell>
4805 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4806 \begin_inset Text
4807
4808 \begin_layout Plain Layout
4809 +
4810 \end_layout
4811
4812 \end_inset
4813 </cell>
4814 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4815 \begin_inset Text
4816
4817 \begin_layout Plain Layout
4818 WILL_FAIL
4819 \end_layout
4820
4821 \end_inset
4822 </cell>
4823 </row>
4824 <row>
4825 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4826 \begin_inset Text
4827
4828 \begin_layout Plain Layout
4829
4830 \end_layout
4831
4832 \end_inset
4833 </cell>
4834 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4835 \begin_inset Text
4836
4837 \begin_layout Plain Layout
4838
4839 \end_layout
4840
4841 \end_inset
4842 </cell>
4843 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4844 \begin_inset Text
4845
4846 \begin_layout Plain Layout
4847 No
4848 \end_layout
4849
4850 \end_inset
4851 </cell>
4852 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4853 \begin_inset Text
4854
4855 \begin_layout Plain Layout
4856 +
4857 \end_layout
4858
4859 \end_inset
4860 </cell>
4861 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4862 \begin_inset Text
4863
4864 \begin_layout Plain Layout
4865 -
4866 \end_layout
4867
4868 \end_inset
4869 </cell>
4870 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4871 \begin_inset Text
4872
4873 \begin_layout Plain Layout
4874 -
4875 \end_layout
4876
4877 \end_inset
4878 </cell>
4879 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4880 \begin_inset Text
4881
4882 \begin_layout Plain Layout
4883
4884 \end_layout
4885
4886 \end_inset
4887 </cell>
4888 </row>
4889 </lyxtabular>
4890
4891 \end_inset
4892
4893
4894 \end_layout
4895
4896 \end_inset
4897
4898
4899 \end_layout
4900
4901 \begin_layout Subsection
4902 check_load tests
4903 \end_layout
4904
4905 \begin_layout Standard
4906 These tests check whether a .lyx file loads without any terminal messages.
4907  They correspond to the manual operations of simply opening a .lyx file on
4908  the terminal, exiting LyX once the file is loaded, and then checking whether
4909  there is any output from the terminal.
4910  These tests are useful for catching malformed .lyx files and parsing bugs.
4911  They can also be used to find a .lyx file in which an instance of something
4912  happens.
4913  To do this, compile LyX with a local patch that outputs something to the
4914  terminal when an instance is found, and then run the check_load tests to
4915  see if any fail, which would mean that the situation occurs in the LyX
4916  documentation files corresponding to the failed tests.
4917  These tests are expectedly fragile: any LyX diagnostic message, which is
4918  not necessarily an error, would cause the tests to fail.
4919  Similarly, any message output by a library (e.g.
4920  Qt) would also cause failure.
4921  There are some messages that the check_load tests are instructed to ignore,
4922  which are stored in the file
4923 \begin_inset Flex Code
4924 status collapsed
4925
4926 \begin_layout Plain Layout
4927 development/autotests/filterCheckWarnings
4928 \end_layout
4929
4930 \end_inset
4931
4932 .
4933 \end_layout
4934
4935 \begin_layout Standard
4936 Under cmake, the tests are labeled as 'load'.
4937 \end_layout
4938
4939 \begin_layout Subsection
4940 Keytests
4941 \end_layout
4942
4943 \begin_layout Standard
4944 Automated tests based on the "MonKey Testing" keytest program are enabled
4945  if the necessary dependencies are found and if the CMake flag
4946 \begin_inset Flex Code
4947 status collapsed
4948
4949 \begin_layout Plain Layout
4950 -DLYX_ENABLE_KEYTESTS=ON
4951 \end_layout
4952
4953 \end_inset
4954
4955  is used.
4956  They are documented in the README document in
4957 \begin_inset Flex Code
4958 status collapsed
4959
4960 \begin_layout Plain Layout
4961 development/autotests
4962 \end_layout
4963
4964 \end_inset
4965
4966  subfolder of the \SpecialChar LyX
4967  source code distribution.
4968 \end_layout
4969
4970 \begin_layout Subsection
4971 lyx21 tests
4972 \end_layout
4973
4974 \begin_layout Standard
4975 These tests combine lyx2lyx tests with check_load tests.
4976  They fail if either fails.
4977 \end_layout
4978
4979 \begin_layout Subsection
4980 URL tests
4981 \end_layout
4982
4983 \begin_layout Standard
4984 The URL tests are enabled with the
4985 \begin_inset Flex Code
4986 status collapsed
4987
4988 \begin_layout Plain Layout
4989 -DLYX_ENABLE_URLTESTS=ON
4990 \end_layout
4991
4992 \end_inset
4993
4994  CMake flag and are useful for finding broken links in our documentation
4995  files.
4996  If a URL test fails, to see which link in particular was reported as broken,
4997  see the output in
4998 \begin_inset Flex Code
4999 status collapsed
5000
5001 \begin_layout Plain Layout
5002 LastTest.log
5003 \end_layout
5004
5005 \end_inset
5006
5007 .
5008  These tests are extremely fragile (e.g.
5009  a test can depend on your Internet connection) and a failed URL test should
5010  not be taken too seriously.
5011  URL tests are labeled as
5012 \family typewriter
5013 'url'.
5014 \end_layout
5015
5016 \begin_layout Subsubsection
5017 Running URL tests
5018 \end_layout
5019
5020 \begin_layout Standard
5021 cmake is required to run the \SpecialChar LyX
5022  tests, running them is not implemented for
5023  autotools.
5024 \end_layout
5025
5026 \begin_layout Standard
5027 The appropriate commands are:
5028 \end_layout
5029
5030 \begin_layout Itemize
5031
5032 \family typewriter
5033 ctest -L url
5034 \family default
5035
5036 \begin_inset Newline newline
5037 \end_inset
5038
5039 runs all tests with label
5040 \family typewriter
5041 'url'
5042 \end_layout
5043
5044 \begin_layout Itemize
5045
5046 \family typewriter
5047 ctest -R 'check_.*urls'
5048 \family default
5049
5050 \begin_inset Newline newline
5051 \end_inset
5052
5053 runs the tests 'check_accessible_urls'
5054 \end_layout
5055
5056 \begin_layout Standard
5057 Associated test results can be examined in ctest-log directory in files
5058  of the form 'LastFailed.*URLS.log'
5059 \end_layout
5060
5061 \begin_layout Chapter
5062 Development policies
5063 \end_layout
5064
5065 \begin_layout Standard
5066 This chapter lists some guidelines that should be followed.
5067  This list is not complete, and many guidelines are in separate chapters,
5068  such as
5069 \begin_inset Quotes eld
5070 \end_inset
5071
5072 When is an update of the .lyx file format number needed?
5073 \begin_inset Quotes erd
5074 \end_inset
5075
5076  in Section
5077 \begin_inset CommandInset ref
5078 LatexCommand ref
5079 reference "sec:When-is-an"
5080
5081 \end_inset
5082
5083 .
5084 \end_layout
5085
5086 \begin_layout Section
5087 When to set a fixed milestone?
5088 \end_layout
5089
5090 \begin_layout Standard
5091 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5092  holds:
5093 \end_layout
5094
5095 \begin_layout Enumerate
5096 Somebody is actively working on a fix.
5097 \end_layout
5098
5099 \begin_layout Enumerate
5100 The bug is so severe that it would block the release if it is not fixed.
5101 \end_layout
5102
5103 \begin_layout Standard
5104 If a bug is important, but nobody is working on it, and it is no showstopper,
5105  use a milestone like 2.1.x or 2.2.x.
5106  For all other bugs, do not set a milestone at all.
5107 \end_layout
5108
5109 \begin_layout Section
5110 Can we add rc entries in stable branch?
5111 \end_layout
5112
5113 \begin_layout Standard
5114 No.
5115  We are supposed to increase the prefs2prefs version number with such things.
5116 \end_layout
5117
5118 \begin_layout Chapter
5119 \begin_inset CommandInset label
5120 LatexCommand label
5121 name "sec:Documentation-policies"
5122
5123 \end_inset
5124
5125 Documentation policies
5126 \end_layout
5127
5128 \begin_layout Section
5129 Rules
5130 \end_layout
5131
5132 \begin_layout Standard
5133 There are 6
5134 \begin_inset space ~
5135 \end_inset
5136
5137 rules in editing the docs:
5138 \end_layout
5139
5140 \begin_layout Enumerate
5141 \begin_inset CommandInset label
5142 LatexCommand label
5143 name "enu:If-you-are"
5144
5145 \end_inset
5146
5147 If you are not the maintainer of a doc file or a chapter/section, you MUST
5148  use change tracking so that the maintainer could review your changes
5149 \end_layout
5150
5151 \begin_layout Enumerate
5152 Respect the formatting of the document.
5153  The different files use different formatting styles.
5154  That is OK and has historic reasons nobody fully knows ;-).
5155  But it is important to be consistent within one file.
5156 \end_layout
5157
5158 \begin_layout Enumerate
5159 All changes you make to a file in one language MUST also go the file in
5160  the other actively maintained languages.
5161  Normally the maintainer does this for you, if you are the maintainer, you
5162  must do this by copying or changing the changed or added text to the other
5163  files so that the translators sees the blue underlined text and know what
5164  they have to translate and what was changed.
5165 \end_layout
5166
5167 \begin_layout Enumerate
5168 You MUST assure that the document is compilable as
5169 \begin_inset Quotes eld
5170 \end_inset
5171
5172 PDF (pdflatex)
5173 \begin_inset Quotes erd
5174 \end_inset
5175
5176  or the document's default output format after your changes.
5177 \end_layout
5178
5179 \begin_layout Enumerate
5180 All fixes (typos, compilation fixes, updates info etc.) go at first into
5181  the current GIT branch because the user should benefit from all fixes with
5182  every minor release.
5183  Feel free to commit directly to branch as long as you follow rule
5184 \begin_inset space ~
5185 \end_inset
5186
5187
5188 \begin_inset CommandInset ref
5189 LatexCommand ref
5190 reference "enu:If-you-are"
5191
5192 \end_inset
5193
5194 .
5195  You can immediately commit to master as well.
5196 \end_layout
5197
5198 \begin_layout Enumerate
5199 \begin_inset CommandInset label
5200 LatexCommand label
5201 name "enu:The-fileformat-of"
5202
5203 \end_inset
5204
5205 The fileformat of a file must not be changed unless you document a new feature
5206  in LyX that requires a new fileformat.
5207  The reason for this rule is to keep it easy for the doc maintainers to
5208  port/backport changes to from master/branch.
5209 \end_layout
5210
5211 \begin_layout Standard
5212 The main documentation consists of these files:
5213 \end_layout
5214
5215 \begin_layout Description
5216 Welcome.lyx it is the first file you see after an installation.
5217  We assume that a new user sees this.
5218  It is therefore designed to be as simple as possible.
5219  Therefore please don't add any new formatting, only fix typos etc.
5220  Welcome.lyx is up to date for \SpecialChar LyX
5221  2.1.x, currently maintained by Uwe Stöhr.
5222 \end_layout
5223
5224 \begin_layout Description
5225 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5226 .
5227  It therefore uses a limited set of formatting.
5228  For example a standard document class.
5229  Since new users will first learn about the formatting possibilities of
5230  \SpecialChar LyX
5231  please keep this file that simple.
5232  Intro.lyx is up to date for \SpecialChar LyX
5233  2.1.x, currently maintained by Uwe Stöhr.
5234 \end_layout
5235
5236 \begin_layout Description
5237 Tutorial.lyx our tutorial.
5238  It must be always up to date.
5239  Normally there is nothing to add since we don't want to overwhelm new users
5240  with too much details.
5241  The will learn these details while using \SpecialChar LyX
5242  and we have special manuals.
5243  Tutorial.lyx is up to date for \SpecialChar LyX
5244  2.1.x, currently maintained by Uwe Stöhr.
5245 \end_layout
5246
5247 \begin_layout Description
5248 UserGuide.lyx our main user guide.
5249  It covers a mixture of basic and detailed information.
5250  Some information is also in the Math and EmbeddedObjects manual so that
5251  the UserGuide refers to these files.
5252  UserGuide.lyx is up to date for \SpecialChar LyX
5253  2.1.x, currently maintained by Uwe Stöhr.
5254 \end_layout
5255
5256 \begin_layout Description
5257 EmbeddedObjects.lyx a special manual to explain things like tables floats
5258  boxes etc.
5259  in all detail.
5260  EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5261  2.1.x, currently maintained by Uwe
5262  Stöhr.
5263 \end_layout
5264
5265 \begin_layout Description
5266 Math.lyx a special manual to explain everything regarding math in all detail.
5267  Math.lyx is up to date for \SpecialChar LyX
5268  2.1.x, currently maintained by Uwe Stöhr.
5269 \end_layout
5270
5271 \begin_layout Description
5272 Additional.lyx this manual covers information that would be too much detail
5273  for the UserGuide or would make the UserGuide uncompilable or only compilable
5274  when installing a lot of special \SpecialChar LaTeX
5275 -packages.
5276  What should be in the UserGuide or better in Additional is a matter of
5277  taste.
5278  it is up to you to decide that.
5279  Additional.lyx is not completely up to date for \SpecialChar LyX
5280  2.1.x.
5281  Only chapter
5282 \begin_inset space ~
5283 \end_inset
5284
5285 8 is up to date and currently maintained by Uwe Stöhr.
5286  It certainly needs a rewrite and update.
5287  For example many info in chapter
5288 \begin_inset space ~
5289 \end_inset
5290
5291 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5292  manual.
5293 \end_layout
5294
5295 \begin_layout Description
5296 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5297  for certain
5298  output formats, operating systems, languages etc.
5299  It is currently completely out of date and needs a major rewrite and update.
5300  If you do this please assure that your information are given for all OSes
5301  and \SpecialChar LaTeX
5302  distributions (meaning be as objective as possible).
5303 \end_layout
5304
5305 \begin_layout Chapter
5306 Coding rules
5307 \end_layout
5308
5309 \begin_layout Standard
5310 The aim of this chapter is to serve as a guide for the developers, to aid
5311  us to get clean and uniform code.
5312  It is incomplete.
5313  We really like to have new developers joining the \SpecialChar LyX
5314  Project.
5315  However, we have had problems in the past with developers leaving the project
5316  and their contributed code in a far from perfect state.
5317  Most of this happened before we really became aware of these issues, but
5318  still, we don't want it to happen again.
5319  So we have put together some guidelines and rules for the developers.
5320 \end_layout
5321
5322 \begin_layout Section
5323 General
5324 \end_layout
5325
5326 \begin_layout Standard
5327 These guidelines should save us a lot of work while cleaning up the code
5328  and help us to have quality code.
5329  \SpecialChar LyX
5330  has been haunted by problems coming from unfinished projects by people
5331  who have left the team.
5332  Those problems will hopefully disappear if the code is easy to hand over
5333  to somebody else.
5334  In general, if you want to contribute to the main source, we expect at
5335  least that you:
5336 \end_layout
5337
5338 \begin_layout Itemize
5339 The most important rule first: KISS (Keep It Simple Stupid), always use
5340  a simple implementation in favor of a more complicated one.
5341  This eases maintenance a lot.
5342 \end_layout
5343
5344 \begin_layout Itemize
5345 Write good C++ code: readable, well commented, and taking advantage of the
5346  OO model.
5347  Follow the formatting guidelines.
5348  See sec.
5349 \begin_inset space ~
5350 \end_inset
5351
5352
5353 \begin_inset CommandInset ref
5354 LatexCommand ref
5355 reference "sec:Formatting"
5356 plural "false"
5357 caps "false"
5358 noprefix "false"
5359
5360 \end_inset
5361
5362 .
5363 \end_layout
5364
5365 \begin_layout Itemize
5366 As of LyX 2.4.0, you can use features of C++11.
5367  Accordingly you have to use C++11 standard conforming compiler, e.
5368 \begin_inset space \thinspace{}
5369 \end_inset
5370
5371 g.
5372  not too dated version of GCC or Clang.
5373 \end_layout
5374
5375 \begin_layout Itemize
5376 Adapt the code to the structures already existing in \SpecialChar LyX
5377 , or in the case that
5378  you have better ideas, discuss them on the developer's list before writing
5379  the code.
5380 \end_layout
5381
5382 \begin_layout Itemize
5383 Take advantage of the C++ standard library.
5384  Especially don't use custom containers when a standard container is usable;
5385  learn to use the algorithms and functors in the standard library.
5386 \end_layout
5387
5388 \begin_layout Itemize
5389 Be aware of exceptions and write exception safe code.
5390  See sec.
5391 \begin_inset space ~
5392 \end_inset
5393
5394
5395 \begin_inset CommandInset ref
5396 LatexCommand ref
5397 reference "sec:Exceptions"
5398 plural "false"
5399 caps "false"
5400 noprefix "false"
5401
5402 \end_inset
5403
5404 .
5405 \end_layout
5406
5407 \begin_layout Itemize
5408 Document all variables, methods, functions, classes etc.
5409  We are using the source documentation program doxygen, a program that handles
5410  javadoc syntax, to document sources.
5411  You can download doxygen from:
5412 \begin_inset Flex URL
5413 status open
5414
5415 \begin_layout Plain Layout
5416
5417 http://www.stack.nl/~dimitri/doxygen/
5418 \end_layout
5419
5420 \end_inset
5421
5422
5423 \end_layout
5424
5425 \begin_layout Itemize
5426 We have certain code constructs that we try to follow.
5427  See sec.
5428 \begin_inset space ~
5429 \end_inset
5430
5431
5432 \begin_inset CommandInset ref
5433 LatexCommand ref
5434 reference "sec:Code-constructs"
5435 plural "false"
5436 caps "false"
5437 noprefix "false"
5438
5439 \end_inset
5440
5441 .
5442 \end_layout
5443
5444 \begin_layout Section
5445 Submitting code
5446 \end_layout
5447
5448 \begin_layout Standard
5449 It is implicitly understood that all patches contributed to The \SpecialChar LyX
5450  Project
5451  is under the Gnu General Public License, version 2 or later.
5452  If you have a problem with that, don't contribute code.
5453  Also please don't just pop up out of the blue with a huge patch (or small)
5454  that changes something substantial in \SpecialChar LyX
5455 .
5456  Always discuss your ideas with the developers on the developer's mailing
5457  list.
5458  When you create the patch, please use
5459 \begin_inset Quotes eld
5460 \end_inset
5461
5462
5463 \family typewriter
5464 diff -up
5465 \family default
5466
5467 \begin_inset Quotes erd
5468 \end_inset
5469
5470  since we find that a lot easier to read than the other diff formats.
5471  Also please do not send patches that implements or fixes several different
5472  things; several patches is a much better option.
5473  We also require you to provide a commit message entry with every patch,
5474  this describes in detail what the patch is doing.
5475
5476 \end_layout
5477
5478 \begin_layout Section
5479 Code constructs
5480 \begin_inset CommandInset label
5481 LatexCommand label
5482 name "sec:Code-constructs"
5483
5484 \end_inset
5485
5486
5487 \end_layout
5488
5489 \begin_layout Standard
5490 We have several guidelines on code constructs, some of these exist to make
5491  the code faster, others to make the code clearer.
5492  Yet others exist to allow us to take advantage of the strong type checking
5493  in C++.
5494 \end_layout
5495
5496 \begin_layout Itemize
5497 Declaration of variables should wait as long as possible.
5498  The rule is:
5499 \begin_inset Quotes eld
5500 \end_inset
5501
5502 Don't declare it until you need it.
5503 \begin_inset Quotes erd
5504 \end_inset
5505
5506  In C++ there are a lot of user defined types, and these can very often
5507  be expensive to initialize.
5508  This rule connects to the next rule too.
5509
5510 \end_layout
5511
5512 \begin_layout Itemize
5513 Declare the variable as
5514 \begin_inset Flex Code
5515 status collapsed
5516
5517 \begin_layout Plain Layout
5518 const
5519 \end_layout
5520
5521 \end_inset
5522
5523  if you don't need to change it.
5524  This applies to POD types like
5525 \begin_inset Flex Code
5526 status collapsed
5527
5528 \begin_layout Plain Layout
5529 int
5530 \end_layout
5531
5532 \end_inset
5533
5534  as well as classes.
5535
5536 \end_layout
5537
5538 \begin_layout Itemize
5539 Make the scope of a variable as small as possible.
5540 \end_layout
5541
5542 \begin_layout Itemize
5543 Make good use of namespaces.
5544  Prefer anonymous namespaces to declaring
5545 \begin_inset Flex Code
5546 status collapsed
5547
5548 \begin_layout Plain Layout
5549 static
5550 \end_layout
5551
5552 \end_inset
5553
5554  for file scope.
5555 \end_layout
5556
5557 \begin_layout Itemize
5558 Prefer preincrement to postincrement whenever possible.
5559 \end_layout
5560
5561 \begin_layout Itemize
5562 Preincrement has potential of being faster than postincrement.
5563  Just think about the obvious implementations of pre/post-increment.
5564  This rule applies to decrement too.
5565 \end_layout
5566
5567 \begin_layout Itemize
5568 Use:
5569 \begin_inset Separator latexpar
5570 \end_inset
5571
5572
5573 \end_layout
5574
5575 \begin_deeper
5576 \begin_layout Standard
5577 \begin_inset listings
5578 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5579 inline false
5580 status open
5581
5582 \begin_layout Plain Layout
5583
5584 ++T;
5585 \end_layout
5586
5587 \begin_layout Plain Layout
5588
5589 --U;
5590 \end_layout
5591
5592 \end_inset
5593
5594
5595 \end_layout
5596
5597 \begin_layout Standard
5598 Do not use:
5599 \end_layout
5600
5601 \begin_layout Standard
5602 \begin_inset listings
5603 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5604 inline false
5605 status open
5606
5607 \begin_layout Plain Layout
5608
5609 T++; // not used in LyX
5610 \end_layout
5611
5612 \begin_layout Plain Layout
5613
5614 U--; // not used in LyX
5615 \end_layout
5616
5617 \end_inset
5618
5619
5620 \end_layout
5621
5622 \end_deeper
5623 \begin_layout Itemize
5624 Try to minimize evaluation of the same code over and over.
5625  This is aimed especially at loops.
5626
5627 \begin_inset Newline newline
5628 \end_inset
5629
5630 Use:
5631 \begin_inset Separator latexpar
5632 \end_inset
5633
5634
5635 \end_layout
5636
5637 \begin_deeper
5638 \begin_layout Standard
5639 \begin_inset listings
5640 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5641 inline false
5642 status open
5643
5644 \begin_layout Plain Layout
5645
5646 Container::iterator end = large.end();
5647 \end_layout
5648
5649 \begin_layout Plain Layout
5650
5651 for (Container::iterator it = large.begin(); it != end; ++it) {
5652 \end_layout
5653
5654 \begin_layout Plain Layout
5655
5656         ...;
5657 \end_layout
5658
5659 \begin_layout Plain Layout
5660
5661 }
5662 \end_layout
5663
5664 \end_inset
5665
5666
5667 \end_layout
5668
5669 \begin_layout Standard
5670 Or better (C++11):
5671 \end_layout
5672
5673 \begin_layout Standard
5674 \begin_inset listings
5675 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5676 inline false
5677 status open
5678
5679 \begin_layout Plain Layout
5680
5681 for (auto const & it : large) {
5682 \end_layout
5683
5684 \begin_layout Plain Layout
5685
5686         ...;
5687 \end_layout
5688
5689 \begin_layout Plain Layout
5690
5691 }
5692 \end_layout
5693
5694 \end_inset
5695
5696
5697 \end_layout
5698
5699 \begin_layout Standard
5700 Do not use:
5701 \end_layout
5702
5703 \begin_layout Standard
5704 \begin_inset listings
5705 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5706 inline false
5707 status open
5708
5709 \begin_layout Plain Layout
5710
5711 for (Container::iterator it = large.begin(); it != large.end(); ++it) {
5712 \end_layout
5713
5714 \begin_layout Plain Layout
5715
5716         ...;
5717 \end_layout
5718
5719 \begin_layout Plain Layout
5720
5721 }
5722 \end_layout
5723
5724 \end_inset
5725
5726
5727 \end_layout
5728
5729 \end_deeper
5730 \begin_layout Itemize
5731 For functions and methods that return a non-POD type
5732 \begin_inset Foot
5733 status open
5734
5735 \begin_layout Plain Layout
5736 Plain Ol' Data type
5737 \end_layout
5738
5739 \end_inset
5740
5741
5742 \begin_inset Flex Code
5743 status collapsed
5744
5745 \begin_layout Plain Layout
5746 T
5747 \end_layout
5748
5749 \end_inset
5750
5751 , return
5752 \begin_inset Flex Code
5753 status collapsed
5754
5755 \begin_layout Plain Layout
5756 T const
5757 \end_layout
5758
5759 \end_inset
5760
5761  instead.
5762  This gives better type checking, and will give a compiler warning when
5763  temporaries are used wrongly.
5764 \begin_inset Separator latexpar
5765 \end_inset
5766
5767
5768 \end_layout
5769
5770 \begin_deeper
5771 \begin_layout Standard
5772 Use:
5773 \end_layout
5774
5775 \begin_layout Standard
5776 \begin_inset listings
5777 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5778 inline false
5779 status open
5780
5781 \begin_layout Plain Layout
5782
5783 T const add(...);
5784 \end_layout
5785
5786 \end_inset
5787
5788
5789 \end_layout
5790
5791 \begin_layout Standard
5792 Do not use:
5793 \end_layout
5794
5795 \begin_layout Standard
5796 \begin_inset listings
5797 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5798 inline false
5799 status open
5800
5801 \begin_layout Plain Layout
5802
5803 T add(...);
5804 \end_layout
5805
5806 \end_inset
5807
5808
5809 \end_layout
5810
5811 \end_deeper
5812 \begin_layout Itemize
5813 Avoid using the default cases in switch statements unless you have too.
5814  Use the correct type for the switch expression and let the compiler ensure
5815  that all cases are exhausted.
5816 \end_layout
5817
5818 \begin_layout Itemize
5819 \begin_inset listings
5820 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5821 inline false
5822 status open
5823
5824 \begin_layout Plain Layout
5825
5826 enum Foo {
5827 \end_layout
5828
5829 \begin_layout Plain Layout
5830
5831         FOO_BAR1,
5832 \end_layout
5833
5834 \begin_layout Plain Layout
5835
5836         FOO_BAR2
5837 \end_layout
5838
5839 \begin_layout Plain Layout
5840
5841 };
5842 \end_layout
5843
5844 \begin_layout Plain Layout
5845
5846 \end_layout
5847
5848 \begin_layout Plain Layout
5849
5850 Foo f = ...;
5851 \end_layout
5852
5853 \begin_layout Plain Layout
5854
5855 \end_layout
5856
5857 \begin_layout Plain Layout
5858
5859 switch (f) {
5860 \end_layout
5861
5862 \begin_layout Plain Layout
5863
5864 case FOO_BAR1: ...;
5865 \end_layout
5866
5867 \begin_layout Plain Layout
5868
5869         break;
5870 \end_layout
5871
5872 \begin_layout Plain Layout
5873
5874 case FOO_BAR2: ...;
5875 \end_layout
5876
5877 \begin_layout Plain Layout
5878
5879         break;
5880 \end_layout
5881
5882 \begin_layout Plain Layout
5883
5884 default: ...;
5885 \end_layout
5886
5887 \begin_layout Plain Layout
5888
5889         // not needed and would shadow a wrong use of Foo
5890 \end_layout
5891
5892 \begin_layout Plain Layout
5893
5894         break;
5895 \end_layout
5896
5897 \begin_layout Plain Layout
5898
5899 }
5900 \end_layout
5901
5902 \end_inset
5903
5904
5905 \end_layout
5906
5907 \begin_layout Section
5908 Exceptions
5909 \begin_inset CommandInset label
5910 LatexCommand label
5911 name "sec:Exceptions"
5912
5913 \end_inset
5914
5915
5916 \end_layout
5917
5918 \begin_layout Standard
5919 Be aware of the presence of exceptions.
5920  One important thing to realize is that you often do not have to use throw,
5921  try or catch to be exception safe.
5922  Let's look at the different types of exceptions safety (these are taken
5923  from Herb Sutter's book
5924 \begin_inset CommandInset citation
5925 LatexCommand cite
5926 key "sutter"
5927 literal "false"
5928
5929 \end_inset
5930
5931 ):
5932 \end_layout
5933
5934 \begin_layout Enumerate
5935 Basic guarantee: Even in the presence of exceptions thrown by T or other
5936  exceptions, Stack objects don't leak resources.
5937  Note that this also implies that the container will be destructible and
5938  usable even if an exception is thrown while performing some container operation.
5939  However, if an exception is thrown, the container will be in a consistent,
5940  but not necessarily predictable, state.
5941  Containers that support the basic guarantee can work safely in some settings.
5942
5943 \end_layout
5944
5945 \begin_layout Enumerate
5946 Strong guarantee: If an operation terminates because of an exception, program
5947  state will remain unchanged.
5948  This always implies commit-or-rollback semantics, including that no references
5949  or iterators into the container be invalidated if an operation fails.
5950  For example, if a Stack client calls Top and then attempts a Push that
5951  fails because of an exception, then the state of the Stack object must
5952  be unchanged and the reference returned from the prior call to Top must
5953  still be valid.
5954  For more information on these guarantees, see Dave Abrahams's documentation
5955  of the SGI exception-safe standard library adaption at:
5956 \begin_inset Flex URL
5957 status open
5958
5959 \begin_layout Plain Layout
5960
5961 http://www.stlport.org/doc/exception_safety.html
5962 \end_layout
5963
5964 \end_inset
5965
5966  Probably the most interesting point here is that when you implement the
5967  basic guarantee, the strong guarantee often comes for free.
5968  For example, in our Stack implementation, almost everything we did was
5969  needed to satisfy just the basic guarantee – and what's presented above
5970  very nearly satisfies the strong guarantee, with little or no extra work.
5971  Not half bad, considering all the trouble we went to.
5972  In addition to these two guarantees, there is one more guarantee that certain
5973  functions must provide in order to make overall exception safety possible:
5974 \end_layout
5975
5976 \begin_layout Enumerate
5977 No throw guarantee: The function will not emit an exception under any circumstan
5978 ces.
5979  Overall exception safety isn't possible unless certain functions are guaranteed
5980  not to throw.
5981  In particular, we've seen that this is true for destructors; later in this
5982  miniseries, we'll see that it's also needed in certain helper functions,
5983  such as
5984 \family typewriter
5985 Swap()
5986 \family default
5987 .
5988 \end_layout
5989
5990 \begin_layout Standard
5991 For all cases where we might be able to write exception safe functions without
5992  using try, throw or catch we should do so.
5993  In particular we should look over all destructors to ensure that they are
5994  as exception safe as possible.
5995 \end_layout
5996
5997 \begin_layout Section
5998 Formatting
5999 \begin_inset CommandInset label
6000 LatexCommand label
6001 name "sec:Formatting"
6002
6003 \end_inset
6004
6005
6006 \end_layout
6007
6008 \begin_layout Itemize
6009 Only one declaration on each line.
6010 \begin_inset Separator latexpar
6011 \end_inset
6012
6013
6014 \end_layout
6015
6016 \begin_deeper
6017 \begin_layout Standard
6018 Use:
6019 \end_layout
6020
6021 \begin_layout Standard
6022 \begin_inset listings
6023 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6024 inline false
6025 status open
6026
6027 \begin_layout Plain Layout
6028
6029 int a;
6030 \end_layout
6031
6032 \begin_layout Plain Layout
6033
6034 int b;
6035 \end_layout
6036
6037 \end_inset
6038
6039
6040 \end_layout
6041
6042 \begin_layout Standard
6043 Do not use:
6044 \end_layout
6045
6046 \begin_layout Standard
6047 \begin_inset listings
6048 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6049 inline false
6050 status open
6051
6052 \begin_layout Plain Layout
6053
6054 int a, b; // not used in LyX
6055 \end_layout
6056
6057 \end_inset
6058
6059
6060 \end_layout
6061
6062 \begin_layout Standard
6063 This is especially important when initialization is done at the same time:
6064 \end_layout
6065
6066 \begin_layout Standard
6067 Use:
6068 \end_layout
6069
6070 \begin_layout Standard
6071 \begin_inset listings
6072 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6073 inline false
6074 status open
6075
6076 \begin_layout Plain Layout
6077
6078 string a = "Lars";
6079 \end_layout
6080
6081 \begin_layout Plain Layout
6082
6083 string b = "Gullik";
6084 \end_layout
6085
6086 \end_inset
6087
6088
6089 \end_layout
6090
6091 \begin_layout Standard
6092 Do not use:
6093 \end_layout
6094
6095 \begin_layout Standard
6096 \begin_inset listings
6097 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6098 inline false
6099 status open
6100
6101 \begin_layout Plain Layout
6102
6103 string a = "Lars", b = "Gullik"; // not used in LyX
6104 \end_layout
6105
6106 \end_inset
6107
6108
6109 \end_layout
6110
6111 \begin_layout Standard
6112 [Note that
6113 \begin_inset Flex Code
6114 status collapsed
6115
6116 \begin_layout Plain Layout
6117 string a = "Lars"
6118 \end_layout
6119
6120 \end_inset
6121
6122  is formally calling a copy constructor on a temporary constructed from
6123  a string literal and therefore has the potential of being more expensive
6124  then direct construction by
6125 \begin_inset Flex Code
6126 status collapsed
6127
6128 \begin_layout Plain Layout
6129 string a("Lars")
6130 \end_layout
6131
6132 \end_inset
6133
6134 .
6135  However the compiler is allowed to elide the copy (even if it had side
6136  effects), and modern compilers typically do so.
6137  Given these equal costs, \SpecialChar LyX
6138  code favours the '=' idiom as it is in line with
6139  the traditional C-style initialization,
6140 \emph on
6141 and
6142 \emph default
6143  cannot be mistaken as function declaration,
6144 \emph on
6145 and
6146 \emph default
6147  reduces the level of nested parentheses in more initializations.]
6148 \end_layout
6149
6150 \end_deeper
6151 \begin_layout Itemize
6152 Pointers and references:
6153 \begin_inset Separator latexpar
6154 \end_inset
6155
6156
6157 \end_layout
6158
6159 \begin_deeper
6160 \begin_layout Standard
6161 Use:
6162 \end_layout
6163
6164 \begin_layout Standard
6165 \begin_inset listings
6166 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6167 inline false
6168 status open
6169
6170 \begin_layout Plain Layout
6171
6172 char * p = "flop";
6173 \end_layout
6174
6175 \begin_layout Plain Layout
6176
6177 char & c = *p;
6178 \end_layout
6179
6180 \end_inset
6181
6182
6183 \end_layout
6184
6185 \begin_layout Standard
6186 Do not use:
6187 \end_layout
6188
6189 \begin_layout Standard
6190 \begin_inset listings
6191 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6192 inline false
6193 status open
6194
6195 \begin_layout Plain Layout
6196
6197 char *p = "flop"; // not used in LyX
6198 \end_layout
6199
6200 \begin_layout Plain Layout
6201
6202 char &c = *p; // not used in LyX
6203 \end_layout
6204
6205 \end_inset
6206
6207
6208 \end_layout
6209
6210 \begin_layout Standard
6211 Some time ago we had a huge discussion on this subject and after convincing
6212  argumentation from Asger this is what we decided.
6213  Also note that we will have:
6214 \end_layout
6215
6216 \begin_layout Standard
6217 \begin_inset listings
6218 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6219 inline false
6220 status open
6221
6222 \begin_layout Plain Layout
6223
6224 char const * p;
6225 \end_layout
6226
6227 \end_inset
6228
6229
6230 \end_layout
6231
6232 \begin_layout Standard
6233 and not
6234 \end_layout
6235
6236 \begin_layout Standard
6237 \begin_inset listings
6238 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6239 inline false
6240 status open
6241
6242 \begin_layout Plain Layout
6243
6244 const char * p; // not used in LyX
6245 \end_layout
6246
6247 \end_inset
6248
6249
6250 \end_layout
6251
6252 \end_deeper
6253 \begin_layout Itemize
6254 Operator names and parentheses
6255 \begin_inset Separator latexpar
6256 \end_inset
6257
6258
6259 \end_layout
6260
6261 \begin_deeper
6262 \begin_layout Standard
6263 \begin_inset listings
6264 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6265 inline false
6266 status open
6267
6268 \begin_layout Plain Layout
6269
6270 operator==(type)
6271 \end_layout
6272
6273 \end_inset
6274
6275
6276 \end_layout
6277
6278 \begin_layout Standard
6279 and not
6280 \end_layout
6281
6282 \begin_layout Standard
6283 \begin_inset listings
6284 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6285 inline false
6286 status open
6287
6288 \begin_layout Plain Layout
6289
6290 operator == (type) // not used in LyX
6291 \end_layout
6292
6293 \end_inset
6294
6295
6296 \end_layout
6297
6298 \begin_layout Standard
6299 The == is part of the function name, separating it makes the declaration
6300  look like an expression.
6301 \end_layout
6302
6303 \end_deeper
6304 \begin_layout Itemize
6305 Function names and parentheses
6306 \begin_inset Separator latexpar
6307 \end_inset
6308
6309
6310 \end_layout
6311
6312 \begin_deeper
6313 \begin_layout Standard
6314 \begin_inset listings
6315 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6316 inline false
6317 status open
6318
6319 \begin_layout Plain Layout
6320
6321 void mangle()
6322 \end_layout
6323
6324 \end_inset
6325
6326
6327 \end_layout
6328
6329 \begin_layout Standard
6330 and not
6331 \end_layout
6332
6333 \begin_layout Standard
6334 \begin_inset listings
6335 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6336 inline false
6337 status open
6338
6339 \begin_layout Plain Layout
6340
6341 void mangle () // not used in LyX
6342 \end_layout
6343
6344 \end_inset
6345
6346
6347 \end_layout
6348
6349 \end_deeper
6350 \begin_layout Itemize
6351 Enumerators
6352 \begin_inset Separator latexpar
6353 \end_inset
6354
6355
6356 \end_layout
6357
6358 \begin_deeper
6359 \begin_layout Standard
6360 \begin_inset listings
6361 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6362 inline false
6363 status open
6364
6365 \begin_layout Plain Layout
6366
6367 enum Foo {
6368 \end_layout
6369
6370 \begin_layout Plain Layout
6371
6372         FOO_ONE = 1,
6373 \end_layout
6374
6375 \begin_layout Plain Layout
6376
6377         FOO_TWO = 2,
6378 \end_layout
6379
6380 \begin_layout Plain Layout
6381
6382         FOO_THREE = 3
6383 \end_layout
6384
6385 \begin_layout Plain Layout
6386
6387 };
6388 \end_layout
6389
6390 \end_inset
6391
6392
6393 \end_layout
6394
6395 \begin_layout Standard
6396 and not
6397 \end_layout
6398
6399 \begin_layout Standard
6400 \begin_inset listings
6401 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6402 inline false
6403 status open
6404
6405 \begin_layout Plain Layout
6406
6407 enum { one = 1, two = 2, three 3 }; // not used in LyX
6408 \end_layout
6409
6410 \end_inset
6411
6412
6413 \end_layout
6414
6415 \begin_layout Standard
6416 and not
6417 \end_layout
6418
6419 \begin_layout Standard
6420 \begin_inset listings
6421 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6422 inline false
6423 status open
6424
6425 \begin_layout Plain Layout
6426
6427 enum {
6428 \end_layout
6429
6430 \begin_layout Plain Layout
6431
6432 One = 1,
6433 \end_layout
6434
6435 \begin_layout Plain Layout
6436
6437 Two = 2,
6438 \end_layout
6439
6440 \begin_layout Plain Layout
6441
6442 Three = 3
6443 \end_layout
6444
6445 \begin_layout Plain Layout
6446
6447 };
6448 \end_layout
6449
6450 \end_inset
6451
6452
6453 \end_layout
6454
6455 \end_deeper
6456 \begin_layout Itemize
6457 Null pointers
6458 \begin_inset Separator latexpar
6459 \end_inset
6460
6461
6462 \end_layout
6463
6464 \begin_deeper
6465 \begin_layout Standard
6466 Use nullptr (C++11):
6467 \end_layout
6468
6469 \begin_layout Standard
6470 \begin_inset listings
6471 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6472 inline false
6473 status open
6474
6475 \begin_layout Plain Layout
6476
6477 void * p = nullptr;
6478 \end_layout
6479
6480 \end_inset
6481
6482
6483 \end_layout
6484
6485 \begin_layout Standard
6486 and not
6487 \end_layout
6488
6489 \begin_layout Standard
6490 \begin_inset listings
6491 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6492 inline false
6493 status open
6494
6495 \begin_layout Plain Layout
6496
6497 void * p = NULL; // not used in LyX
6498 \end_layout
6499
6500 \end_inset
6501
6502
6503 \end_layout
6504
6505 \begin_layout Standard
6506 and not
6507 \end_layout
6508
6509 \begin_layout Standard
6510 \begin_inset listings
6511 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6512 inline false
6513 status open
6514
6515 \begin_layout Plain Layout
6516
6517 void * p = '
6518 \backslash
6519 0'; // not used in LyX
6520 \end_layout
6521
6522 \end_inset
6523
6524
6525 \end_layout
6526
6527 \begin_layout Standard
6528 and not
6529 \end_layout
6530
6531 \begin_layout Standard
6532 \begin_inset listings
6533 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6534 inline false
6535 status open
6536
6537 \begin_layout Plain Layout
6538
6539 void * p = 42 - 7 * 6; // not used in LyX
6540 \end_layout
6541
6542 \end_inset
6543
6544
6545 \end_layout
6546
6547 \begin_layout Standard
6548 Note: As an exception, imported third party code as well as code interfacing
6549  the
6550 \begin_inset Quotes eld
6551 \end_inset
6552
6553 native
6554 \begin_inset Quotes erd
6555 \end_inset
6556
6557  APIs (
6558 \begin_inset Flex Code
6559 status collapsed
6560
6561 \begin_layout Plain Layout
6562 src/support/os_*
6563 \end_layout
6564
6565 \end_inset
6566
6567 ) can use NULL.
6568 \end_layout
6569
6570 \end_deeper
6571 \begin_layout Itemize
6572 Naming rules for classes
6573 \begin_inset Separator latexpar
6574 \end_inset
6575
6576
6577 \end_layout
6578
6579 \begin_deeper
6580 \begin_layout Itemize
6581 Use descriptive but simple and short names.
6582  Do not abbreviate.
6583 \end_layout
6584
6585 \begin_layout Itemize
6586 Class names are usually capitalized, and function names lowercased.
6587 \end_layout
6588
6589 \begin_layout Itemize
6590 Enums are named like Classes, values are usually in lower-case.
6591 \end_layout
6592
6593 \begin_layout Itemize
6594 Public API functions are camel-case (
6595 \begin_inset Flex Code
6596 status collapsed
6597
6598 \begin_layout Plain Layout
6599 void setAFlagToAValue(bool)
6600 \end_layout
6601
6602 \end_inset
6603
6604 ).
6605 \end_layout
6606
6607 \begin_layout Itemize
6608 Member variables are underscored (
6609 \begin_inset Flex Code
6610 status collapsed
6611
6612 \begin_layout Plain Layout
6613 enable_this_feature_flag_
6614 \end_layout
6615
6616 \end_inset
6617
6618 ) with a final
6619 \begin_inset Quotes eld
6620 \end_inset
6621
6622 _
6623 \begin_inset Quotes erd
6624 \end_inset
6625
6626 .
6627 \end_layout
6628
6629 \begin_layout Itemize
6630 Private/protected functions are also camel-case.
6631 \end_layout
6632
6633 \begin_layout Itemize
6634 New types are capitalized, so this goes for typedefs, classes, structs and
6635  enums.
6636 \end_layout
6637
6638 \end_deeper
6639 \begin_layout Itemize
6640 Formatting
6641 \begin_inset Separator latexpar
6642 \end_inset
6643
6644
6645 \end_layout
6646
6647 \begin_deeper
6648 \begin_layout Itemize
6649 Adapt the formatting of your code to the one used in the other parts of
6650  \SpecialChar LyX
6651 .
6652  In case there is different formatting for the same construct, use the one
6653  used more often.
6654 \end_layout
6655
6656 \end_deeper
6657 \begin_layout Itemize
6658 Use existing structures
6659 \begin_inset Separator latexpar
6660 \end_inset
6661
6662
6663 \end_layout
6664
6665 \begin_deeper
6666 \begin_layout Itemize
6667 \begin_inset CommandInset label
6668 LatexCommand label
6669 name "Use-string-wherever"
6670
6671 \end_inset
6672
6673 Use
6674 \begin_inset Flex Code
6675 status collapsed
6676
6677 \begin_layout Plain Layout
6678 string
6679 \end_layout
6680
6681 \end_inset
6682
6683  wherever possible.
6684  Unicode strings should prefer using
6685 \begin_inset Flex Code
6686 status collapsed
6687
6688 \begin_layout Plain Layout
6689 docstring
6690 \end_layout
6691
6692 \end_inset
6693
6694  instead of UTF-8 encoded
6695 \begin_inset Flex Code
6696 status collapsed
6697
6698 \begin_layout Plain Layout
6699 std::string
6700 \end_layout
6701
6702 \end_inset
6703
6704 .
6705 \end_layout
6706
6707 \begin_layout Itemize
6708 Check out the filename and path tools in
6709 \begin_inset Flex Code
6710 status collapsed
6711
6712 \begin_layout Plain Layout
6713 filetools.h
6714 \end_layout
6715
6716 \end_inset
6717
6718
6719 \end_layout
6720
6721 \begin_layout Itemize
6722 Check out the string tools in
6723 \begin_inset Flex Code
6724 status collapsed
6725
6726 \begin_layout Plain Layout
6727 lstring.h
6728 \end_layout
6729
6730 \end_inset
6731
6732 .
6733 \end_layout
6734
6735 \begin_layout Itemize
6736 Use the \SpecialChar LyX
6737 Err class to report errors and messages using the lyxerr instantiation.
6738  [add description of other existing structures]
6739 \end_layout
6740
6741 \end_deeper
6742 \begin_layout Itemize
6743 Declarations
6744 \begin_inset Separator latexpar
6745 \end_inset
6746
6747
6748 \end_layout
6749
6750 \begin_deeper
6751 \begin_layout Itemize
6752 Use this order for the access sections of your class: public, protected,
6753  private.
6754  The public section is interesting for every user of the class.
6755  The private section is only of interest for the implementors of the class
6756  (you).
6757  [Obviously not true since this is for developers, and we do not want one
6758  developer only to be able to read and understand the implementation of
6759  class internals.
6760  Lgb]
6761 \end_layout
6762
6763 \begin_layout Itemize
6764 Avoid declaring global objects in the declaration file of the class.
6765  If the same variable is used for all objects, use a static member.
6766 \end_layout
6767
6768 \begin_layout Itemize
6769 Avoid global or static variables.
6770 \end_layout
6771
6772 \end_deeper
6773 \begin_layout Itemize
6774 File headers
6775 \begin_inset Separator latexpar
6776 \end_inset
6777
6778
6779 \end_layout
6780
6781 \begin_deeper
6782 \begin_layout Standard
6783 If you create a new file, the top of the file should look something like
6784  this :
6785 \end_layout
6786
6787 \begin_layout Standard
6788 \begin_inset listings
6789 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6790 inline false
6791 status open
6792
6793 \begin_layout Plain Layout
6794
6795 /**
6796 \end_layout
6797
6798 \begin_layout Plain Layout
6799
6800 *
6801 \backslash
6802 file NewFile.cpp
6803 \end_layout
6804
6805 \begin_layout Plain Layout
6806
6807 * This file is part of LyX, the document processor.
6808 \end_layout
6809
6810 \begin_layout Plain Layout
6811
6812 * Licence details can be found in the file COPYING.
6813 \end_layout
6814
6815 \begin_layout Plain Layout
6816
6817 *
6818 \end_layout
6819
6820 \begin_layout Plain Layout
6821
6822 *
6823 \backslash
6824 author Kaiser Sose
6825 \end_layout
6826
6827 \begin_layout Plain Layout
6828
6829 *
6830 \end_layout
6831
6832 \begin_layout Plain Layout
6833
6834 * Full author contact details are available
6835 \end_layout
6836
6837 \begin_layout Plain Layout
6838
6839 * in file CREDITS.
6840 \end_layout
6841
6842 \begin_layout Plain Layout
6843
6844 */
6845 \end_layout
6846
6847 \end_inset
6848
6849
6850 \end_layout
6851
6852 \end_deeper
6853 \begin_layout Itemize
6854 Documentation
6855 \begin_inset Separator latexpar
6856 \end_inset
6857
6858
6859 \end_layout
6860
6861 \begin_deeper
6862 \begin_layout Itemize
6863 The documentation is generated from the header files.
6864 \end_layout
6865
6866 \begin_layout Itemize
6867 You document for the other developers, not for yourself.
6868 \end_layout
6869
6870 \begin_layout Itemize
6871 You should document what the function does, not the implementation.
6872 \begin_inset Separator latexpar
6873 \end_inset
6874
6875
6876 \end_layout
6877
6878 \begin_deeper
6879 \begin_layout Itemize
6880 in the .cpp files you document the implementation.
6881 \end_layout
6882
6883 \end_deeper
6884 \begin_layout Itemize
6885 Single line description (
6886 \begin_inset Flex Code
6887 status collapsed
6888
6889 \begin_layout Plain Layout
6890 ///
6891 \end_layout
6892
6893 \end_inset
6894
6895 ), multiple lines description (
6896 \begin_inset Flex Code
6897 status collapsed
6898
6899 \begin_layout Plain Layout
6900 /** ...
6901  */
6902 \end_layout
6903
6904 \end_inset
6905
6906 ), see the doxygen webpage referenced above.
6907 \end_layout
6908
6909 \end_deeper
6910 \begin_layout Section
6911 Naming rules for \SpecialChar LyX
6912  User Functions (LFUNs)
6913 \end_layout
6914
6915 \begin_layout Standard
6916 Here is the set of rules to apply when a new command name is introduced:
6917 \end_layout
6918
6919 \begin_layout Enumerate
6920 Use the object.event order.
6921  That is, use `word-forward' instead of `forward-word'.
6922 \end_layout
6923
6924 \begin_layout Enumerate
6925 Don't introduce an alias for an already named object.
6926  Same for events.
6927 \end_layout
6928
6929 \begin_layout Enumerate
6930 Forward movement or focus is called `forward' (not `right').
6931 \end_layout
6932
6933 \begin_layout Enumerate
6934 Backward movement or focus is called `backward' (not `left').
6935 \end_layout
6936
6937 \begin_layout Enumerate
6938 Upward movement of focus is called `up'.
6939 \end_layout
6940
6941 \begin_layout Enumerate
6942 Downward movement is called `down'.
6943 \end_layout
6944
6945 \begin_layout Enumerate
6946 The begin of an object is called `begin' (not `start').
6947 \end_layout
6948
6949 \begin_layout Enumerate
6950 The end of an object is called `end'.
6951 \end_layout
6952
6953 \begin_layout Section
6954 How to create class interfaces
6955 \end_layout
6956
6957 \begin_layout Standard
6958 (a.k.a How Non-Member Functions Improve Encapsulation)
6959 \end_layout
6960
6961 \begin_layout Standard
6962 I recently read an article by Scott Meyers, where he makes a strong case
6963  on how non-member functions makes classes more encapsulated, not less.
6964  Just skipping to the core of this provides us with the following algorithm
6965  for deciding what kind of function to add to a class interface:
6966 \end_layout
6967
6968 \begin_layout Itemize
6969 We need to add a function f to the class C's API.
6970 \begin_inset Separator latexpar
6971 \end_inset
6972
6973
6974 \end_layout
6975
6976 \begin_deeper
6977 \begin_layout Standard
6978 \begin_inset listings
6979 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6980 inline false
6981 status open
6982
6983 \begin_layout Plain Layout
6984
6985 if (f needs to be virtual)
6986 \end_layout
6987
6988 \begin_layout Plain Layout
6989
6990         make f a member function of C;
6991 \end_layout
6992
6993 \begin_layout Plain Layout
6994
6995 else if (f is operator>> or operator<<) {
6996 \end_layout
6997
6998 \begin_layout Plain Layout
6999
7000         make f a non-member function;
7001 \end_layout
7002
7003 \begin_layout Plain Layout
7004
7005         if (f needs access to non-public members of C)
7006 \end_layout
7007
7008 \begin_layout Plain Layout
7009
7010                 make f a friend of C;
7011 \end_layout
7012
7013 \begin_layout Plain Layout
7014
7015 } else if (f needs type conversions on its left-most argument) {
7016 \end_layout
7017
7018 \begin_layout Plain Layout
7019
7020         make f a non-member function;
7021 \end_layout
7022
7023 \begin_layout Plain Layout
7024
7025         if (f needs access to non-public members of C)
7026 \end_layout
7027
7028 \begin_layout Plain Layout
7029
7030                 make f a friend of C;
7031 \end_layout
7032
7033 \begin_layout Plain Layout
7034
7035 } else if (f can be implemented via C's public interface)
7036 \end_layout
7037
7038 \begin_layout Plain Layout
7039
7040         make f a non-member function;
7041 \end_layout
7042
7043 \begin_layout Plain Layout
7044
7045 else
7046 \end_layout
7047
7048 \begin_layout Plain Layout
7049
7050         make f a member function of C;
7051 \end_layout
7052
7053 \end_inset
7054
7055
7056 \end_layout
7057
7058 \end_deeper
7059 \begin_layout Chapter
7060 Coding recommendations
7061 \end_layout
7062
7063 \begin_layout Standard
7064 These are some rules for effective C++ programming.
7065  These are taken from Scott Meyers
7066 \begin_inset CommandInset citation
7067 LatexCommand cite
7068 key "journal"
7069 literal "true"
7070
7071 \end_inset
7072
7073 , and are presented in their short form.
7074  These are not all the rules Meyers presents, only the most important of
7075  them.
7076  \SpecialChar LyX
7077  does not yet follow these rules, but they should be the goal.
7078 \end_layout
7079
7080 \begin_layout Itemize
7081 use
7082 \family typewriter
7083 const
7084 \family default
7085  and
7086 \family typewriter
7087 inline
7088 \family default
7089  instead of
7090 \family typewriter
7091 #define
7092 \end_layout
7093
7094 \begin_layout Itemize
7095 use the same form in corresponding calls to new and delete, i.e.
7096  write
7097 \begin_inset Flex Code
7098 status collapsed
7099
7100 \begin_layout Plain Layout
7101 delete[] obj;
7102 \end_layout
7103
7104 \end_inset
7105
7106  if
7107 \begin_inset Flex Code
7108 status collapsed
7109
7110 \begin_layout Plain Layout
7111 new obj[n];
7112 \end_layout
7113
7114 \end_inset
7115
7116  was used to create the object and write
7117 \begin_inset Flex Code
7118 status collapsed
7119
7120 \begin_layout Plain Layout
7121 delete obj;
7122 \end_layout
7123
7124 \end_inset
7125
7126  if you wrote
7127 \begin_inset Flex Code
7128 status collapsed
7129
7130 \begin_layout Plain Layout
7131 new obj;
7132 \end_layout
7133
7134 \end_inset
7135
7136  Notice strings should be
7137 \begin_inset Flex Code
7138 status collapsed
7139
7140 \begin_layout Plain Layout
7141 std::string
7142 \end_layout
7143
7144 \end_inset
7145
7146 's instead of
7147 \begin_inset Flex Code
7148 status collapsed
7149
7150 \begin_layout Plain Layout
7151 char *
7152 \end_layout
7153
7154 \end_inset
7155
7156 's.
7157  (this contradicts to
7158 \begin_inset CommandInset ref
7159 LatexCommand ref
7160 reference "Use-string-wherever"
7161
7162 \end_inset
7163
7164  )
7165 \end_layout
7166
7167 \begin_layout Itemize
7168 define a default constructor, copy constructor and an assignment operator
7169  for all classes with dynamically allocated memory that are not made noncopyable
7170 \end_layout
7171
7172 \begin_layout Itemize
7173 do not define default constructor, copy constructor and an assignment operator
7174  if the compiler generated one would do the same
7175 \end_layout
7176
7177 \begin_layout Itemize
7178 make destructors virtual in base classes and only there
7179 \end_layout
7180
7181 \begin_layout Itemize
7182 assign to all data members in operator=()
7183 \end_layout
7184
7185 \begin_layout Itemize
7186 strive for class interfaces that are complete and minimal
7187 \end_layout
7188
7189 \begin_layout Itemize
7190 differentiate among member functions, global functions and friend functions
7191 \end_layout
7192
7193 \begin_layout Itemize
7194 avoid data members in the public interface
7195 \end_layout
7196
7197 \begin_layout Itemize
7198 use const whenever possible
7199 \end_layout
7200
7201 \begin_layout Itemize
7202 pass and return objects by reference instead of by value
7203 \end_layout
7204
7205 \begin_layout Itemize
7206 choose carefully between function overloading and parameter defaulting
7207 \end_layout
7208
7209 \begin_layout Itemize
7210 never return a reference to a local object or a dereferenced pointer initialized
7211  by new within the function
7212 \end_layout
7213
7214 \begin_layout Itemize
7215 use enums for integral constants
7216 \end_layout
7217
7218 \begin_layout Itemize
7219 minimize compilation dependencies between files
7220 \end_layout
7221
7222 \begin_layout Itemize
7223 pay attention to compiler warnings
7224 \end_layout
7225
7226 \begin_layout Itemize
7227 differentiate between inheritance of interface and inheritance of implementation
7228 \end_layout
7229
7230 \begin_layout Itemize
7231 differentiate between inheritance and templates
7232 \end_layout
7233
7234 \begin_layout Itemize
7235 ensure that global objects are initialized before they are used
7236 \end_layout
7237
7238 \begin_layout Itemize
7239 avoid conditions to
7240 \begin_inset Flex Code
7241 status collapsed
7242
7243 \begin_layout Plain Layout
7244 if
7245 \end_layout
7246
7247 \end_inset
7248
7249  and
7250 \begin_inset Flex Code
7251 status collapsed
7252
7253 \begin_layout Plain Layout
7254 while
7255 \end_layout
7256
7257 \end_inset
7258
7259  that span more than a line
7260 \end_layout
7261
7262 \begin_layout Chapter
7263 \start_of_appendix
7264 Notes
7265 \end_layout
7266
7267 \begin_layout Itemize
7268 And one of mine: (Lgb)
7269 \begin_inset Separator latexpar
7270 \end_inset
7271
7272
7273 \end_layout
7274
7275 \begin_deeper
7276 \begin_layout Itemize
7277 when switching on enums, refrain from using "default:" if possible
7278 \end_layout
7279
7280 \end_deeper
7281 \begin_layout Itemize
7282 And one of mine: (Andre')
7283 \begin_inset Separator latexpar
7284 \end_inset
7285
7286
7287 \end_layout
7288
7289 \begin_deeper
7290 \begin_layout Itemize
7291 try to implement your class in a way that the automatically generated copy
7292  constructor and copy assignment work out-of-the box
7293 \end_layout
7294
7295 \begin_layout Itemize
7296 I don't have problems with using boost in the implementation _if and only
7297  if_ it provides actual benefits over less intrusive alternatives.
7298  I do have a problem with needlessly sprinkling 'boost::' over interfaces,
7299  especially if it does not add any value.
7300 \begin_inset Separator latexpar
7301 \end_inset
7302
7303
7304 \end_layout
7305
7306 \begin_deeper
7307 \begin_layout Standard
7308 Given that there seems to be an unconditional "typedef unsigned int quint32;"
7309  in qglobal.h I don't think there's any platform supported by current \SpecialChar LyX
7310  that
7311  could not use 'unsigned int' (and an static assert in some implementation
7312  file for the unlikely case some ILP64 zombie raises its ugly head again.
7313  And if that happens, using <cstdint> would still be a better choice...)
7314 \end_layout
7315
7316 \begin_layout Standard
7317 The idea is to create something that's not compilable as soon as the condition
7318  is violated.
7319  There are lots of possibilities to achieve this, some examples follow:
7320 \end_layout
7321
7322 \begin_layout Standard
7323 In C++11 there's a "built-in":
7324 \end_layout
7325
7326 \begin_layout Standard
7327 \begin_inset listings
7328 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7329 inline false
7330 status open
7331
7332 \begin_layout Plain Layout
7333
7334 static_assert(sizeof(int) == 4, "Funny platform")
7335 \end_layout
7336
7337 \end_inset
7338
7339
7340 \end_layout
7341
7342 \begin_layout Standard
7343 until then on namespace scope:
7344 \end_layout
7345
7346 \begin_layout Standard
7347 \begin_inset listings
7348 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7349 inline false
7350 status open
7351
7352 \begin_layout Plain Layout
7353
7354 #include <boost/static_assert.hpp>
7355 \end_layout
7356
7357 \begin_layout Plain Layout
7358
7359 BOOST_STATIC_ASSERT(sizeof(int) == 4)
7360 \end_layout
7361
7362 \end_inset
7363
7364
7365 \end_layout
7366
7367 \begin_layout Standard
7368 or without boost:
7369 \end_layout
7370
7371 \begin_layout Standard
7372 \begin_inset listings
7373 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7374 inline false
7375 status open
7376
7377 \begin_layout Plain Layout
7378
7379 template<bool Condition>
7380 \end_layout
7381
7382 \begin_layout Plain Layout
7383
7384 struct static_assert_helper;
7385 \end_layout
7386
7387 \begin_layout Plain Layout
7388
7389 template <>
7390 \end_layout
7391
7392 \begin_layout Plain Layout
7393
7394 struct static_assert_helper<true> {};
7395 \end_layout
7396
7397 \begin_layout Plain Layout
7398
7399 enum {
7400 \end_layout
7401
7402 \begin_layout Plain Layout
7403
7404         dummy = sizeof(static_assert_helper<sizeof(int) == 4>)
7405 \end_layout
7406
7407 \begin_layout Plain Layout
7408
7409 };
7410 \end_layout
7411
7412 \end_inset
7413
7414
7415 \end_layout
7416
7417 \begin_layout Standard
7418 or somewhat brutish without templates, in any function:
7419 \end_layout
7420
7421 \begin_layout Standard
7422 \begin_inset listings
7423 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7424 inline false
7425 status open
7426
7427 \begin_layout Plain Layout
7428
7429 const int d = sizeof(int) - 4;
7430 \end_layout
7431
7432 \begin_layout Plain Layout
7433
7434 switch (0) {
7435 \end_layout
7436
7437 \begin_layout Plain Layout
7438
7439 case 0:
7440 \end_layout
7441
7442 \begin_layout Plain Layout
7443
7444 case !(d*d):
7445 \end_layout
7446
7447 \begin_layout Plain Layout
7448
7449         break;
7450 \end_layout
7451
7452 \begin_layout Plain Layout
7453
7454 }
7455 \end_layout
7456
7457 \end_inset
7458
7459
7460 \end_layout
7461
7462 \begin_layout Standard
7463 Any of them in a .cpp file will break compilation as soon as
7464 \begin_inset Flex Code
7465 status collapsed
7466
7467 \begin_layout Plain Layout
7468 sizeof(int)
7469 \end_layout
7470
7471 \end_inset
7472
7473  is not equal 4.
7474  Personally I prefer something like the third version (or the first, if
7475  using C++11 is allowed).
7476 \end_layout
7477
7478 \end_deeper
7479 \end_deeper
7480 \begin_layout Itemize
7481 And one of mine: (vfr)
7482 \begin_inset Separator latexpar
7483 \end_inset
7484
7485
7486 \end_layout
7487
7488 \begin_deeper
7489 \begin_layout Itemize
7490 On dynamics_casts
7491 \begin_inset Flex URL
7492 status open
7493
7494 \begin_layout Plain Layout
7495
7496 http://www.lyx.org/trac/changeset/35855
7497 \end_layout
7498
7499 \end_inset
7500
7501 :
7502 \begin_inset Separator latexpar
7503 \end_inset
7504
7505
7506 \end_layout
7507
7508 \begin_deeper
7509 \begin_layout Standard
7510 A dynamic_cast is necessary when:
7511 \end_layout
7512
7513 \begin_layout Itemize
7514 the object to be casted is from an external library because we can't add
7515  Qxxx::asXxxx() to Qt e.g.:
7516 \begin_inset Separator latexpar
7517 \end_inset
7518
7519
7520 \end_layout
7521
7522 \begin_deeper
7523 \begin_layout Itemize
7524 QAbstractListModel to GuiIdListModel,
7525 \end_layout
7526
7527 \begin_layout Itemize
7528 QValidator to PathValidator,
7529 \end_layout
7530
7531 \begin_layout Itemize
7532 QWidget to TabWorkArea,
7533 \end_layout
7534
7535 \begin_layout Itemize
7536 QWidget to GuiWorkArea;
7537 \end_layout
7538
7539 \end_deeper
7540 \begin_layout Itemize
7541 the object is to be casted from an interface to the implementing class,
7542  because the Interface does not know by whom it is implemented:
7543 \begin_inset Separator latexpar
7544 \end_inset
7545
7546
7547 \end_layout
7548
7549 \begin_deeper
7550 \begin_layout Itemize
7551 ProgressInterface to GuiProgress,
7552 \end_layout
7553
7554 \begin_layout Itemize
7555 Application to GuiApplication.
7556 \end_layout
7557
7558 \end_deeper
7559 \begin_layout Standard
7560 A dynamic_cast can be replaced by:
7561 \end_layout
7562
7563 \begin_layout Itemize
7564 already existing as***Inset() functions, e.g.:
7565 \begin_inset Separator latexpar
7566 \end_inset
7567
7568
7569 \end_layout
7570
7571 \begin_deeper
7572 \begin_layout Itemize
7573 asHullInset(),
7574 \end_layout
7575
7576 \begin_layout Itemize
7577 asInsetMath()->asMacro(),
7578 \end_layout
7579
7580 \begin_layout Itemize
7581 asInsetText();
7582 \end_layout
7583
7584 \end_deeper
7585 \begin_layout Itemize
7586 A static_cast when we are sure this can't go wrong, e.g.:
7587 \begin_inset Separator latexpar
7588 \end_inset
7589
7590
7591 \end_layout
7592
7593 \begin_deeper
7594 \begin_layout Itemize
7595 we are sure that CellData::inset->clone() is an InsetTableCell,
7596 \end_layout
7597
7598 \begin_layout Itemize
7599 in cases where we explicitly check it->lyxCode().
7600 \end_layout
7601
7602 \end_deeper
7603 \end_deeper
7604 \end_deeper
7605 \begin_layout Bibliography
7606 \begin_inset CommandInset bibitem
7607 LatexCommand bibitem
7608 key "meyers"
7609 literal "true"
7610
7611 \end_inset
7612
7613 Meyers, Scott.
7614  Effective C++: 50 Specific Ways to Improve Your Programs and Design.
7615  Addison-Wesley, 1992.
7616 \end_layout
7617
7618 \begin_layout Bibliography
7619 \begin_inset CommandInset bibitem
7620 LatexCommand bibitem
7621 key "sutter"
7622 literal "true"
7623
7624 \end_inset
7625
7626 Sutter, Herb.
7627  Exceptional C++: 47 engineering puzzles, programming problems, and solutions.
7628  ISBN 0-201-61562-2.
7629 \end_layout
7630
7631 \begin_layout Bibliography
7632 \begin_inset CommandInset bibitem
7633 LatexCommand bibitem
7634 key "journal"
7635 literal "true"
7636
7637 \end_inset
7638
7639 Meyers, Scott.
7640  C/C++ User's Journal (Vol.18, No.2).
7641 \end_layout
7642
7643 \end_body
7644 \end_document