lib/doc/Development.lyx

   1 #LyX 2.4 created this file. For more info see https://www.lyx.org/
   2 \lyxformat 599
   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 Adapt the code to the structures already existing in \SpecialChar LyX
5367 , or in the case that
5368  you have better ideas, discuss them on the developer's list before writing
5369  the code.
5370 \end_layout
5371
5372 \begin_layout Itemize
5373 Take advantage of the C++ standard library.
5374  Especially don't use custom containers when a standard container is usable;
5375  learn to use the algorithms and functors in the standard library.
5376 \end_layout
5377
5378 \begin_layout Itemize
5379 Be aware of exceptions and write exception safe code.
5380  See sec.
5381 \begin_inset space ~
5382 \end_inset
5383
5384
5385 \begin_inset CommandInset ref
5386 LatexCommand ref
5387 reference "sec:Exceptions"
5388 plural "false"
5389 caps "false"
5390 noprefix "false"
5391
5392 \end_inset
5393
5394 .
5395 \end_layout
5396
5397 \begin_layout Itemize
5398 Document all variables, methods, functions, classes etc.
5399  We are using the source documentation program doxygen, a program that handles
5400  javadoc syntax, to document sources.
5401  You can download doxygen from:
5402 \begin_inset Flex URL
5403 status open
5404
5405 \begin_layout Plain Layout
5406
5407 http://www.stack.nl/~dimitri/doxygen/
5408 \end_layout
5409
5410 \end_inset
5411
5412
5413 \end_layout
5414
5415 \begin_layout Itemize
5416 We have certain code constructs that we try to follow.
5417  See sec.
5418 \begin_inset space ~
5419 \end_inset
5420
5421
5422 \begin_inset CommandInset ref
5423 LatexCommand ref
5424 reference "sec:Code-constructs"
5425 plural "false"
5426 caps "false"
5427 noprefix "false"
5428
5429 \end_inset
5430
5431 .
5432 \end_layout
5433
5434 \begin_layout Section
5435 Submitting code
5436 \end_layout
5437
5438 \begin_layout Standard
5439 It is implicitly understood that all patches contributed to The \SpecialChar LyX
5440  Project
5441  is under the Gnu General Public License, version 2 or later.
5442  If you have a problem with that, don't contribute code.
5443  Also please don't just pop up out of the blue with a huge patch (or small)
5444  that changes something substantial in \SpecialChar LyX
5445 .
5446  Always discuss your ideas with the developers on the developer's mailing
5447  list.
5448  When you create the patch, please use
5449 \begin_inset Quotes eld
5450 \end_inset
5451
5452
5453 \family typewriter
5454 diff -up
5455 \family default
5456
5457 \begin_inset Quotes erd
5458 \end_inset
5459
5460  since we find that a lot easier to read than the other diff formats.
5461  Also please do not send patches that implements or fixes several different
5462  things; several patches is a much better option.
5463  We also require you to provide a commit message entry with every patch,
5464  this describes in detail what the patch is doing.
5465
5466 \end_layout
5467
5468 \begin_layout Section
5469 Code constructs
5470 \begin_inset CommandInset label
5471 LatexCommand label
5472 name "sec:Code-constructs"
5473
5474 \end_inset
5475
5476
5477 \end_layout
5478
5479 \begin_layout Standard
5480 We have several guidelines on code constructs, some of these exist to make
5481  the code faster, others to make the code clearer.
5482  Yet others exist to allow us to take advantage of the strong type checking
5483  in C++.
5484 \end_layout
5485
5486 \begin_layout Itemize
5487 Declaration of variables should wait as long as possible.
5488  The rule is:
5489 \begin_inset Quotes eld
5490 \end_inset
5491
5492 Don't declare it until you need it.
5493 \begin_inset Quotes erd
5494 \end_inset
5495
5496  In C++ there are a lot of user defined types, and these can very often
5497  be expensive to initialize.
5498  This rule connects to the next rule too.
5499
5500 \end_layout
5501
5502 \begin_layout Itemize
5503 Declare the variable as
5504 \begin_inset Flex Code
5505 status collapsed
5506
5507 \begin_layout Plain Layout
5508 const
5509 \end_layout
5510
5511 \end_inset
5512
5513  if you don't need to change it.
5514  This applies to POD types like
5515 \begin_inset Flex Code
5516 status collapsed
5517
5518 \begin_layout Plain Layout
5519 int
5520 \end_layout
5521
5522 \end_inset
5523
5524  as well as classes.
5525
5526 \end_layout
5527
5528 \begin_layout Itemize
5529 Make the scope of a variable as small as possible.
5530 \end_layout
5531
5532 \begin_layout Itemize
5533 Make good use of namespaces.
5534  Prefer anonymous namespaces to declaring
5535 \begin_inset Flex Code
5536 status collapsed
5537
5538 \begin_layout Plain Layout
5539 static
5540 \end_layout
5541
5542 \end_inset
5543
5544  for file scope.
5545 \end_layout
5546
5547 \begin_layout Itemize
5548 Prefer preincrement to postincrement whenever possible.
5549 \end_layout
5550
5551 \begin_layout Itemize
5552 Preincrement has potential of being faster than postincrement.
5553  Just think about the obvious implementations of pre/post-increment.
5554  This rule applies to decrement too.
5555 \end_layout
5556
5557 \begin_layout Itemize
5558 Use:
5559 \begin_inset Separator latexpar
5560 \end_inset
5561
5562
5563 \end_layout
5564
5565 \begin_deeper
5566 \begin_layout Standard
5567 \begin_inset listings
5568 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5569 inline false
5570 status open
5571
5572 \begin_layout Plain Layout
5573
5574 ++T;
5575 \end_layout
5576
5577 \begin_layout Plain Layout
5578
5579 --U;
5580 \end_layout
5581
5582 \end_inset
5583
5584
5585 \end_layout
5586
5587 \begin_layout Standard
5588 Do not use:
5589 \end_layout
5590
5591 \begin_layout Standard
5592 \begin_inset listings
5593 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5594 inline false
5595 status open
5596
5597 \begin_layout Plain Layout
5598
5599 T++; // not used in LyX
5600 \end_layout
5601
5602 \begin_layout Plain Layout
5603
5604 U--; // not used in LyX
5605 \end_layout
5606
5607 \end_inset
5608
5609
5610 \end_layout
5611
5612 \end_deeper
5613 \begin_layout Itemize
5614 Try to minimize evaluation of the same code over and over.
5615  This is aimed especially at loops.
5616
5617 \begin_inset Newline newline
5618 \end_inset
5619
5620 Use:
5621 \begin_inset Separator latexpar
5622 \end_inset
5623
5624
5625 \end_layout
5626
5627 \begin_deeper
5628 \begin_layout Standard
5629 \begin_inset listings
5630 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5631 inline false
5632 status open
5633
5634 \begin_layout Plain Layout
5635
5636 Container::iterator end = large.end();
5637 \end_layout
5638
5639 \begin_layout Plain Layout
5640
5641 for (Container::iterator it = large.begin(); it != end; ++it) {
5642 \end_layout
5643
5644 \begin_layout Plain Layout
5645
5646         ...;
5647 \end_layout
5648
5649 \begin_layout Plain Layout
5650
5651 }
5652 \end_layout
5653
5654 \end_inset
5655
5656
5657 \end_layout
5658
5659 \begin_layout Standard
5660 Or better (C++11):
5661 \end_layout
5662
5663 \begin_layout Standard
5664 \begin_inset listings
5665 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5666 inline false
5667 status open
5668
5669 \begin_layout Plain Layout
5670
5671 for (auto const & it : large) {
5672 \end_layout
5673
5674 \begin_layout Plain Layout
5675
5676         ...;
5677 \end_layout
5678
5679 \begin_layout Plain Layout
5680
5681 }
5682 \end_layout
5683
5684 \end_inset
5685
5686
5687 \end_layout
5688
5689 \begin_layout Standard
5690 Do not use:
5691 \end_layout
5692
5693 \begin_layout Standard
5694 \begin_inset listings
5695 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5696 inline false
5697 status open
5698
5699 \begin_layout Plain Layout
5700
5701 for (Container::iterator it = large.begin(); it != large.end(); ++it) {
5702 \end_layout
5703
5704 \begin_layout Plain Layout
5705
5706         ...;
5707 \end_layout
5708
5709 \begin_layout Plain Layout
5710
5711 }
5712 \end_layout
5713
5714 \end_inset
5715
5716
5717 \end_layout
5718
5719 \end_deeper
5720 \begin_layout Itemize
5721 For functions and methods that return a non-POD type
5722 \begin_inset Foot
5723 status open
5724
5725 \begin_layout Plain Layout
5726 Plain Ol' Data type
5727 \end_layout
5728
5729 \end_inset
5730
5731
5732 \begin_inset Flex Code
5733 status collapsed
5734
5735 \begin_layout Plain Layout
5736 T
5737 \end_layout
5738
5739 \end_inset
5740
5741 , return
5742 \begin_inset Flex Code
5743 status collapsed
5744
5745 \begin_layout Plain Layout
5746 T const
5747 \end_layout
5748
5749 \end_inset
5750
5751  instead.
5752  This gives better type checking, and will give a compiler warning when
5753  temporaries are used wrongly.
5754 \begin_inset Separator latexpar
5755 \end_inset
5756
5757
5758 \end_layout
5759
5760 \begin_deeper
5761 \begin_layout Standard
5762 Use:
5763 \end_layout
5764
5765 \begin_layout Standard
5766 \begin_inset listings
5767 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5768 inline false
5769 status open
5770
5771 \begin_layout Plain Layout
5772
5773 T const add(...);
5774 \end_layout
5775
5776 \end_inset
5777
5778
5779 \end_layout
5780
5781 \begin_layout Standard
5782 Do not use:
5783 \end_layout
5784
5785 \begin_layout Standard
5786 \begin_inset listings
5787 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5788 inline false
5789 status open
5790
5791 \begin_layout Plain Layout
5792
5793 T add(...);
5794 \end_layout
5795
5796 \end_inset
5797
5798
5799 \end_layout
5800
5801 \end_deeper
5802 \begin_layout Itemize
5803 Avoid using the default cases in switch statements unless you have too.
5804  Use the correct type for the switch expression and let the compiler ensure
5805  that all cases are exhausted.
5806 \end_layout
5807
5808 \begin_layout Itemize
5809 \begin_inset listings
5810 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5811 inline false
5812 status open
5813
5814 \begin_layout Plain Layout
5815
5816 enum Foo {
5817 \end_layout
5818
5819 \begin_layout Plain Layout
5820
5821         FOO_BAR1,
5822 \end_layout
5823
5824 \begin_layout Plain Layout
5825
5826         FOO_BAR2
5827 \end_layout
5828
5829 \begin_layout Plain Layout
5830
5831 };
5832 \end_layout
5833
5834 \begin_layout Plain Layout
5835
5836 \end_layout
5837
5838 \begin_layout Plain Layout
5839
5840 Foo f = ...;
5841 \end_layout
5842
5843 \begin_layout Plain Layout
5844
5845 \end_layout
5846
5847 \begin_layout Plain Layout
5848
5849 switch (f) {
5850 \end_layout
5851
5852 \begin_layout Plain Layout
5853
5854 case FOO_BAR1: ...;
5855 \end_layout
5856
5857 \begin_layout Plain Layout
5858
5859         break;
5860 \end_layout
5861
5862 \begin_layout Plain Layout
5863
5864 case FOO_BAR2: ...;
5865 \end_layout
5866
5867 \begin_layout Plain Layout
5868
5869         break;
5870 \end_layout
5871
5872 \begin_layout Plain Layout
5873
5874 default: ...;
5875 \end_layout
5876
5877 \begin_layout Plain Layout
5878
5879         // not needed and would shadow a wrong use of Foo
5880 \end_layout
5881
5882 \begin_layout Plain Layout
5883
5884         break;
5885 \end_layout
5886
5887 \begin_layout Plain Layout
5888
5889 }
5890 \end_layout
5891
5892 \end_inset
5893
5894
5895 \end_layout
5896
5897 \begin_layout Section
5898 Exceptions
5899 \begin_inset CommandInset label
5900 LatexCommand label
5901 name "sec:Exceptions"
5902
5903 \end_inset
5904
5905
5906 \end_layout
5907
5908 \begin_layout Standard
5909 Be aware of the presence of exceptions.
5910  One important thing to realize is that you often do not have to use throw,
5911  try or catch to be exception safe.
5912  Let's look at the different types of exceptions safety (these are taken
5913  from Herb Sutter's book
5914 \begin_inset CommandInset citation
5915 LatexCommand cite
5916 key "sutter"
5917 literal "false"
5918
5919 \end_inset
5920
5921 ):
5922 \end_layout
5923
5924 \begin_layout Enumerate
5925 Basic guarantee: Even in the presence of exceptions thrown by T or other
5926  exceptions, Stack objects don't leak resources.
5927  Note that this also implies that the container will be destructible and
5928  usable even if an exception is thrown while performing some container operation.
5929  However, if an exception is thrown, the container will be in a consistent,
5930  but not necessarily predictable, state.
5931  Containers that support the basic guarantee can work safely in some settings.
5932
5933 \end_layout
5934
5935 \begin_layout Enumerate
5936 Strong guarantee: If an operation terminates because of an exception, program
5937  state will remain unchanged.
5938  This always implies commit-or-rollback semantics, including that no references
5939  or iterators into the container be invalidated if an operation fails.
5940  For example, if a Stack client calls Top and then attempts a Push that
5941  fails because of an exception, then the state of the Stack object must
5942  be unchanged and the reference returned from the prior call to Top must
5943  still be valid.
5944  For more information on these guarantees, see Dave Abrahams's documentation
5945  of the SGI exception-safe standard library adaption at:
5946 \begin_inset Flex URL
5947 status open
5948
5949 \begin_layout Plain Layout
5950
5951 http://www.stlport.org/doc/exception_safety.html
5952 \end_layout
5953
5954 \end_inset
5955
5956  Probably the most interesting point here is that when you implement the
5957  basic guarantee, the strong guarantee often comes for free.
5958  For example, in our Stack implementation, almost everything we did was
5959  needed to satisfy just the basic guarantee – and what's presented above
5960  very nearly satisfies the strong guarantee, with little or no extra work.
5961  Not half bad, considering all the trouble we went to.
5962  In addition to these two guarantees, there is one more guarantee that certain
5963  functions must provide in order to make overall exception safety possible:
5964 \end_layout
5965
5966 \begin_layout Enumerate
5967 No throw guarantee: The function will not emit an exception under any circumstan
5968 ces.
5969  Overall exception safety isn't possible unless certain functions are guaranteed
5970  not to throw.
5971  In particular, we've seen that this is true for destructors; later in this
5972  miniseries, we'll see that it's also needed in certain helper functions,
5973  such as
5974 \family typewriter
5975 Swap()
5976 \family default
5977 .
5978 \end_layout
5979
5980 \begin_layout Standard
5981 For all cases where we might be able to write exception safe functions without
5982  using try, throw or catch we should do so.
5983  In particular we should look over all destructors to ensure that they are
5984  as exception safe as possible.
5985 \end_layout
5986
5987 \begin_layout Section
5988 Formatting
5989 \begin_inset CommandInset label
5990 LatexCommand label
5991 name "sec:Formatting"
5992
5993 \end_inset
5994
5995
5996 \end_layout
5997
5998 \begin_layout Itemize
5999 Only one declaration on each line.
6000 \begin_inset Separator latexpar
6001 \end_inset
6002
6003
6004 \end_layout
6005
6006 \begin_deeper
6007 \begin_layout Standard
6008 Use:
6009 \end_layout
6010
6011 \begin_layout Standard
6012 \begin_inset listings
6013 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6014 inline false
6015 status open
6016
6017 \begin_layout Plain Layout
6018
6019 int a;
6020 \end_layout
6021
6022 \begin_layout Plain Layout
6023
6024 int b;
6025 \end_layout
6026
6027 \end_inset
6028
6029
6030 \end_layout
6031
6032 \begin_layout Standard
6033 Do not use:
6034 \end_layout
6035
6036 \begin_layout Standard
6037 \begin_inset listings
6038 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6039 inline false
6040 status open
6041
6042 \begin_layout Plain Layout
6043
6044 int a, b; // not used in LyX
6045 \end_layout
6046
6047 \end_inset
6048
6049
6050 \end_layout
6051
6052 \begin_layout Standard
6053 This is especially important when initialization is done at the same time:
6054 \end_layout
6055
6056 \begin_layout Standard
6057 Use:
6058 \end_layout
6059
6060 \begin_layout Standard
6061 \begin_inset listings
6062 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6063 inline false
6064 status open
6065
6066 \begin_layout Plain Layout
6067
6068 string a = "Lars";
6069 \end_layout
6070
6071 \begin_layout Plain Layout
6072
6073 string b = "Gullik";
6074 \end_layout
6075
6076 \end_inset
6077
6078
6079 \end_layout
6080
6081 \begin_layout Standard
6082 Do not use:
6083 \end_layout
6084
6085 \begin_layout Standard
6086 \begin_inset listings
6087 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6088 inline false
6089 status open
6090
6091 \begin_layout Plain Layout
6092
6093 string a = "Lars", b = "Gullik"; // not used in LyX
6094 \end_layout
6095
6096 \end_inset
6097
6098
6099 \end_layout
6100
6101 \begin_layout Standard
6102 [Note that
6103 \begin_inset Flex Code
6104 status collapsed
6105
6106 \begin_layout Plain Layout
6107 string a = "Lars"
6108 \end_layout
6109
6110 \end_inset
6111
6112  is formally calling a copy constructor on a temporary constructed from
6113  a string literal and therefore has the potential of being more expensive
6114  then direct construction by
6115 \begin_inset Flex Code
6116 status collapsed
6117
6118 \begin_layout Plain Layout
6119 string a("Lars")
6120 \end_layout
6121
6122 \end_inset
6123
6124 .
6125  However the compiler is allowed to elide the copy (even if it had side
6126  effects), and modern compilers typically do so.
6127  Given these equal costs, \SpecialChar LyX
6128  code favours the '=' idiom as it is in line with
6129  the traditional C-style initialization,
6130 \emph on
6131 and
6132 \emph default
6133  cannot be mistaken as function declaration,
6134 \emph on
6135 and
6136 \emph default
6137  reduces the level of nested parentheses in more initializations.]
6138 \end_layout
6139
6140 \end_deeper
6141 \begin_layout Itemize
6142 Pointers and references:
6143 \begin_inset Separator latexpar
6144 \end_inset
6145
6146
6147 \end_layout
6148
6149 \begin_deeper
6150 \begin_layout Standard
6151 Use:
6152 \end_layout
6153
6154 \begin_layout Standard
6155 \begin_inset listings
6156 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6157 inline false
6158 status open
6159
6160 \begin_layout Plain Layout
6161
6162 char * p = "flop";
6163 \end_layout
6164
6165 \begin_layout Plain Layout
6166
6167 char & c = *p;
6168 \end_layout
6169
6170 \end_inset
6171
6172
6173 \end_layout
6174
6175 \begin_layout Standard
6176 Do not use:
6177 \end_layout
6178
6179 \begin_layout Standard
6180 \begin_inset listings
6181 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6182 inline false
6183 status open
6184
6185 \begin_layout Plain Layout
6186
6187 char *p = "flop"; // not used in LyX
6188 \end_layout
6189
6190 \begin_layout Plain Layout
6191
6192 char &c = *p; // not used in LyX
6193 \end_layout
6194
6195 \end_inset
6196
6197
6198 \end_layout
6199
6200 \begin_layout Standard
6201 Some time ago we had a huge discussion on this subject and after convincing
6202  argumentation from Asger this is what we decided.
6203  Also note that we will have:
6204 \end_layout
6205
6206 \begin_layout Standard
6207 \begin_inset listings
6208 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6209 inline false
6210 status open
6211
6212 \begin_layout Plain Layout
6213
6214 char const * p;
6215 \end_layout
6216
6217 \end_inset
6218
6219
6220 \end_layout
6221
6222 \begin_layout Standard
6223 and not
6224 \end_layout
6225
6226 \begin_layout Standard
6227 \begin_inset listings
6228 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6229 inline false
6230 status open
6231
6232 \begin_layout Plain Layout
6233
6234 const char * p; // not used in LyX
6235 \end_layout
6236
6237 \end_inset
6238
6239
6240 \end_layout
6241
6242 \end_deeper
6243 \begin_layout Itemize
6244 Operator names and parentheses
6245 \begin_inset Separator latexpar
6246 \end_inset
6247
6248
6249 \end_layout
6250
6251 \begin_deeper
6252 \begin_layout Standard
6253 \begin_inset listings
6254 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6255 inline false
6256 status open
6257
6258 \begin_layout Plain Layout
6259
6260 operator==(type)
6261 \end_layout
6262
6263 \end_inset
6264
6265
6266 \end_layout
6267
6268 \begin_layout Standard
6269 and not
6270 \end_layout
6271
6272 \begin_layout Standard
6273 \begin_inset listings
6274 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6275 inline false
6276 status open
6277
6278 \begin_layout Plain Layout
6279
6280 operator == (type) // not used in LyX
6281 \end_layout
6282
6283 \end_inset
6284
6285
6286 \end_layout
6287
6288 \begin_layout Standard
6289 The == is part of the function name, separating it makes the declaration
6290  look like an expression.
6291 \end_layout
6292
6293 \end_deeper
6294 \begin_layout Itemize
6295 Function names and parentheses
6296 \begin_inset Separator latexpar
6297 \end_inset
6298
6299
6300 \end_layout
6301
6302 \begin_deeper
6303 \begin_layout Standard
6304 \begin_inset listings
6305 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6306 inline false
6307 status open
6308
6309 \begin_layout Plain Layout
6310
6311 void mangle()
6312 \end_layout
6313
6314 \end_inset
6315
6316
6317 \end_layout
6318
6319 \begin_layout Standard
6320 and not
6321 \end_layout
6322
6323 \begin_layout Standard
6324 \begin_inset listings
6325 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6326 inline false
6327 status open
6328
6329 \begin_layout Plain Layout
6330
6331 void mangle () // not used in LyX
6332 \end_layout
6333
6334 \end_inset
6335
6336
6337 \end_layout
6338
6339 \end_deeper
6340 \begin_layout Itemize
6341 Enumerators
6342 \begin_inset Separator latexpar
6343 \end_inset
6344
6345
6346 \end_layout
6347
6348 \begin_deeper
6349 \begin_layout Standard
6350 \begin_inset listings
6351 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6352 inline false
6353 status open
6354
6355 \begin_layout Plain Layout
6356
6357 enum Foo {
6358 \end_layout
6359
6360 \begin_layout Plain Layout
6361
6362         FOO_ONE = 1,
6363 \end_layout
6364
6365 \begin_layout Plain Layout
6366
6367         FOO_TWO = 2,
6368 \end_layout
6369
6370 \begin_layout Plain Layout
6371
6372         FOO_THREE = 3
6373 \end_layout
6374
6375 \begin_layout Plain Layout
6376
6377 };
6378 \end_layout
6379
6380 \end_inset
6381
6382
6383 \end_layout
6384
6385 \begin_layout Standard
6386 and not
6387 \end_layout
6388
6389 \begin_layout Standard
6390 \begin_inset listings
6391 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6392 inline false
6393 status open
6394
6395 \begin_layout Plain Layout
6396
6397 enum { one = 1, two = 2, three 3 }; // not used in LyX
6398 \end_layout
6399
6400 \end_inset
6401
6402
6403 \end_layout
6404
6405 \begin_layout Standard
6406 and not
6407 \end_layout
6408
6409 \begin_layout Standard
6410 \begin_inset listings
6411 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6412 inline false
6413 status open
6414
6415 \begin_layout Plain Layout
6416
6417 enum {
6418 \end_layout
6419
6420 \begin_layout Plain Layout
6421
6422 One = 1,
6423 \end_layout
6424
6425 \begin_layout Plain Layout
6426
6427 Two = 2,
6428 \end_layout
6429
6430 \begin_layout Plain Layout
6431
6432 Three = 3
6433 \end_layout
6434
6435 \begin_layout Plain Layout
6436
6437 };
6438 \end_layout
6439
6440 \end_inset
6441
6442
6443 \end_layout
6444
6445 \end_deeper
6446 \begin_layout Itemize
6447 Null pointers
6448 \begin_inset Separator latexpar
6449 \end_inset
6450
6451
6452 \end_layout
6453
6454 \begin_deeper
6455 \begin_layout Standard
6456 Use nullptr (C++11):
6457 \end_layout
6458
6459 \begin_layout Standard
6460 \begin_inset listings
6461 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6462 inline false
6463 status open
6464
6465 \begin_layout Plain Layout
6466
6467 void * p = nullptr;
6468 \end_layout
6469
6470 \end_inset
6471
6472
6473 \end_layout
6474
6475 \begin_layout Standard
6476 and not
6477 \end_layout
6478
6479 \begin_layout Standard
6480 \begin_inset listings
6481 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6482 inline false
6483 status open
6484
6485 \begin_layout Plain Layout
6486
6487 void * p = NULL; // not used in LyX
6488 \end_layout
6489
6490 \end_inset
6491
6492
6493 \end_layout
6494
6495 \begin_layout Standard
6496 and not
6497 \end_layout
6498
6499 \begin_layout Standard
6500 \begin_inset listings
6501 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6502 inline false
6503 status open
6504
6505 \begin_layout Plain Layout
6506
6507 void * p = '
6508 \backslash
6509 0'; // not used in LyX
6510 \end_layout
6511
6512 \end_inset
6513
6514
6515 \end_layout
6516
6517 \begin_layout Standard
6518 and not
6519 \end_layout
6520
6521 \begin_layout Standard
6522 \begin_inset listings
6523 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6524 inline false
6525 status open
6526
6527 \begin_layout Plain Layout
6528
6529 void * p = 42 - 7 * 6; // not used in LyX
6530 \end_layout
6531
6532 \end_inset
6533
6534
6535 \end_layout
6536
6537 \begin_layout Standard
6538 Note: As an exception, imported third party code as well as code interfacing
6539  the
6540 \begin_inset Quotes eld
6541 \end_inset
6542
6543 native
6544 \begin_inset Quotes erd
6545 \end_inset
6546
6547  APIs (
6548 \begin_inset Flex Code
6549 status collapsed
6550
6551 \begin_layout Plain Layout
6552 src/support/os_*
6553 \end_layout
6554
6555 \end_inset
6556
6557 ) can use NULL.
6558 \end_layout
6559
6560 \end_deeper
6561 \begin_layout Itemize
6562 Naming rules for classes
6563 \begin_inset Separator latexpar
6564 \end_inset
6565
6566
6567 \end_layout
6568
6569 \begin_deeper
6570 \begin_layout Itemize
6571 Use descriptive but simple and short names.
6572  Do not abbreviate.
6573 \end_layout
6574
6575 \begin_layout Itemize
6576 Class names are usually capitalized, and function names lowercased.
6577 \end_layout
6578
6579 \begin_layout Itemize
6580 Enums are named like Classes, values are usually in lower-case.
6581 \end_layout
6582
6583 \begin_layout Itemize
6584 Public API functions are camel-case (
6585 \begin_inset Flex Code
6586 status collapsed
6587
6588 \begin_layout Plain Layout
6589 void setAFlagToAValue(bool)
6590 \end_layout
6591
6592 \end_inset
6593
6594 ).
6595 \end_layout
6596
6597 \begin_layout Itemize
6598 Member variables are underscored (
6599 \begin_inset Flex Code
6600 status collapsed
6601
6602 \begin_layout Plain Layout
6603 enable_this_feature_flag_
6604 \end_layout
6605
6606 \end_inset
6607
6608 ) with a final
6609 \begin_inset Quotes eld
6610 \end_inset
6611
6612 _
6613 \begin_inset Quotes erd
6614 \end_inset
6615
6616 .
6617 \end_layout
6618
6619 \begin_layout Itemize
6620 Private/protected functions are also camel-case.
6621 \end_layout
6622
6623 \begin_layout Itemize
6624 New types are capitalized, so this goes for typedefs, classes, structs and
6625  enums.
6626 \end_layout
6627
6628 \end_deeper
6629 \begin_layout Itemize
6630 Formatting
6631 \begin_inset Separator latexpar
6632 \end_inset
6633
6634
6635 \end_layout
6636
6637 \begin_deeper
6638 \begin_layout Itemize
6639 Adapt the formatting of your code to the one used in the other parts of
6640  \SpecialChar LyX
6641 .
6642  In case there is different formatting for the same construct, use the one
6643  used more often.
6644 \end_layout
6645
6646 \end_deeper
6647 \begin_layout Itemize
6648 Use existing structures
6649 \begin_inset Separator latexpar
6650 \end_inset
6651
6652
6653 \end_layout
6654
6655 \begin_deeper
6656 \begin_layout Itemize
6657 \begin_inset CommandInset label
6658 LatexCommand label
6659 name "Use-string-wherever"
6660
6661 \end_inset
6662
6663 Use
6664 \begin_inset Flex Code
6665 status collapsed
6666
6667 \begin_layout Plain Layout
6668 string
6669 \end_layout
6670
6671 \end_inset
6672
6673  wherever possible.
6674  Unicode strings should prefer using
6675 \begin_inset Flex Code
6676 status collapsed
6677
6678 \begin_layout Plain Layout
6679 docstring
6680 \end_layout
6681
6682 \end_inset
6683
6684  instead of UTF-8 encoded
6685 \begin_inset Flex Code
6686 status collapsed
6687
6688 \begin_layout Plain Layout
6689 std::string
6690 \end_layout
6691
6692 \end_inset
6693
6694 .
6695 \end_layout
6696
6697 \begin_layout Itemize
6698 Check out the filename and path tools in
6699 \begin_inset Flex Code
6700 status collapsed
6701
6702 \begin_layout Plain Layout
6703 filetools.h
6704 \end_layout
6705
6706 \end_inset
6707
6708
6709 \end_layout
6710
6711 \begin_layout Itemize
6712 Check out the string tools in
6713 \begin_inset Flex Code
6714 status collapsed
6715
6716 \begin_layout Plain Layout
6717 lstring.h
6718 \end_layout
6719
6720 \end_inset
6721
6722 .
6723 \end_layout
6724
6725 \begin_layout Itemize
6726 Use the \SpecialChar LyX
6727 Err class to report errors and messages using the lyxerr instantiation.
6728  [add description of other existing structures]
6729 \end_layout
6730
6731 \end_deeper
6732 \begin_layout Itemize
6733 Declarations
6734 \begin_inset Separator latexpar
6735 \end_inset
6736
6737
6738 \end_layout
6739
6740 \begin_deeper
6741 \begin_layout Itemize
6742 Use this order for the access sections of your class: public, protected,
6743  private.
6744  The public section is interesting for every user of the class.
6745  The private section is only of interest for the implementors of the class
6746  (you).
6747  [Obviously not true since this is for developers, and we do not want one
6748  developer only to be able to read and understand the implementation of
6749  class internals.
6750  Lgb]
6751 \end_layout
6752
6753 \begin_layout Itemize
6754 Avoid declaring global objects in the declaration file of the class.
6755  If the same variable is used for all objects, use a static member.
6756 \end_layout
6757
6758 \begin_layout Itemize
6759 Avoid global or static variables.
6760 \end_layout
6761
6762 \end_deeper
6763 \begin_layout Itemize
6764 File headers
6765 \begin_inset Separator latexpar
6766 \end_inset
6767
6768
6769 \end_layout
6770
6771 \begin_deeper
6772 \begin_layout Standard
6773 If you create a new file, the top of the file should look something like
6774  this :
6775 \end_layout
6776
6777 \begin_layout Standard
6778 \begin_inset listings
6779 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6780 inline false
6781 status open
6782
6783 \begin_layout Plain Layout
6784
6785 /**
6786 \end_layout
6787
6788 \begin_layout Plain Layout
6789
6790 *
6791 \backslash
6792 file NewFile.cpp
6793 \end_layout
6794
6795 \begin_layout Plain Layout
6796
6797 * This file is part of LyX, the document processor.
6798 \end_layout
6799
6800 \begin_layout Plain Layout
6801
6802 * Licence details can be found in the file COPYING.
6803 \end_layout
6804
6805 \begin_layout Plain Layout
6806
6807 *
6808 \end_layout
6809
6810 \begin_layout Plain Layout
6811
6812 *
6813 \backslash
6814 author Kaiser Sose
6815 \end_layout
6816
6817 \begin_layout Plain Layout
6818
6819 *
6820 \end_layout
6821
6822 \begin_layout Plain Layout
6823
6824 * Full author contact details are available
6825 \end_layout
6826
6827 \begin_layout Plain Layout
6828
6829 * in file CREDITS.
6830 \end_layout
6831
6832 \begin_layout Plain Layout
6833
6834 */
6835 \end_layout
6836
6837 \end_inset
6838
6839
6840 \end_layout
6841
6842 \end_deeper
6843 \begin_layout Itemize
6844 Documentation
6845 \begin_inset Separator latexpar
6846 \end_inset
6847
6848
6849 \end_layout
6850
6851 \begin_deeper
6852 \begin_layout Itemize
6853 The documentation is generated from the header files.
6854 \end_layout
6855
6856 \begin_layout Itemize
6857 You document for the other developers, not for yourself.
6858 \end_layout
6859
6860 \begin_layout Itemize
6861 You should document what the function does, not the implementation.
6862 \begin_inset Separator latexpar
6863 \end_inset
6864
6865
6866 \end_layout
6867
6868 \begin_deeper
6869 \begin_layout Itemize
6870 in the .cpp files you document the implementation.
6871 \end_layout
6872
6873 \end_deeper
6874 \begin_layout Itemize
6875 Single line description (
6876 \begin_inset Flex Code
6877 status collapsed
6878
6879 \begin_layout Plain Layout
6880 ///
6881 \end_layout
6882
6883 \end_inset
6884
6885 ), multiple lines description (
6886 \begin_inset Flex Code
6887 status collapsed
6888
6889 \begin_layout Plain Layout
6890 /** ...
6891  */
6892 \end_layout
6893
6894 \end_inset
6895
6896 ), see the doxygen webpage referenced above.
6897 \end_layout
6898
6899 \end_deeper
6900 \begin_layout Section
6901 Naming rules for \SpecialChar LyX
6902  User Functions (LFUNs)
6903 \end_layout
6904
6905 \begin_layout Standard
6906 Here is the set of rules to apply when a new command name is introduced:
6907 \end_layout
6908
6909 \begin_layout Enumerate
6910 Use the object.event order.
6911  That is, use `word-forward' instead of `forward-word'.
6912 \end_layout
6913
6914 \begin_layout Enumerate
6915 Don't introduce an alias for an already named object.
6916  Same for events.
6917 \end_layout
6918
6919 \begin_layout Enumerate
6920 Forward movement or focus is called `forward' (not `right').
6921 \end_layout
6922
6923 \begin_layout Enumerate
6924 Backward movement or focus is called `backward' (not `left').
6925 \end_layout
6926
6927 \begin_layout Enumerate
6928 Upward movement of focus is called `up'.
6929 \end_layout
6930
6931 \begin_layout Enumerate
6932 Downward movement is called `down'.
6933 \end_layout
6934
6935 \begin_layout Enumerate
6936 The begin of an object is called `begin' (not `start').
6937 \end_layout
6938
6939 \begin_layout Enumerate
6940 The end of an object is called `end'.
6941 \end_layout
6942
6943 \begin_layout Section
6944 How to create class interfaces
6945 \end_layout
6946
6947 \begin_layout Standard
6948 (a.k.a How Non-Member Functions Improve Encapsulation)
6949 \end_layout
6950
6951 \begin_layout Standard
6952 I recently read an article by Scott Meyers, where he makes a strong case
6953  on how non-member functions makes classes more encapsulated, not less.
6954  Just skipping to the core of this provides us with the following algorithm
6955  for deciding what kind of function to add to a class interface:
6956 \end_layout
6957
6958 \begin_layout Itemize
6959 We need to add a function f to the class C's API.
6960 \begin_inset Separator latexpar
6961 \end_inset
6962
6963
6964 \end_layout
6965
6966 \begin_deeper
6967 \begin_layout Standard
6968 \begin_inset listings
6969 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6970 inline false
6971 status open
6972
6973 \begin_layout Plain Layout
6974
6975 if (f needs to be virtual)
6976 \end_layout
6977
6978 \begin_layout Plain Layout
6979
6980         make f a member function of C;
6981 \end_layout
6982
6983 \begin_layout Plain Layout
6984
6985 else if (f is operator>> or operator<<) {
6986 \end_layout
6987
6988 \begin_layout Plain Layout
6989
6990         make f a non-member function;
6991 \end_layout
6992
6993 \begin_layout Plain Layout
6994
6995         if (f needs access to non-public members of C)
6996 \end_layout
6997
6998 \begin_layout Plain Layout
6999
7000                 make f a friend of C;
7001 \end_layout
7002
7003 \begin_layout Plain Layout
7004
7005 } else if (f needs type conversions on its left-most argument) {
7006 \end_layout
7007
7008 \begin_layout Plain Layout
7009
7010         make f a non-member function;
7011 \end_layout
7012
7013 \begin_layout Plain Layout
7014
7015         if (f needs access to non-public members of C)
7016 \end_layout
7017
7018 \begin_layout Plain Layout
7019
7020                 make f a friend of C;
7021 \end_layout
7022
7023 \begin_layout Plain Layout
7024
7025 } else if (f can be implemented via C's public interface)
7026 \end_layout
7027
7028 \begin_layout Plain Layout
7029
7030         make f a non-member function;
7031 \end_layout
7032
7033 \begin_layout Plain Layout
7034
7035 else
7036 \end_layout
7037
7038 \begin_layout Plain Layout
7039
7040         make f a member function of C;
7041 \end_layout
7042
7043 \end_inset
7044
7045
7046 \end_layout
7047
7048 \end_deeper
7049 \begin_layout Chapter
7050 Coding recommendations
7051 \end_layout
7052
7053 \begin_layout Standard
7054 These are some rules for effective C++ programming.
7055  These are taken from Scott Meyers
7056 \begin_inset CommandInset citation
7057 LatexCommand cite
7058 key "journal"
7059 literal "true"
7060
7061 \end_inset
7062
7063 , and are presented in their short form.
7064  These are not all the rules Meyers presents, only the most important of
7065  them.
7066  \SpecialChar LyX
7067  does not yet follow these rules, but they should be the goal.
7068 \end_layout
7069
7070 \begin_layout Itemize
7071 use
7072 \family typewriter
7073 const
7074 \family default
7075  and
7076 \family typewriter
7077 inline
7078 \family default
7079  instead of
7080 \family typewriter
7081 #define
7082 \end_layout
7083
7084 \begin_layout Itemize
7085 use the same form in corresponding calls to new and delete, i.e.
7086  write
7087 \begin_inset Flex Code
7088 status collapsed
7089
7090 \begin_layout Plain Layout
7091 delete[] obj;
7092 \end_layout
7093
7094 \end_inset
7095
7096  if
7097 \begin_inset Flex Code
7098 status collapsed
7099
7100 \begin_layout Plain Layout
7101 new obj[n];
7102 \end_layout
7103
7104 \end_inset
7105
7106  was used to create the object and write
7107 \begin_inset Flex Code
7108 status collapsed
7109
7110 \begin_layout Plain Layout
7111 delete obj;
7112 \end_layout
7113
7114 \end_inset
7115
7116  if you wrote
7117 \begin_inset Flex Code
7118 status collapsed
7119
7120 \begin_layout Plain Layout
7121 new obj;
7122 \end_layout
7123
7124 \end_inset
7125
7126  Notice strings should be
7127 \begin_inset Flex Code
7128 status collapsed
7129
7130 \begin_layout Plain Layout
7131 std::string
7132 \end_layout
7133
7134 \end_inset
7135
7136 's instead of
7137 \begin_inset Flex Code
7138 status collapsed
7139
7140 \begin_layout Plain Layout
7141 char *
7142 \end_layout
7143
7144 \end_inset
7145
7146 's.
7147  (this contradicts to
7148 \begin_inset CommandInset ref
7149 LatexCommand ref
7150 reference "Use-string-wherever"
7151
7152 \end_inset
7153
7154  )
7155 \end_layout
7156
7157 \begin_layout Itemize
7158 define a default constructor, copy constructor and an assignment operator
7159  for all classes with dynamically allocated memory that are not made noncopyable
7160 \end_layout
7161
7162 \begin_layout Itemize
7163 do not define default constructor, copy constructor and an assignment operator
7164  if the compiler generated one would do the same
7165 \end_layout
7166
7167 \begin_layout Itemize
7168 make destructors virtual in base classes and only there
7169 \end_layout
7170
7171 \begin_layout Itemize
7172 assign to all data members in operator=()
7173 \end_layout
7174
7175 \begin_layout Itemize
7176 strive for class interfaces that are complete and minimal
7177 \end_layout
7178
7179 \begin_layout Itemize
7180 differentiate among member functions, global functions and friend functions
7181 \end_layout
7182
7183 \begin_layout Itemize
7184 avoid data members in the public interface
7185 \end_layout
7186
7187 \begin_layout Itemize
7188 use const whenever possible
7189 \end_layout
7190
7191 \begin_layout Itemize
7192 pass and return objects by reference instead of by value
7193 \end_layout
7194
7195 \begin_layout Itemize
7196 choose carefully between function overloading and parameter defaulting
7197 \end_layout
7198
7199 \begin_layout Itemize
7200 never return a reference to a local object or a dereferenced pointer initialized
7201  by new within the function
7202 \end_layout
7203
7204 \begin_layout Itemize
7205 use enums for integral constants
7206 \end_layout
7207
7208 \begin_layout Itemize
7209 minimize compilation dependencies between files
7210 \end_layout
7211
7212 \begin_layout Itemize
7213 pay attention to compiler warnings
7214 \end_layout
7215
7216 \begin_layout Itemize
7217 differentiate between inheritance of interface and inheritance of implementation
7218 \end_layout
7219
7220 \begin_layout Itemize
7221 differentiate between inheritance and templates
7222 \end_layout
7223
7224 \begin_layout Itemize
7225 ensure that global objects are initialized before they are used
7226 \end_layout
7227
7228 \begin_layout Itemize
7229 avoid conditions to
7230 \begin_inset Flex Code
7231 status collapsed
7232
7233 \begin_layout Plain Layout
7234 if
7235 \end_layout
7236
7237 \end_inset
7238
7239  and
7240 \begin_inset Flex Code
7241 status collapsed
7242
7243 \begin_layout Plain Layout
7244 while
7245 \end_layout
7246
7247 \end_inset
7248
7249  that span more than a line
7250 \end_layout
7251
7252 \begin_layout Chapter
7253 \start_of_appendix
7254 Notes
7255 \end_layout
7256
7257 \begin_layout Itemize
7258 And one of mine: (Lgb)
7259 \begin_inset Separator latexpar
7260 \end_inset
7261
7262
7263 \end_layout
7264
7265 \begin_deeper
7266 \begin_layout Itemize
7267 when switching on enums, refrain from using "default:" if possible
7268 \end_layout
7269
7270 \end_deeper
7271 \begin_layout Itemize
7272 And one of mine: (Andre')
7273 \begin_inset Separator latexpar
7274 \end_inset
7275
7276
7277 \end_layout
7278
7279 \begin_deeper
7280 \begin_layout Itemize
7281 try to implement your class in a way that the automatically generated copy
7282  constructor and copy assignment work out-of-the box
7283 \end_layout
7284
7285 \begin_layout Itemize
7286 I don't have problems with using boost in the implementation _if and only
7287  if_ it provides actual benefits over less intrusive alternatives.
7288  I do have a problem with needlessly sprinkling 'boost::' over interfaces,
7289  especially if it does not add any value.
7290 \begin_inset Separator latexpar
7291 \end_inset
7292
7293
7294 \end_layout
7295
7296 \begin_deeper
7297 \begin_layout Standard
7298 Given that there seems to be an unconditional "typedef unsigned int quint32;"
7299  in qglobal.h I don't think there's any platform supported by current \SpecialChar LyX
7300  that
7301  could not use 'unsigned int' (and an static assert in some implementation
7302  file for the unlikely case some ILP64 zombie raises its ugly head again.
7303  And if that happens, using <cstdint> would still be a better choice...)
7304 \end_layout
7305
7306 \begin_layout Standard
7307 The idea is to create something that's not compilable as soon as the condition
7308  is violated.
7309  There are lots of possibilities to achieve this, some examples follow:
7310 \end_layout
7311
7312 \begin_layout Standard
7313 In C++11 there's a "built-in":
7314 \end_layout
7315
7316 \begin_layout Standard
7317 \begin_inset listings
7318 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7319 inline false
7320 status open
7321
7322 \begin_layout Plain Layout
7323
7324 static_assert(sizeof(int) == 4, "Funny platform")
7325 \end_layout
7326
7327 \end_inset
7328
7329
7330 \end_layout
7331
7332 \begin_layout Standard
7333 until then on namespace scope:
7334 \end_layout
7335
7336 \begin_layout Standard
7337 \begin_inset listings
7338 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7339 inline false
7340 status open
7341
7342 \begin_layout Plain Layout
7343
7344 #include <boost/static_assert.hpp>
7345 \end_layout
7346
7347 \begin_layout Plain Layout
7348
7349 BOOST_STATIC_ASSERT(sizeof(int) == 4)
7350 \end_layout
7351
7352 \end_inset
7353
7354
7355 \end_layout
7356
7357 \begin_layout Standard
7358 or without boost:
7359 \end_layout
7360
7361 \begin_layout Standard
7362 \begin_inset listings
7363 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7364 inline false
7365 status open
7366
7367 \begin_layout Plain Layout
7368
7369 template<bool Condition>
7370 \end_layout
7371
7372 \begin_layout Plain Layout
7373
7374 struct static_assert_helper;
7375 \end_layout
7376
7377 \begin_layout Plain Layout
7378
7379 template <>
7380 \end_layout
7381
7382 \begin_layout Plain Layout
7383
7384 struct static_assert_helper<true> {};
7385 \end_layout
7386
7387 \begin_layout Plain Layout
7388
7389 enum {
7390 \end_layout
7391
7392 \begin_layout Plain Layout
7393
7394         dummy = sizeof(static_assert_helper<sizeof(int) == 4>)
7395 \end_layout
7396
7397 \begin_layout Plain Layout
7398
7399 };
7400 \end_layout
7401
7402 \end_inset
7403
7404
7405 \end_layout
7406
7407 \begin_layout Standard
7408 or somewhat brutish without templates, in any function:
7409 \end_layout
7410
7411 \begin_layout Standard
7412 \begin_inset listings
7413 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7414 inline false
7415 status open
7416
7417 \begin_layout Plain Layout
7418
7419 const int d = sizeof(int) - 4;
7420 \end_layout
7421
7422 \begin_layout Plain Layout
7423
7424 switch (0) {
7425 \end_layout
7426
7427 \begin_layout Plain Layout
7428
7429 case 0:
7430 \end_layout
7431
7432 \begin_layout Plain Layout
7433
7434 case !(d*d):
7435 \end_layout
7436
7437 \begin_layout Plain Layout
7438
7439         break;
7440 \end_layout
7441
7442 \begin_layout Plain Layout
7443
7444 }
7445 \end_layout
7446
7447 \end_inset
7448
7449
7450 \end_layout
7451
7452 \begin_layout Standard
7453 Any of them in a .cpp file will break compilation as soon as
7454 \begin_inset Flex Code
7455 status collapsed
7456
7457 \begin_layout Plain Layout
7458 sizeof(int)
7459 \end_layout
7460
7461 \end_inset
7462
7463  is not equal 4.
7464  Personally I prefer something like the third version (or the first, if
7465  using C++11 is allowed).
7466 \end_layout
7467
7468 \end_deeper
7469 \end_deeper
7470 \begin_layout Itemize
7471 And one of mine: (vfr)
7472 \begin_inset Separator latexpar
7473 \end_inset
7474
7475
7476 \end_layout
7477
7478 \begin_deeper
7479 \begin_layout Itemize
7480 On dynamics_casts
7481 \begin_inset Flex URL
7482 status open
7483
7484 \begin_layout Plain Layout
7485
7486 http://www.lyx.org/trac/changeset/35855
7487 \end_layout
7488
7489 \end_inset
7490
7491 :
7492 \begin_inset Separator latexpar
7493 \end_inset
7494
7495
7496 \end_layout
7497
7498 \begin_deeper
7499 \begin_layout Standard
7500 A dynamic_cast is necessary when:
7501 \end_layout
7502
7503 \begin_layout Itemize
7504 the object to be casted is from an external library because we can't add
7505  Qxxx::asXxxx() to Qt e.g.:
7506 \begin_inset Separator latexpar
7507 \end_inset
7508
7509
7510 \end_layout
7511
7512 \begin_deeper
7513 \begin_layout Itemize
7514 QAbstractListModel to GuiIdListModel,
7515 \end_layout
7516
7517 \begin_layout Itemize
7518 QValidator to PathValidator,
7519 \end_layout
7520
7521 \begin_layout Itemize
7522 QWidget to TabWorkArea,
7523 \end_layout
7524
7525 \begin_layout Itemize
7526 QWidget to GuiWorkArea;
7527 \end_layout
7528
7529 \end_deeper
7530 \begin_layout Itemize
7531 the object is to be casted from an interface to the implementing class,
7532  because the Interface does not know by whom it is implemented:
7533 \begin_inset Separator latexpar
7534 \end_inset
7535
7536
7537 \end_layout
7538
7539 \begin_deeper
7540 \begin_layout Itemize
7541 ProgressInterface to GuiProgress,
7542 \end_layout
7543
7544 \begin_layout Itemize
7545 Application to GuiApplication.
7546 \end_layout
7547
7548 \end_deeper
7549 \begin_layout Standard
7550 A dynamic_cast can be replaced by:
7551 \end_layout
7552
7553 \begin_layout Itemize
7554 already existing as***Inset() functions, e.g.:
7555 \begin_inset Separator latexpar
7556 \end_inset
7557
7558
7559 \end_layout
7560
7561 \begin_deeper
7562 \begin_layout Itemize
7563 asHullInset(),
7564 \end_layout
7565
7566 \begin_layout Itemize
7567 asInsetMath()->asMacro(),
7568 \end_layout
7569
7570 \begin_layout Itemize
7571 asInsetText();
7572 \end_layout
7573
7574 \end_deeper
7575 \begin_layout Itemize
7576 A static_cast when we are sure this can't go wrong, e.g.:
7577 \begin_inset Separator latexpar
7578 \end_inset
7579
7580
7581 \end_layout
7582
7583 \begin_deeper
7584 \begin_layout Itemize
7585 we are sure that CellData::inset->clone() is an InsetTableCell,
7586 \end_layout
7587
7588 \begin_layout Itemize
7589 in cases where we explicitly check it->lyxCode().
7590 \end_layout
7591
7592 \end_deeper
7593 \end_deeper
7594 \end_deeper
7595 \begin_layout Bibliography
7596 \begin_inset CommandInset bibitem
7597 LatexCommand bibitem
7598 key "meyers"
7599 literal "true"
7600
7601 \end_inset
7602
7603 Meyers, Scott.
7604  Effective C++: 50 Specific Ways to Improve Your Programs and Design.
7605  Addison-Wesley, 1992.
7606 \end_layout
7607
7608 \begin_layout Bibliography
7609 \begin_inset CommandInset bibitem
7610 LatexCommand bibitem
7611 key "sutter"
7612 literal "true"
7613
7614 \end_inset
7615
7616 Sutter, Herb.
7617  Exceptional C++: 47 engineering puzzles, programming problems, and solutions.
7618  ISBN 0-201-61562-2.
7619 \end_layout
7620
7621 \begin_layout Bibliography
7622 \begin_inset CommandInset bibitem
7623 LatexCommand bibitem
7624 key "journal"
7625 literal "true"
7626
7627 \end_inset
7628
7629 Meyers, Scott.
7630  C/C++ User's Journal (Vol.18, No.2).
7631 \end_layout
7632
7633 \end_body
7634 \end_document