lib/doc/Development.lyx

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