lib/doc/Development.lyx

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