lib/doc/Development.lyx

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