lib/doc/Development.lyx

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