1 #LyX 2.4 created this file. For more info see https://www.lyx.org/
5 \save_transient_properties true
6 \origin /systemlyxdir/doc/
8 \options BCOR8mm,captions=tableheading
9 \use_default_options false
13 \maintain_unincluded_children no
15 \language_package default
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
27 \font_typewriter_osf false
28 \font_sf_scale 100 100
29 \font_tt_scale 100 100
31 \use_dash_ligatures true
33 \default_output_format pdf2
35 \bibtex_command default
36 \index_command default
37 \float_placement class
38 \float_alignment class
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"
47 \pdf_bookmarksnumbered true
48 \pdf_bookmarksopen true
49 \pdf_bookmarksopenlevel 1
54 \pdf_pdfusetitle false
55 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
58 \use_package amsmath 1
59 \use_package amssymb 1
62 \use_package mathdots 1
63 \use_package mathtools 1
65 \use_package stackrel 1
66 \use_package stmaryrd 1
67 \use_package undertilde 1
69 \cite_engine_type default
73 \paperorientation portrait
79 \notefontcolor #0000ff
86 \paragraph_separation indent
87 \paragraph_indentation default
89 \math_numbering_side default
94 \paperpagestyle headings
96 \tracking_changes false
99 \postpone_fragile_content false
103 \docbook_table_output 0
104 \docbook_mathml_prefix 1
110 Developing \SpecialChar LyX
114 \begin_layout Subtitle
119 by the \SpecialChar LyX
124 \begin_layout Plain Layout
125 If you have comments on or error corrections to this documentation, please
126 send them to the \SpecialChar LyX
127 Documentation mailing list:
128 \begin_inset CommandInset href
130 target "lyx-docs@lists.lyx.org"
144 \begin_layout Standard
145 \begin_inset CommandInset toc
146 LatexCommand tableofcontents
153 \begin_layout Chapter
157 \begin_layout Standard
158 This manual documents some aspects of \SpecialChar LyX
160 It is currently rather incomplete, but will hopefully be extended in the
162 Meanwhile, additional information can be found in the
163 \begin_inset Flex Code
166 \begin_layout Plain Layout
172 subfolder of the \SpecialChar LyX
173 source code distribution.
174 This document is not translated, since the development language of \SpecialChar LyX
177 If you just want to use \SpecialChar LyX
178 , then you don't need to read this manual.
179 However, if you want to learn more about how \SpecialChar LyX
180 is developed, or even want
181 to participate in \SpecialChar LyX
182 development, you may find some interesting information
186 \begin_layout Chapter
190 \begin_layout Standard
192 uses several custom file formats for configuration files and documents.
193 This chapter contains some background concerning these file formats.
194 Several file formats are also described in detail in the regular user documenta
198 \begin_layout Section
199 When is an update of the .lyx file format number needed?
200 \begin_inset CommandInset label
202 name "sec:When-is-an"
209 \begin_layout Standard
210 When you are working on a new feature you may ask yourself whether it needs
211 an update of the .lyx file format number.
212 Whether an update is needed or not is not always obvious.
217 Whenever there is the danger that a previous version of LyX cannot open
218 a file using the new feature, a file format update is needed.
221 \begin_layout Standard
222 The file format change allows lyx2lyx rules to implement backwards compatibility.
223 Below you can find a list of reasons for file format updates with explanations:
226 \begin_layout Description
235 setting Whenever you introduce a new setting that is stored in the document
236 header, a file format update is needed.
239 \begin_layout Description
248 setting If a certain setting becomes obsolete and gets removed, a file format
252 \begin_layout Description
278 \begin_inset space \thinspace{}
285 \begin_layout Description
286 \paragraph_spacing single
299 package The reason for this is that there is no true ERT inset for math
300 formulas: Each command is parsed, and if a user happens to define a local
301 command with the same name as a command that triggers an automatic load
302 of a package, they need to be able to switch off the automatic loading
304 This switch is stored by the
305 \begin_inset Flex Code
308 \begin_layout Plain Layout
317 \begin_layout Description
322 language that is stored in
323 \begin_inset Flex Code
326 \begin_layout Plain Layout
336 \begin_inset Note Note
339 \begin_layout Plain Layout
340 This requirement is under discussion.
349 \begin_layout Description
354 inset Of course a new inset requires a file format update.
357 \begin_layout Description
362 style If a new style or inset layout is added to any layout file or module
363 shipped with \SpecialChar LyX
364 , then a new file format is needed in the master (development)
366 It is possible to backport new styles to the stable version without a file
369 \begin_inset CommandInset ref
371 reference "subsec:Backporting-new-styles"
375 for more information.
378 \begin_layout Description
383 style If a style or inset layout is removed in any layout file or module
384 shipped with \SpecialChar LyX
385 , a new file format is required.
388 \begin_layout Standard
393 layouts and modules do
397 require a file format update (changed 03/16, see
398 \begin_inset CommandInset ref
400 reference "subsec:New-layouts"
408 \begin_layout Standard
409 If you are still unsure, please ask on the development list.
412 \begin_layout Section
413 \begin_inset CommandInset label
415 name "subsec:update_lyx_files"
419 How to update the file format number of .lyx files
422 \begin_layout Standard
423 Once you come to the conclusion that a file format update is needed, you
424 should use the following procedure to perform the update:
427 \begin_layout Enumerate
428 Implement and test the new feature, including the reading and writing of
430 Note that any file produced at this stage does not use a valid format,
431 so do not use this version of \SpecialChar LyX
432 for working on any important documents.
435 \begin_layout Enumerate
436 \begin_inset CommandInset label
438 name "enu:Describe_format"
442 Describe the new format in
443 \begin_inset Flex Code
446 \begin_layout Plain Layout
455 \begin_layout Enumerate
456 Update the \SpecialChar LyX
457 file format number in
458 \begin_inset Flex Code
461 \begin_layout Plain Layout
470 \begin_layout Enumerate
471 \begin_inset CommandInset label
473 name "enu:Add-an-entry"
477 Add an entry to both format lists (for conversion and reversion) in
478 \begin_inset Newline newline
482 \begin_inset Flex Code
485 \begin_layout Plain Layout
486 lib/lyx2lyx/lyx_2_4.py
492 Add a conversion routine if needed (e.
493 \begin_inset space \thinspace{}
496 g., a new header setting always needs a conversion that adds the new setting,
497 but a new document language does not need one).
498 Add a reversion routine if needed.
500 \begin_inset Newline newline
503 While the conversion routine is required to produce a document that is equivalen
504 t to the old version, the requirements of the reversion are not that strict.
505 If possible, try to produce a proper reversion, using ERT if needed, but
506 for some features this might be too complicated.
507 In this case, the minimum requirement of the reversion routine is that
508 it produces a valid document which can be read by an older \SpecialChar LyX
510 If absolutely needed, even data loss is allowed for the reversion.
511 (In that case, you might want to add a LyX comment that indicates what
512 you have had to do, so the user is at least warned).
515 \begin_layout Enumerate
516 Since tex2lyx has several implicit file format dependencies caused by sharing
517 code with \SpecialChar LyX
518 , updating the file format of .lyx files produced by tex2lyx at
519 the same time as updating the main .lyx file format is strongly recommended.
520 Therefore, a compiler warning will be issued if the \SpecialChar LyX
521 and tex2lyx .lyx file
522 format numbers differ.
523 In many cases the tex2lyx update requires only the first and last item
528 \begin_layout Enumerate
529 Update the tex2lyx file format number in
530 \begin_inset Flex Code
533 \begin_layout Plain Layout
542 \begin_layout Enumerate
543 If the lyx2lyx conversion from the old to the new format is empty, or if
544 tex2lyx does not yet output the changed feature, you do not need any further
546 Otherwise, search for the changed feature in tex2lyx, and adjust the output
547 according to the lyx2lyx changes.
550 \begin_layout Enumerate
551 Update the tex2lyx test references as described in
552 \begin_inset CommandInset ref
553 LatexCommand formatted
554 reference "sec:Updating-test-references"
562 \begin_layout Enumerate
563 If you did not implement full tex2lyx support for the new feature, add a
565 \begin_inset Flex Code
568 \begin_layout Plain Layout
574 describing the missing bits.
575 Note that it is perfectly fine if you do not add full tex2lyx support for
576 a new feature: The updating recommendation above is only issued for the
577 syntax of the produced .lyx file.
578 It is no problem if some features supported by \SpecialChar LyX
579 are still output as ERT
581 The problems in the past that resulted in the update recommendation were
582 related to mixed version syntax, not ERT.
585 \begin_layout Enumerate
586 It would be nice if you could create a .lyx test file which contains instances
587 of all changed or added features.
588 This could then be used to test lyx2lyx and tex2lyx.
589 Test samples are collected under the corresponding subdirectories of
596 \begin_layout Enumerate
597 \begin_inset CommandInset label
599 name "enu:updatefiles"
603 Test your lyx2lyx code by updating LyX's .lyx documentation files to the
605 The developer who makes the change knows best what changes to expect when
606 inspecting the resulting diff.
607 Because of this, you might be able to catch a bug in the lyx2lyx code that
608 updates the format just by taking a quick scan through the large diff that
610 \begin_inset Note Note
613 \begin_layout Plain Layout
614 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
615 see which layout update made an unexpected change by looking at the git
616 log of a .lyx file that suffers the problem.
621 To do this, first make sure that there are no changes to the git repository
622 that you will not want to commit (this is needed because it will be convenient
623 to commit with the command
624 \begin_inset Flex Code
627 \begin_layout Plain Layout
634 Then run the following command in the root folder of the source:
635 \begin_inset Flex Code
638 \begin_layout Plain Layout
639 python development/tools/updatedocs.py
645 Look at the resulting changes using the command
646 \begin_inset Flex Code
649 \begin_layout Plain Layout
656 If anything looks surprising, please investigate.
657 Keep in mind that the case of
658 \begin_inset Flex Code
661 \begin_layout Plain Layout
667 is special, because it is first generated with
668 \begin_inset Flex Code
671 \begin_layout Plain Layout
677 before being converted to the latest format.
678 \begin_inset Newline newline
682 \begin_inset Note Greyedout
685 \begin_layout Plain Layout
690 Only commit file format changes in the doc files if these files are using
691 the new feature of the new file format.
697 \begin_inset CommandInset ref
699 reference "enu:The-fileformat-of"
703 of the documentation policies described in sec.
708 \begin_inset CommandInset ref
710 reference "sec:Documentation-policies"
722 \begin_layout Enumerate
723 Finally, commit using
724 \begin_inset Flex Code
727 \begin_layout Plain Layout
736 \begin_layout Section
737 Updating the file format number of layout files
740 \begin_layout Standard
741 The procedure for updating the layout files is similar to that in step
742 \begin_inset CommandInset ref
744 reference "enu:updatefiles"
749 \begin_inset CommandInset ref
751 reference "subsec:update_lyx_files"
757 \begin_inset Flex Code
760 \begin_layout Plain Layout
761 python development/tools/updatelayouts.py
767 \begin_inset Flex Code
770 \begin_layout Plain Layout
779 \begin_layout Standard
780 Note that we do not automatically update any local layout used in the
781 \begin_inset Flex Code
784 \begin_layout Plain Layout
790 files shipped with \SpecialChar LyX
791 because users would then not be able to export to older
793 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
794 to open the file in \SpecialChar LyX
795 2.1.x, there would be an error because the file would
796 contain a local layout whose format is too new.
797 The root reason for this is that we do not support converting layouts to
798 older layout formats, as we do for the
799 \begin_inset Flex Code
802 \begin_layout Plain Layout
811 \begin_layout Section
812 Backporting new styles to the stable version
813 \begin_inset CommandInset label
815 name "subsec:Backporting-new-styles"
822 \begin_layout Standard
823 Starting with the stable \SpecialChar LyX
824 2.1 branch, there is a mechanism in place to backport
825 new styles to the stable version without the need to update the file format.
826 The basic idea is that the new style definition is automatically copied
827 to the document preamble so that it can even be used by older minor versions
828 that did not yet include the style.
829 To backport a new style to the stable version, the following steps are
833 \begin_layout Enumerate
835 \begin_inset Flex Code
838 \begin_layout Plain Layout
844 to the style definition in the development version.
847 \begin_layout Enumerate
848 Copy the style definition to the stable version, but use
849 \begin_inset Flex Code
852 \begin_layout Plain Layout
859 If needed adjust the format to the one used by the stable version (see
860 the customization manual for details of the layout file format).
863 \begin_layout Enumerate
864 For each update of the style in a later stable version, increase the argument
866 \begin_inset Flex Code
869 \begin_layout Plain Layout
876 (In the stable version, the development version should not be touched.)
879 \begin_layout Standard
880 For details about the
881 \begin_inset Flex Code
884 \begin_layout Plain Layout
890 flag see the customization manual.
892 \begin_inset Flex Code
895 \begin_layout Plain Layout
901 support is needed for backported styles: Since the style of the development
902 version has an infinite version number, it will always be used.
903 Furthermore, since its version number is less than one, the style will
904 not be written anymore to the document header for files saved by the new
908 \begin_layout Section
909 Updating the file format number of bind/ui files
912 \begin_layout Standard
913 A change to the functionality of existing LFUNs can require a conversion
915 \begin_inset Flex Code
918 \begin_layout Plain Layout
925 \begin_inset Flex Code
928 \begin_layout Plain Layout
934 files, and therefore an increment of the LFUN format, as well as a conversion
936 \begin_inset Flex Code
939 \begin_layout Plain Layout
946 The latter cannot be done automatically and also requires an update of
950 \begin_inset space \space{}
953 of someone who might have made a set of \SpecialChar LyX
954 teaching manuals for use in their
959 \begin_layout Plain Layout
960 \begin_inset Flex URL
963 \begin_layout Plain Layout
965 https://www.lyx.org/trac/ticket/9794
978 \begin_layout Standard
979 To update the LFUN format:
982 \begin_layout Enumerate
983 Increment the LFUN file format number in
984 \begin_inset Flex Code
987 \begin_layout Plain Layout
996 \begin_layout Enumerate
997 Implement the LFUN conversion in
998 \begin_inset Flex Code
1001 \begin_layout Plain Layout
1002 lib/scripts/prefs2prefs_lfuns.py
1010 \begin_layout Enumerate
1012 \begin_inset CommandInset ref
1014 reference "enu:updatefiles"
1019 \begin_inset CommandInset ref
1021 reference "subsec:update_lyx_files"
1026 \begin_inset Flex Code
1029 \begin_layout Plain Layout
1035 command, use this command:
1036 \begin_inset Flex Code
1039 \begin_layout Plain Layout
1040 bash development/tools/updatelfuns.sh
1047 \begin_inset Note Note
1050 \begin_layout Plain Layout
1051 This file should really be converted to python.
1059 \begin_layout Enumerate
1060 Update Info insets in
1061 \begin_inset Flex Code
1064 \begin_layout Plain Layout
1071 To do so, increment the \SpecialChar LyX
1072 format and proceed as in
1073 \begin_inset CommandInset ref
1075 reference "subsec:update_lyx_files"
1080 \begin_inset CommandInset ref
1082 reference "enu:Describe_format"
1087 \begin_inset CommandInset ref
1089 reference "enu:updatefiles"
1094 In the lyx2lyx implementation (step
1095 \begin_inset CommandInset ref
1097 reference "enu:Add-an-entry"
1101 ), implement a conversion similar to the one in
1102 \begin_inset Flex Code
1105 \begin_layout Plain Layout
1106 prefs2prefs_lfuns.py
1111 above, as well as a corresponding reversion; for this one can use
1112 \begin_inset Flex Code
1115 \begin_layout Plain Layout
1122 \begin_inset Flex Code
1125 \begin_layout Plain Layout
1126 lib/lyx2lyx/lyx2lyx_tools.py
1135 \begin_layout Chapter
1136 New layouts and modules
1139 \begin_layout Section
1140 \begin_inset CommandInset label
1142 name "subsec:New-layouts"
1149 \begin_layout Standard
1150 Adding a new layout file to the \SpecialChar LyX
1152 \begin_inset Quotes eld
1155 officially supported
1156 \begin_inset Quotes erd
1160 You should therefore think carefully about whether you really want to do
1161 this and discuss it on lyx-devel, since you will need to be prepared to
1162 update and fix the layout if necessary.
1163 If the layout is experimental or for a rarely used document class, then
1164 it may be better to add it to the relevant portion of the \SpecialChar LyX
1168 \begin_inset CommandInset href
1170 target "https://wiki.lyx.org/Layouts/Layouts"
1178 \begin_layout Standard
1179 In older versions of this document, it was stated that new layout files
1180 require a file format change.
1181 After some discussion, it was decided that this is not needed.
1185 \begin_layout Plain Layout
1187 \begin_inset CommandInset href
1189 name "the thread “Proposal for a guide on updating layouts”"
1190 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1204 For reference, here are the arguments on each side
1208 \begin_layout Description
1210 \begin_inset Quotes eld
1213 New layout files are a file format change
1214 \begin_inset Quotes erd
1220 \begin_layout Itemize
1221 All documents produced by 2.2.
1222 \begin_inset Formula $x$
1225 can always be edited and exported even if
1226 \begin_inset Formula $x$
1230 This is important for people using different machines, or exchanging work
1234 \begin_layout Description
1236 \begin_inset Quotes eld
1239 New layout files are not a file format change
1240 \begin_inset Quotes erd
1246 \begin_layout Itemize
1247 No new LaTeX classes can be supported in a stable version, and stable versions
1248 have a typical lifetime of 2–3 years.
1251 \begin_layout Itemize
1252 We have the same situation already with custom layout files: If a document
1253 using a custom layout file is moved between machines or people, then the
1254 layout file needs to be exchanged as well.
1255 If that is not done, then we have a fallback implemented so that such documents
1256 can still be edited, but not exported, and the user gets a warning.
1260 \begin_layout Itemize
1261 The lyx2lyx script cannot do anything useful in such a case.
1265 \begin_layout Standard
1266 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1268 then, you should do the following:
1271 \begin_layout Enumerate
1272 Put your new layout file in
1273 \begin_inset Flex Code
1276 \begin_layout Plain Layout
1283 \begin_inset Flex Code
1286 \begin_layout Plain Layout
1287 git add lib/layouts/newlayout.layout
1292 ) so that it will be committed.
1295 \begin_layout Enumerate
1297 \begin_inset Flex Code
1300 \begin_layout Plain Layout
1306 , so that the new layout actually gets installed.
1309 \begin_layout Enumerate
1311 \begin_inset Flex Code
1314 \begin_layout Plain Layout
1315 lib/doc/LaTeXConfig.lyx
1320 containing in particular a line like
1328 \begin_layout Standard
1329 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1330 \begin_inset Flex Code
1333 \begin_layout Plain Layout
1334 info-insert textclass <name>
1340 This inset will automatically display a boxed
1341 \begin_inset Quotes eld
1345 \begin_inset Quotes erd
1349 \begin_inset Quotes eld
1353 \begin_inset Quotes erd
1356 depending on the availability of the package.
1360 \begin_layout Enumerate
1361 A template or example is strongly encouraged (but not necessarily required).
1362 It is also possible to provide both.
1364 \begin_inset Flex Code
1367 \begin_layout Plain Layout
1374 \begin_inset Flex Code
1377 \begin_layout Plain Layout
1386 \begin_layout Enumerate
1387 Reconfigure \SpecialChar LyX
1391 \begin_layout Enumerate
1392 Ensure the autotests for the new layout pass (see
1393 \begin_inset CommandInset ref
1395 reference "par:when-to-run-an-export-test"
1402 \begin_layout Section
1406 \begin_layout Standard
1407 Adding a new module is very similar to adding a new layout.
1408 Therefore, the previous section applies to new modules as well, with two
1412 \begin_layout Enumerate
1413 You only need to add an entry to
1414 \begin_inset Flex Code
1417 \begin_layout Plain Layout
1418 lib/doc/LaTeXConfig.lyx
1423 if the module requires a LaTeX package.
1424 In that case, the command for entering the InsetInfo is:
1425 \begin_inset Flex Code
1428 \begin_layout Plain Layout
1429 info-insert package <name>
1437 \begin_layout Enumerate
1438 Modules do not need a template, only an example, which is strongly encouraged
1439 but not necessarily required.
1442 \begin_layout Section
1443 Layouts for document classes with incompatible versions
1446 \begin_layout Standard
1447 \begin_inset Note Greyedout
1450 \begin_layout Description
1451 Note: This section is currently only a proposal under discussion.
1452 Please correct/amend as suited.
1453 Remove this note once a consensus is found.
1456 \begin_layout Plain Layout
1458 \begin_inset Quotes eld
1461 Proposal for a guide on updating layouts
1462 \begin_inset Quotes erd
1465 for details and background
1468 \begin_layout Plain Layout
1469 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1477 \begin_layout Standard
1478 Every now and then, there are changes to LaTeX document classes that break
1479 backwards compatibility.
1483 \begin_layout Plain Layout
1484 Uwe has suggested we implement automatic detection of changes in class files.
1485 This could be done by running a script every month that checks if a document
1486 class was changed at CTAN and at the homepages of the scientific journals.
1487 If it reports a change, we can check if our template and layout file are
1488 still usable with the changed document class.
1489 (This is different from the autotests insofar, as this would also catch
1490 changes that do not result in compilation errors.)
1495 Reasons can be a new name for the
1496 \begin_inset Flex Code
1499 \begin_layout Plain Layout
1505 file, removed \SpecialChar LaTeX
1507 How should this best be handled in \SpecialChar LyX
1511 \begin_layout Standard
1512 The idea is to support the new version with a new \SpecialChar LyX
1516 \begin_layout Itemize
1517 Existing documents can still be opened in \SpecialChar LyX
1518 and will continue to work on
1519 systems where the old version is still installed.
1523 \begin_layout Itemize
1524 With differently named
1525 \begin_inset Flex Code
1528 \begin_layout Plain Layout
1534 files, \SpecialChar LyX
1535 can check for the availability of the particular version and reflect
1537 Different document class versions with the same file name are currently
1538 (2.2.x) not detected by the configuration script.
1539 This is planned for 2.3.
1543 \begin_layout Plain Layout
1544 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1547 \begin_layout Plain Layout
1548 However, what we really need is version detection for the configuration,
1549 so that the user can be warned if the required class file has the wrong
1551 (If the class file keeps the name over the version change, only one of
1552 the two layout files generates compilable documents.)
1555 \begin_layout Plain Layout
1556 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1565 \begin_layout Itemize
1566 The new layout can be added both to the master and the stable branches,
1567 in accord with the policy discussed in
1568 \begin_inset CommandInset ref
1569 LatexCommand formatted
1570 reference "subsec:New-layouts"
1575 No lyx2lyx conversion is then required when a new major version is released.
1578 \begin_layout Standard
1579 The user can move an existing document to the new version simply by selecting
1580 a new document class.
1581 This step is well supported by \SpecialChar LyX
1582 , with established methods for handling
1583 unsupported styles and other changes.
1584 This way, no lyx2lyx code is required.
1587 \begin_layout Standard
1588 The steps to support a new version of an existing document class are thus:
1591 \begin_layout Itemize
1592 Create a new layout file including the upstream version in the name (avoid
1593 special characters like spaces and dots), e.g.
1595 \begin_inset Flex Code
1598 \begin_layout Plain Layout
1599 acmsiggraph-v0-92.layout
1607 \begin_layout Itemize
1608 Include the name of the
1609 \begin_inset Flex Code
1612 \begin_layout Plain Layout
1618 file as an optional argument in the
1619 \begin_inset Flex Code
1622 \begin_layout Plain Layout
1630 line and include the version number in the GUI name:
1631 \begin_inset Newline newline
1635 \begin_inset Flex Code
1638 \begin_layout Plain Layout
1641 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1642 \begin_inset space ~
1653 \begin_layout Itemize
1654 Update the GUI name in the old layout file (whose name should not be changed),
1656 \begin_inset Newline newline
1660 \begin_inset Flex Code
1663 \begin_layout Plain Layout
1666 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1667 \begin_inset space ~
1678 \begin_layout Itemize
1679 To avoid duplicate definitions, the new layout can
1680 \begin_inset Flex Code
1683 \begin_layout Plain Layout
1689 the old layout file and add\SpecialChar breakableslash
1690 remove\SpecialChar breakableslash
1691 obsolete\SpecialChar breakableslash
1692 modify settings and styles (similar
1694 \begin_inset Flex Code
1697 \begin_layout Plain Layout
1707 \begin_layout Standard
1708 It may be tempting to let the new layout be the
1709 \begin_inset Quotes eld
1713 \begin_inset Quotes erd
1716 and have the old layout import it.
1717 However, this should not be done because any changes to the new layout
1718 would need undo steps in the importing old layout.
1722 \begin_layout Itemize
1723 If the new LaTeX document class obsoletes the old one, update the example
1724 and template files to use the new layout.
1725 Add a note about the changes (preferably with a pointer to the documentation
1730 \begin_layout Standard
1731 This way, new documents based on the template or example will use the up-to-date
1732 document class version.
1736 \begin_layout Standard
1737 \begin_inset Newpage newpage
1743 \begin_layout Chapter
1747 \begin_layout Standard
1748 Automated tests are an important tool to detect bugs and regressions in
1749 software development.
1750 Some projects like gcc even require each bug fix to be accompanied by a
1751 test case for the automatic test suite, that would detect this bug.
1752 Testing interactive features automatically is of course very hard, but
1753 core functionality like document import and export can be tested quite
1754 easily, and some tests of this kind exist.
1757 \begin_layout Section
1761 \begin_layout Standard
1762 There are attempts to set up a suite of unit tests for LyX.
1765 \begin_layout Standard
1766 TODO: describe what is done and what is still to do.
1769 \begin_layout Section
1773 \begin_layout Standard
1774 The tex2lyx tests are located in the
1775 \begin_inset Flex Code
1778 \begin_layout Plain Layout
1784 subfolder of the \SpecialChar LyX
1785 source code distribution.
1786 The actual testing is performed by the simple python script
1787 \begin_inset Flex Code
1790 \begin_layout Plain Layout
1791 src/tex2lyx/test/runtests.py
1797 Each test consists of two files:
1798 \begin_inset Flex Code
1801 \begin_layout Plain Layout
1807 contains the \SpecialChar LaTeX
1808 code that should be tested.
1810 \begin_inset Flex Code
1813 \begin_layout Plain Layout
1819 contains the expected output of tex2lyx.
1820 When a test is run, the actual produced output is compared with the stored
1822 The test passes if both are identical.
1823 The test machinery is also able to generate a file
1824 \begin_inset Flex Code
1827 \begin_layout Plain Layout
1833 by exporting the produced .lyx file with \SpecialChar LyX
1835 This may be useful for roundtrip comparisons.
1838 \begin_layout Subsection
1842 \begin_layout Standard
1843 The tex2lyx tests can be run in several ways.
1845 \begin_inset Flex Code
1848 \begin_layout Plain Layout
1854 subfolder of the build directory, the commands
1855 \begin_inset Flex Code
1858 \begin_layout Plain Layout
1864 (cmake, all platforms),
1865 \begin_inset Flex Code
1868 \begin_layout Plain Layout
1874 (cmake, when using a make based build system and not MSVC) or
1875 \begin_inset Flex Code
1878 \begin_layout Plain Layout
1884 (autotools) will run the tex2lyx tests.
1885 Alternatively, in the root of the build directory, the command
1886 \begin_inset Flex Code
1889 \begin_layout Plain Layout
1895 runs all tests whose names match the regex
1896 \begin_inset Quotes eld
1900 \begin_inset Quotes erd
1904 Another way to run the tex2lyx tests in the root build directory is to
1905 instead use the command
1906 \begin_inset Flex Code
1909 \begin_layout Plain Layout
1910 ctest -L '(cmplyx|roundtrip)'
1915 , which runs all tests categorized with the label
1916 \begin_inset Quotes eld
1920 \begin_inset Quotes erd
1924 \begin_inset Quotes eld
1928 \begin_inset Quotes erd
1932 If a test fails, the differences between the expected and actual results
1933 are output in unified diff format.
1936 \begin_layout Subsection
1937 Updating test references
1938 \begin_inset CommandInset label
1940 name "sec:Updating-test-references"
1947 \begin_layout Standard
1948 In some cases a changed tex2lyx output is not a test failure, but wanted,
1950 \begin_inset space \thinspace{}
1954 \begin_inset space \space{}
1957 if a tex2lyx bug was fixed, or a new feature was added.
1958 In these cases the stored references need to be updated.
1959 To do so if using autotools, call
1960 \begin_inset Flex Code
1963 \begin_layout Plain Layout
1970 \begin_inset Flex Code
1973 \begin_layout Plain Layout
1979 subdirectory of the build directory.
1980 If instead using CMake, call
1981 \begin_inset Flex Code
1984 \begin_layout Plain Layout
1985 make updatetex2lyxtests
1990 in the build directory or in the
1991 \begin_inset Flex Code
1994 \begin_layout Plain Layout
2000 subdirectory of the build directory.
2004 \begin_layout Plain Layout
2005 Note that this is a case where a make target in the build directory can
2006 affect the source directory, which might not be advisable.
2011 On Windows do the following:
2014 \begin_layout Itemize
2015 Assure that the path to the python.exe is in your system PATH variable.
2018 \begin_layout Itemize
2019 Double-click on the file
2020 \begin_inset Flex Code
2023 \begin_layout Plain Layout
2024 updatetex2lyxtests.vcxproj
2029 in the build directory or in the
2030 \begin_inset Flex Code
2033 \begin_layout Plain Layout
2039 subdirectory of your build directory.
2042 \begin_layout Itemize
2043 In the appearing MSVC program assure that you build the
2047 version, then right-click on the project
2051 in the project explorer and choose then
2054 \begin_inset space ~
2057 Only\SpecialChar menuseparator
2059 \begin_inset space ~
2067 \begin_layout Standard
2068 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2070 Please examine the changed output carefully before committing the changed
2071 files to the repository: Since the test machinery does not do a roundtrip
2073 \begin_inset Formula $\Rightarrow$
2077 \begin_inset Formula $\Rightarrow$
2080 .tex, and does not compare the produced dvi or pdf output, it assumes that
2081 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2083 There is only one chance to detect wrong output: before committing a new
2085 Once it is committed, it is quite difficult to verify whether it is correct.
2088 \begin_layout Standard
2093 update the test references by opening them with \SpecialChar LyX
2094 or directly running lyx2lyx
2096 This would not work, since lyx2lyx and \SpecialChar LyX
2097 produce slightly different files
2098 regarding insignificant whitespace and line breaks.
2101 \begin_layout Subsection
2105 \begin_layout Standard
2106 In many cases tests for new features may be added to one of the existing
2107 test files, but sometimes this is not possible or not wanted.
2108 Then a new test file needs to be added:
2111 \begin_layout Enumerate
2113 \begin_inset Flex Code
2116 \begin_layout Plain Layout
2117 src/tex2lyx/test/<test name>.tex
2122 and run tex2lyx in roundtrip mode to produce the file
2123 \begin_inset Flex Code
2126 \begin_layout Plain Layout
2127 src/tex2lyx/test/<test name>.lyx.lyx
2133 This file will be the new reference.
2136 \begin_layout Enumerate
2137 Once you confirmed that the tex2lyx output is correct, add the new files
2138 to the corresponding lists in
2139 \begin_inset Flex Code
2142 \begin_layout Plain Layout
2143 src/tex2lyx/test/runtests.py
2149 \begin_inset Flex Code
2152 \begin_layout Plain Layout
2153 src/tex2lyx/Makefile.am
2159 \begin_inset Flex Code
2162 \begin_layout Plain Layout
2163 src/tex2lyx/test/CMakeLists.txt
2171 \begin_layout Enumerate
2172 Commit the changes to the repository, or send a patch to the development
2173 list and ask for committing if you do not have commit rights.
2176 \begin_layout Section
2177 ctest automatic tests
2180 \begin_layout Standard
2181 Some tests are located in the
2182 \begin_inset Flex Code
2185 \begin_layout Plain Layout
2186 development/autotests/
2191 subfolder of the \SpecialChar LyX
2192 source code distribution.
2197 \begin_layout Plain Layout
2198 The README document in this folder only describes the
2199 \begin_inset Quotes eld
2203 \begin_inset Quotes erd
2206 subset of autotests!
2214 \begin_layout Standard
2215 These tests can be run by the commands
2216 \begin_inset Flex Code
2219 \begin_layout Plain Layout
2229 (all platforms) or (when using a make based build system and not MSVC)
2231 \begin_inset Flex Code
2234 \begin_layout Plain Layout
2241 \begin_inset Flex Code
2244 \begin_layout Plain Layout
2255 The test logs are written to the
2256 \begin_inset Flex Code
2259 \begin_layout Plain Layout
2273 \begin_layout Subsection
2277 \begin_layout Standard
2278 The export tests are integration tests.
2279 They take longer to run and are more likely to break than the tex2lyx tests.
2280 Nevertheless, they have caught many regressions and without a better alternativ
2281 e it is important to keep them up-to-date and understand how they work.
2284 \begin_layout Standard
2286 \begin_inset Quotes eld
2290 \begin_inset Quotes erd
2293 documentation, template, and example documents.
2294 In addition, there are a number of dedicated sample documents in the
2295 \begin_inset Flex Code
2298 \begin_layout Plain Layout
2304 subfolder of the \SpecialChar LyX
2305 source code distribution.
2306 All samples are (after copying and eventual processing by scripts) exported
2307 to various output formats via the
2308 \begin_inset Flex Code
2311 \begin_layout Plain Layout
2317 command line option.
2318 The tests checks for errors reported by LyX.
2319 (However, error-free export is no guarantee for an error-free output document.)
2322 \begin_layout Subsubsection
2323 \begin_inset CommandInset label
2325 name "par:when-to-run-an-export-test"
2329 Expectations of LyX developers
2332 \begin_layout Standard
2333 Because the export tests are integration tests and take a long time to run,
2334 LyX developers are rarely expected to run all of the tests.
2335 Here are some good practices to follow by developers:
2338 \begin_layout Itemize
2339 When making a non-trivial change to a .layout file, run the export and layout
2340 tests corresponding with that .layout file.
2343 \begin_layout Itemize
2344 When making non-trivial changes to a .lyx file, run the export tests correspondin
2345 g to that .lyx file.
2350 \begin_layout Plain Layout
2351 This rule is due to revision.
2355 \begin_layout Plain Layout
2356 There is an objection from the documentation maintainer that working on
2357 the documentation must not be complicated by having to consider non-standard
2361 \begin_layout Itemize
2362 successful compiling/testing an edited documentation file with pdflatex
2363 suffices to ensure it can be commited, not tests with other exports are
2367 \begin_layout Plain Layout
2368 If sudden failures with other exports due to “half-tested” documentation
2369 updates are a problem for the test maintainer, the test suite should use
2373 \begin_layout Itemize
2374 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2377 \begin_layout Itemize
2378 updated regularely (but on a time chosen by the test suite maintainer) from
2379 the originals in lib/doc/
2382 \begin_layout Plain Layout
2386 \begin_layout Itemize
2387 no test will fail due to ongoing work on documentation,
2390 \begin_layout Itemize
2391 the documentation is still tested in full (with some delay),
2394 \begin_layout Itemize
2395 failures with non-default export can be examined and handled accordingly
2396 in one run with the cache update,
2399 \begin_layout Itemize
2400 “interesting failures” (like the nested-language+polyglossia problem in
2401 es/Customization can be separated and moved into dedicated test samples.
2409 \begin_layout Itemize
2410 When making non-trivial changes to LyX's \SpecialChar LaTeX
2412 touching the encoding code or package handling code that you expect will
2413 change the exported \SpecialChar LaTeX
2418 \begin_layout Standard
2419 \paragraph_spacing single
2420 Consider running all of the export tests before and after your change.
2421 If there are differences, please reconcile these (i.e.
2422 fix the bug or fix the tests)
2427 Ask for help if you're not sure what to.
2430 \begin_layout Standard
2431 If you do not want to run the tests,
2434 \begin_layout Itemize
2435 post the patch on the list and others will run the tests and eventually
2439 \begin_layout Itemize
2440 commit, but be prepared to fix eventually arising problems or to revert
2441 the commit if there is no easy fix.
2445 \begin_layout Itemize
2446 Understand how to interpret test failures.
2447 If your commit is found to have broken a test, you should be able to interpret
2448 the test results when made aware of them.
2450 \begin_inset CommandInset ref
2452 reference "subsec:Interpreting-export-tests"
2459 \begin_layout Subsubsection
2460 \begin_inset CommandInset label
2462 name "par:export-test-output-formats"
2469 \begin_layout Standard
2470 The following output formats are currently tested for each sample document
2472 \begin_inset CommandInset ref
2474 reference "par:Export-test-filtering"
2481 \begin_layout Labeling
2482 \labelwidthstring 00.00.0000
2487 \begin_layout Labeling
2488 \labelwidthstring 00.00.0000
2489 lyx16 LyX 1.6 file format (lyx2lyx)
2492 \begin_layout Labeling
2493 \labelwidthstring 00.00.0000
2494 lyx21 LyX 2.1 file format (lyx2lyx)
2497 \begin_layout Labeling
2498 \labelwidthstring 00.00.0000
2499 xhtml LyXHTML (native LyX HTML export)
2503 \begin_layout Labeling
2504 \labelwidthstring 00.00.0000
2506 \begin_inset space ~
2510 \begin_inset space ~
2517 \begin_layout Labeling
2518 \labelwidthstring pdf5msystemFM
2519 dvi DVI (8-bit latex)
2522 \begin_layout Labeling
2523 \labelwidthstring pdf5msystemFM
2524 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2527 \begin_layout Labeling
2528 \labelwidthstring pdf5msystemFM
2529 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2532 \begin_layout Labeling
2533 \labelwidthstring pdf5msystemFM
2537 \begin_layout Labeling
2538 \labelwidthstring pdf5msystemFM
2539 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2542 \begin_layout Labeling
2543 \labelwidthstring pdf5msystemFM
2544 pdf4_systemF PDF (XeTeX with Unicode fonts)
2547 \begin_layout Labeling
2548 \labelwidthstring pdf5msystemFM
2549 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2552 \begin_layout Labeling
2553 \labelwidthstring pdf5msystemFM
2554 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2558 \begin_layout Labeling
2559 \labelwidthstring 00.00.0000
2561 \begin_inset space ~
2565 \begin_inset space ~
2569 \begin_inset space ~
2573 \begin_inset space ~
2580 \begin_layout Labeling
2581 \labelwidthstring pdf5msystemFM
2582 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2585 \begin_layout Labeling
2586 \labelwidthstring pdf5msystemFM
2587 pdf3 DVI -> PDF (dvipdfm)
2591 \begin_layout Labeling
2592 \labelwidthstring 00.00.0000
2594 \begin_inset space ~
2597 tested: (or only if set as default output format in the document source)
2601 \begin_layout Labeling
2602 \labelwidthstring pdf5msystemFM
2606 \begin_layout Labeling
2607 \labelwidthstring pdf5msystemFM
2608 luatex LaTeX (LuaTeX)
2611 \begin_layout Labeling
2612 \labelwidthstring pdf5msystemFM
2613 dviluatex LaTeX (dviluatex)
2616 \begin_layout Labeling
2617 \labelwidthstring pdf5msystemFM
2618 pdflatex LaTeX (pdflatex)
2621 \begin_layout Labeling
2622 \labelwidthstring pdf5msystemFM
2623 platex LaTeX (pLaTeX)
2626 \begin_layout Labeling
2627 \labelwidthstring pdf5msystemFM
2631 \begin_layout Labeling
2632 \labelwidthstring pdf5msystemFM
2633 eps3 EPS (encapsulated Postscript) (cropped)
2636 \begin_layout Labeling
2637 \labelwidthstring pdf5msystemFM
2638 ps DVI -> Postscript (dvips)
2641 \begin_layout Labeling
2642 \labelwidthstring pdf5msystemFM
2646 \begin_layout Labeling
2647 \labelwidthstring pdf5msystemFM
2648 text (nor text2, ..., text4)
2651 \begin_layout Labeling
2652 \labelwidthstring pdf5msystemFM
2656 \begin_layout Labeling
2657 \labelwidthstring pdf5msystemFM
2661 \begin_layout Labeling
2662 \labelwidthstring pdf5msystemFM
2666 \begin_layout Labeling
2667 \labelwidthstring pdf5msystemFM
2672 \begin_layout Subsubsection
2673 \begin_inset CommandInset label
2675 name "par:Configuring-ctests"
2679 Configuring the tests
2682 \begin_layout Standard
2683 To enable the export autotests, add the
2684 \begin_inset Flex Code
2687 \begin_layout Plain Layout
2688 -DLYX_ENABLE_EXPORT_TESTS=ON
2697 \begin_layout Standard
2698 \begin_inset Flex Code
2701 \begin_layout Plain Layout
2702 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2710 \begin_layout Standard
2712 This flag will increase the time for the cmake command by several seconds,
2713 mainly because of the process of inverting tests (see Section
2714 \begin_inset CommandInset ref
2716 reference "subsec:Interpreting-export-tests"
2723 \begin_layout Subsubsection
2724 \begin_inset CommandInset label
2726 name "par:ctest-options"
2733 \begin_layout Standard
2734 To run all tests, in the build directory simply run the command
2735 \begin_inset Flex Code
2738 \begin_layout Plain Layout
2745 A full, up-to-date TeXLive installation is recommended to run the tests.
2746 Otherwise, some tests will fail.
2747 Tests with additional requirements are labeled
2748 \begin_inset Quotes eld
2751 unreliable:nonstandard
2752 \begin_inset Quotes erd
2759 \begin_layout Standard
2760 To run only some of the tests, use command line options (see examples below):
2763 \begin_layout Labeling
2764 \labelwidthstring -R
2765 \begin_inset Flex Code
2768 \begin_layout Plain Layout
2774 Run only the tests whose names match the given regular expression.
2777 \begin_layout Labeling
2778 \labelwidthstring -R
2779 \begin_inset Flex Code
2782 \begin_layout Plain Layout
2788 Run only the tests whose labels match the given regular expression.
2789 A test may have more that one label.
2793 \begin_layout Labeling
2794 \labelwidthstring -R
2795 \begin_inset Flex Code
2798 \begin_layout Plain Layout
2804 Exclude the tests whose names match the given regular expression.
2807 \begin_layout Labeling
2808 \labelwidthstring -R
2809 \begin_inset Flex Code
2812 \begin_layout Plain Layout
2818 Exclude the tests whose labels match the given regular expression.
2819 Cannot be combined with
2820 \begin_inset Flex Code
2823 \begin_layout Plain Layout
2832 \begin_layout Standard
2833 The following options help to find good selection patterns:
2836 \begin_layout Labeling
2837 \labelwidthstring -R
2838 \begin_inset Flex Code
2841 \begin_layout Plain Layout
2847 List the tests that would be run but not actually run them.
2852 \begin_layout Standard
2853 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2854 to know how many tests there are or whether your
2855 \begin_inset Flex Code
2858 \begin_layout Plain Layout
2864 regular expression did what you expected.
2868 \begin_layout Labeling
2869 \labelwidthstring -R
2870 \begin_inset Flex Code
2873 \begin_layout Plain Layout
2874 \SpecialChar nobreakdash
2875 \SpecialChar nobreakdash
2881 print the list of all labels associated with the test set.
2882 Can also be combined with -R, -L, -E, ...
2886 \begin_layout Standard
2887 Other useful options are:
2890 \begin_layout Labeling
2891 \labelwidthstring -R
2892 \begin_inset Flex Code
2895 \begin_layout Plain Layout
2901 Run the tests in parallel using the given number of jobs.
2905 \begin_layout Standard
2906 We are still working on getting the tests to run in parallel.
2907 However, when running the tests in parallel, sometimes tests fail that
2908 pass when run sequentially.
2909 A reasonable approach is to first run the tests in parallel and then run
2910 the failed tests sequentially.
2913 \begin_layout Standard
2914 For example, to run 8 jobs at a time:
2917 \begin_layout Standard
2918 \begin_inset Flex Code
2921 \begin_layout Plain Layout
2930 \begin_layout Standard
2931 \begin_inset Flex Code
2934 \begin_layout Plain Layout
2935 ctest \SpecialChar nobreakdash
2936 \SpecialChar nobreakdash
2945 \begin_layout Standard
2946 When specifying a subset of the tests (e.g.
2948 \begin_inset Flex Code
2951 \begin_layout Plain Layout
2952 \SpecialChar nobreakdash
2958 ), the same subset must be specified when using the
2959 \begin_inset Flex Code
2962 \begin_layout Plain Layout
2963 \SpecialChar nobreakdash
2964 \SpecialChar nobreakdash
2970 option because it is the test numbers that are used to index which tests
2971 failed on the previous run.
2974 \begin_layout Standard
2976 Note that some tests cannot be run in parallel.
2977 These tests are marked in the code with the
2978 \begin_inset Flex Code
2981 \begin_layout Plain Layout
2991 \begin_layout Labeling
2992 \labelwidthstring -R
2993 \begin_inset Flex Code
2996 \begin_layout Plain Layout
2997 \SpecialChar nobreakdash
2998 \SpecialChar nobreakdash
3004 Set a global timeout on all tests that do not already have a timeout set
3009 \begin_layout Standard
3010 There have been bugs in LyX and in \SpecialChar LaTeX
3011 which cause compilation to hang, and
3012 without a timeout a test might never stop (in one case there was even a
3014 If a test times out, the
3015 \begin_inset Flex Code
3018 \begin_layout Plain Layout
3024 command exits with error, but you can distinguish between a timed out test
3025 and a failed test in the output reported at the end of the
3026 \begin_inset Flex Code
3029 \begin_layout Plain Layout
3039 \begin_layout Standard
3041 \begin_inset Flex Code
3044 \begin_layout Plain Layout
3050 ) the full list of command line options.
3053 \begin_layout Subsubsection
3057 \begin_layout Itemize
3058 run only the export tests:
3059 \begin_inset Flex Code
3062 \begin_layout Plain Layout
3071 \begin_layout Itemize
3073 \begin_inset Flex Code
3076 \begin_layout Plain Layout
3077 ctest -L "inverted|suspended"
3085 \begin_layout Itemize
3086 list all export tests which match any of the labelling patterns:
3087 \begin_inset Flex Code
3090 \begin_layout Plain Layout
3101 \begin_layout Itemize
3102 exclude rarely used output formats and post-processing tests
3103 \begin_inset Flex Code
3106 \begin_layout Plain Layout
3107 ctest -L export -E "_(texF|dvi3|pdf3?)"
3115 \begin_layout Subsubsection
3116 \begin_inset CommandInset label
3118 name "subsec:Interpreting-export-tests"
3122 Interpreting the export test results
3125 \begin_layout Standard
3126 A test can fail for several reasons, not all of them bad.
3129 \begin_layout Enumerate
3130 A new or edited sample document may be incompatible with some output formats.
3133 \begin_layout Enumerate
3134 A dependency is not met (e.g.
3135 the \SpecialChar LaTeX
3137 One hint that this is the case is that the corresponding
3138 \begin_inset Flex Code
3141 \begin_layout Plain Layout
3147 test will likely also fail.
3150 \begin_layout Enumerate
3151 An inverted test fails to fail (i.e.
3152 export that previously failed now works).
3155 \begin_layout Enumerate
3156 An external dependency was updated (e.g.
3161 \begin_layout Enumerate
3162 A recent code change introduced a bug.
3165 \begin_layout Enumerate
3166 \begin_inset CommandInset label
3172 A change in a document exposed a previously unknown bug or an incompatibility
3173 with an export format (e.g.
3174 Lua\SpecialChar LaTeX
3178 \begin_layout Standard
3179 Because the .lyx files are exported in several formats, it is not surprising
3180 that many of the exports fail.
3181 This expectation of failure is addressed by
3182 \begin_inset Quotes eld
3186 \begin_inset Quotes erd
3189 the tests, that is, by marking the test as
3190 \begin_inset Quotes eld
3194 \begin_inset Quotes erd
3197 if the export exits with error and as
3198 \begin_inset Quotes eld
3202 \begin_inset Quotes erd
3205 if the export succeeds
3210 It follows that these expected failures will not show up as failed tests
3211 in the test results and thus will not pollute the
3212 \begin_inset Quotes eld
3216 \begin_inset Quotes erd
3220 If the export actually succeeds, then the test will fail.
3221 The purpose of this failure is to get your attention—something has changed,
3222 possibly for the better.
3225 \begin_layout Standard
3226 We try to document why a test is inverted or ignored.
3227 See the comment (prefixed with
3228 \begin_inset Flex Code
3231 \begin_layout Plain Layout
3237 ) above the block in which the test is listed as inverted or ignored in
3239 \begin_inset Flex Code
3242 \begin_layout Plain Layout
3243 development/autotests/invertedTests
3249 \begin_inset Flex Code
3252 \begin_layout Plain Layout
3253 development/autotests/unreliableTests
3259 \begin_inset Flex Code
3262 \begin_layout Plain Layout
3263 development/autotests/ignoredTests
3272 \begin_layout Standard
3273 A good question is why do we enable the tests for non-default formats? The
3274 answer is that if a non-default route is broken it is often because a bug
3275 was introduced in LyX and not because a document-specific change was made
3276 that is not supported by the route.
3277 In other words, there is a high signal/noise ratio in the export tests
3278 for some non-default formats.
3282 \begin_layout Standard
3283 When a test or several tests fail, consider checking the files in the
3284 \begin_inset Flex Code
3287 \begin_layout Plain Layout
3293 subdirectory of your build directory.
3294 In this subdirectory are three files: the file
3295 \begin_inset Flex Code
3298 \begin_layout Plain Layout
3304 simply lists the tests that failed on your last
3305 \begin_inset Flex Code
3308 \begin_layout Plain Layout
3315 \begin_inset Flex Code
3318 \begin_layout Plain Layout
3324 file contains the output from the tests (and often has details explaining
3325 why a test failed); and the
3326 \begin_inset Flex Code
3329 \begin_layout Plain Layout
3335 file lists the times that it took to run the tests.
3338 \begin_layout Subsubsection
3339 What action should you take if a test fails?
3342 \begin_layout Standard
3343 \paragraph_spacing single
3344 It is always good to check manually why something fails and if it passes
3345 if the PDF output is good.
3348 \begin_layout Itemize
3349 Generally, if a change breaks compilation for the target format (for the
3350 manuals pdf2) without solving some important other issue,
3352 fix or revert the commit
3354 that led to failure.
3357 \begin_layout Itemize
3358 If it is not possible to (immediately) fix the failure but there are reasons
3359 not to revert the commit (e.g.
3360 it fixes another more important issue),
3364 the failing test case (see
3365 \begin_inset CommandInset ref
3367 reference "par:Inverted-tests"
3374 \begin_layout Itemize
3379 test case fails because the export now works, first confirm that the output
3380 of the corresponding export looks good (e.g., not garbled text).
3385 the test by removing the pattern from the
3386 \begin_inset Quotes eld
3390 \begin_inset Quotes erd
3394 \begin_inset CommandInset ref
3396 reference "par:Inverted-tests"
3403 \begin_layout Itemize
3404 If the export did not fail previously but led to wrong output (PDF, say),
3408 \begin_layout Plain Layout
3409 Non-failing test with wrong output should be labeled as
3410 \begin_inset Quotes eld
3413 unreliable:wrong_output
3414 \begin_inset Quotes erd
3418 \begin_inset CommandInset ref
3420 reference "par:Unreliable-tests"
3429 it is in fact an improvement when the test now fails.
3434 the failing test case (see
3435 \begin_inset CommandInset ref
3437 reference "par:Inverted-tests"
3444 \begin_layout Itemize
3445 In case of tests failing due to missing requirements (tests labeled
3446 \begin_inset Quotes eld
3449 unreliable:nonstandard
3450 \begin_inset Quotes erd
3453 or testing on a system with only a subset of TeXLive installed), ignore
3454 the failure, ask for someone else to run the test, or install the missing
3455 resources and try again.
3458 \begin_layout Itemize
3459 Check the log file Testing/Temporary/LastTest.log.
3460 In case of latex-errors rerun the failing test with environment variable
3461 'LYX_DEBUG_LATEX' set to '1'.
3462 This will include latex messages in LastTest.log, so it should be easier
3463 to interpret the fail-reason.
3466 \begin_layout Subsubsection
3467 \begin_inset CommandInset label
3469 name "par:Inverted-tests"
3476 \begin_layout Standard
3477 Test cases whose name matches a pattern in the file
3478 \begin_inset Flex Code
3481 \begin_layout Plain Layout
3482 development/autotests/invertedTests
3492 They get also the test property
3493 \begin_inset Flex Code
3496 \begin_layout Plain Layout
3503 they are reported as failing if the export works without error
3504 \begin_inset Flex URL
3507 \begin_layout Plain Layout
3509 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3517 \begin_layout Standard
3518 Add failing cases to this file, if they cannot be solved
3519 \begin_inset Quotes eld
3523 \begin_inset Quotes erd
3526 but it is expected that the export will work in a foreseeable future, e.g.
3527 low priority issues like failures to export to a non-target format (for
3528 the manuals everything except pdf2).
3531 \begin_layout Standard
3532 The following sublabels are currently present in
3533 \begin_inset Flex Code
3536 \begin_layout Plain Layout
3545 \begin_layout Description
3546 todo test failures that require attention:
3550 \begin_layout Itemize
3551 minor issues to explore and properly sort later,
3554 \begin_layout Itemize
3558 \begin_layout Itemize
3559 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3563 \begin_layout Description
3564 lyxbugs LyX bugs with a Trac number.
3567 \begin_layout Description
3568 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3572 \begin_layout Standard
3573 "Wontfix" if demonstrating correct use and OK in the default output format.
3577 \begin_layout Description
3578 texissues Export fails due to LaTeX limitations like non-ASCII characters
3579 in verbatim or listings, incompatible packages, ...
3583 \begin_layout Standard
3584 "Wontfix" if documents demonstrate correct use in the default output format:
3587 \begin_layout Itemize
3588 If the source can be made more robust without becoming "hackish", fix the
3592 \begin_layout Itemize
3593 if LyX could be enhanced to care for a permanent TeX limitation, file a
3594 ticket at trac and add a pattern under lyxbugs,
3597 \begin_layout Itemize
3598 otherwise, add a pattern here.
3602 \begin_layout Description
3603 attic Documents in the attic (kept for reference and format conversion test).
3605 \begin_inset Quotes eld
3609 \begin_inset Quotes erd
3615 \begin_layout Paragraph
3619 \begin_layout Standard
3620 Test cases whose name additionally matches a pattern in the file
3621 \begin_inset Flex Code
3624 \begin_layout Plain Layout
3625 development/autotests/suspendedTests
3643 This means they are not executed using
3644 \begin_inset Flex Code
3647 \begin_layout Plain Layout
3654 \begin_inset Flex Code
3657 \begin_layout Plain Layout
3664 However, they also get the test property
3665 \begin_inset Flex Code
3668 \begin_layout Plain Layout
3675 they are reported as failing if the export works without error.
3676 From time to time they still have to be checked using
3677 \begin_inset Flex Code
3680 \begin_layout Plain Layout
3689 \begin_layout Standard
3690 These tests are suspended, because the export fails for known reasons which
3691 cannot ATM be resolved.
3692 But it is expected the reason might disappear in the future.
3693 Be it new TL or better handling in \SpecialChar LyX
3697 \begin_layout Standard
3698 For ctest commands without the
3699 \begin_inset Flex Code
3702 \begin_layout Plain Layout
3708 parameter nothing changes.
3709 Suspended or not, tests will be executed depending only on the selecting
3710 regular expression given to the ctest command (see
3711 \begin_inset CommandInset ref
3713 reference "par:ctest-options"
3720 \begin_layout Subsubsection
3721 \begin_inset CommandInset label
3723 name "par:Unreliable-tests"
3730 \begin_layout Standard
3731 Test cases whose name matches a pattern in the file
3732 \begin_inset Flex Code
3735 \begin_layout Plain Layout
3736 development/autotests/unreliableTests
3748 \begin_layout Standard
3749 These tests are not executed using
3750 \begin_inset Flex Code
3753 \begin_layout Plain Layout
3760 \begin_inset Flex Code
3763 \begin_layout Plain Layout
3773 \begin_layout Standard
3774 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3775 or pass but should rather fail (wrong output).
3777 \begin_inset Note Note
3780 \begin_layout Plain Layout
3781 *invalid* tests (wrong output) are not *unreliable*.
3782 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3791 \begin_layout Standard
3792 The following sublabels are currently present in
3793 \begin_inset Flex Code
3796 \begin_layout Plain Layout
3805 \begin_layout Description
3806 nonstandard Documents with additional requirements, e.g.
3807 a class or package file not in TeXLive.
3809 \begin_inset Note Note
3812 \begin_layout Plain Layout
3814 \begin_inset Quotes eld
3818 \begin_inset Quotes erd
3822 \begin_inset Quotes eld
3826 \begin_inset Quotes erd
3837 \begin_layout Description
3838 erratic Tests depending on local configuration or the phase of the moon.
3842 \begin_layout Description
3843 varying_versions Tests depending on e.g.
3844 OS or version of a non-TeX-Live dependency.
3845 Note that a full, up-to-date TeX Live installation is required so this
3846 sublabel is about versions of other dependencies.
3849 \begin_layout Description
3851 \begin_inset space ~
3854 output Export does not fail but the resulting document has (undetected)
3859 \begin_layout Standard
3860 \paragraph_spacing single
3861 \begin_inset Note Note
3864 \begin_layout Plain Layout
3865 \paragraph_spacing single
3866 These tests are in a strict sense not unreliable but
3870 (not measuring what they should measure).
3879 \begin_layout Subsubsection
3880 \begin_inset CommandInset label
3882 name "par:Export-test-filtering"
3886 Export test filtering
3889 \begin_layout Standard
3890 The assignment of a label to a test is controlled by a set of files with
3891 regular expressions that are matched against the test names.
3894 \begin_layout Description
3895 ignoredTests (small file)
3896 \begin_inset Newline newline
3899 Tests selected here are withdrawn in the configuration step (cf.
3901 \begin_inset CommandInset ref
3903 reference "par:Configuring-ctests"
3911 \begin_layout Labeling
3912 \labelwidthstring 00.00.0000
3913 Input Test of any export combination
3916 \begin_layout Labeling
3917 \labelwidthstring 00.00.0000
3918 Output Stop if tests not selected here
3922 \begin_layout Description
3923 unreliableTests: Tests selected pass or fail dependent on the system where
3925 Selected tests gain the label 'unreliable'.
3929 \begin_layout Labeling
3930 \labelwidthstring 00.00.0000
3931 Input Each test which passed 'ignoredTests'
3934 \begin_layout Labeling
3935 \labelwidthstring 00.00.0000
3936 Output Gain label 'unreliable', proceed with checking for 'inverted'.
3940 \begin_layout Description
3942 \begin_inset space \space{}
3949 \begin_layout Labeling
3950 \labelwidthstring 00.00.0000
3951 Input Each test which passed 'ignoredTests'
3954 \begin_layout Labeling
3955 \labelwidthstring 00.00.0000
3956 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3957 tests are reported as failing if the export works without error.) If no
3958 subselection applies, gain labels 'export' and 'inverted'.
3961 \begin_layout Standard
3962 The following filter perfoms a subselection of 'invertedTests':
3965 \begin_layout Description
3966 suspendedTests Tests selected here gain the label 'suspended' but _not_
3967 'export' or 'inverted', although in ctest they remain inverted.
3968 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3972 \begin_layout Labeling
3973 \labelwidthstring 00.00.0000
3974 Input Each test selected by 'invertedTests'
3977 \begin_layout Labeling
3978 \labelwidthstring 00.00.0000
3979 Output Selected test gains label 'suspended'.
3985 \begin_layout Standard
3986 The following table may clarify label assignement
3989 \begin_layout Standard
3990 \begin_inset space \hspace{}
3995 \begin_inset Tabular
3996 <lyxtabular version="3" rows="6" columns="8">
3997 <features tabularvalignment="middle">
3998 <column alignment="left" valignment="top" width="2cm">
3999 <column alignment="left" valignment="top" width="2.5cm">
4000 <column alignment="left" valignment="top" width="2cm">
4001 <column alignment="center" valignment="top" width="2.5cm">
4002 <column alignment="center" valignment="top">
4003 <column alignment="center" valignment="top">
4004 <column alignment="center" valignment="top">
4005 <column alignment="center" valignment="top">
4007 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4010 \begin_layout Plain Layout
4011 Test matching pattern in file:
4016 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4019 \begin_layout Plain Layout
4025 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4028 \begin_layout Plain Layout
4034 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4037 \begin_layout Plain Layout
4043 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4046 \begin_layout Plain Layout
4052 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4055 \begin_layout Plain Layout
4061 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4064 \begin_layout Plain Layout
4070 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4073 \begin_layout Plain Layout
4081 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4084 \begin_layout Plain Layout
4085 ignored\SpecialChar softhyphen
4091 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4094 \begin_layout Plain Layout
4095 unreliable\SpecialChar softhyphen
4101 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4104 \begin_layout Plain Layout
4105 inverted\SpecialChar softhyphen
4111 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4114 \begin_layout Plain Layout
4115 suspended\SpecialChar softhyphen
4121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4124 \begin_layout Plain Layout
4130 <cell alignment="center" valignment="top" topline="true" usebox="none">
4133 \begin_layout Plain Layout
4139 <cell alignment="center" valignment="top" topline="true" usebox="none">
4142 \begin_layout Plain Layout
4148 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4151 \begin_layout Plain Layout
4159 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4162 \begin_layout Plain Layout
4168 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4171 \begin_layout Plain Layout
4177 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4180 \begin_layout Plain Layout
4186 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4189 \begin_layout Plain Layout
4195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4198 \begin_layout Plain Layout
4204 <cell alignment="center" valignment="top" topline="true" usebox="none">
4207 \begin_layout Plain Layout
4213 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4216 \begin_layout Plain Layout
4222 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4225 \begin_layout Plain Layout
4233 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4236 \begin_layout Plain Layout
4242 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4245 \begin_layout Plain Layout
4247 \begin_inset Newline newline
4251 \begin_inset Newline newline
4259 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4262 \begin_layout Plain Layout
4268 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4271 \begin_layout Plain Layout
4277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4280 \begin_layout Plain Layout
4286 <cell alignment="center" valignment="top" topline="true" usebox="none">
4289 \begin_layout Plain Layout
4295 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4298 \begin_layout Plain Layout
4304 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4307 \begin_layout Plain Layout
4315 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4318 \begin_layout Plain Layout
4324 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4327 \begin_layout Plain Layout
4333 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4336 \begin_layout Plain Layout
4342 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4345 \begin_layout Plain Layout
4351 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4354 \begin_layout Plain Layout
4360 <cell alignment="center" valignment="top" topline="true" usebox="none">
4363 \begin_layout Plain Layout
4369 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4372 \begin_layout Plain Layout
4378 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4381 \begin_layout Plain Layout
4389 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4392 \begin_layout Plain Layout
4398 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4401 \begin_layout Plain Layout
4407 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4410 \begin_layout Plain Layout
4416 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4419 \begin_layout Plain Layout
4425 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4428 \begin_layout Plain Layout
4434 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4437 \begin_layout Plain Layout
4443 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4446 \begin_layout Plain Layout
4452 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4455 \begin_layout Plain Layout
4469 \begin_layout Standard
4470 \begin_inset Note Note
4473 \begin_layout Plain Layout
4475 \begin_inset Quotes eld
4479 \begin_inset Quotes erd
4482 filter, this would be far less complicated:
4485 \begin_layout Plain Layout
4486 \begin_inset Tabular
4487 <lyxtabular version="3" rows="6" columns="7">
4488 <features tabularvalignment="middle">
4489 <column alignment="left" valignment="top" width="0pt">
4490 <column alignment="left" valignment="top" width="0pt">
4491 <column alignment="left" valignment="top" width="0pt">
4492 <column alignment="center" valignment="top">
4493 <column alignment="center" valignment="top">
4494 <column alignment="center" valignment="top">
4495 <column alignment="center" valignment="top">
4497 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4500 \begin_layout Plain Layout
4501 Test matching pattern in file:
4506 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4509 \begin_layout Plain Layout
4515 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4518 \begin_layout Plain Layout
4524 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4527 \begin_layout Plain Layout
4533 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4536 \begin_layout Plain Layout
4542 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4545 \begin_layout Plain Layout
4551 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4554 \begin_layout Plain Layout
4562 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4565 \begin_layout Plain Layout
4571 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4574 \begin_layout Plain Layout
4580 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4583 \begin_layout Plain Layout
4589 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4592 \begin_layout Plain Layout
4598 <cell alignment="center" valignment="top" topline="true" usebox="none">
4601 \begin_layout Plain Layout
4607 <cell alignment="center" valignment="top" topline="true" usebox="none">
4610 \begin_layout Plain Layout
4616 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4619 \begin_layout Plain Layout
4627 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4630 \begin_layout Plain Layout
4636 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4639 \begin_layout Plain Layout
4645 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4648 \begin_layout Plain Layout
4654 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4657 \begin_layout Plain Layout
4663 <cell alignment="center" valignment="top" topline="true" usebox="none">
4666 \begin_layout Plain Layout
4672 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4675 \begin_layout Plain Layout
4681 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4684 \begin_layout Plain Layout
4692 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4695 \begin_layout Plain Layout
4701 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4704 \begin_layout Plain Layout
4710 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4713 \begin_layout Plain Layout
4719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4722 \begin_layout Plain Layout
4728 <cell alignment="center" valignment="top" topline="true" usebox="none">
4731 \begin_layout Plain Layout
4737 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4740 \begin_layout Plain Layout
4746 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4749 \begin_layout Plain Layout
4757 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4760 \begin_layout Plain Layout
4766 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4769 \begin_layout Plain Layout
4775 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4778 \begin_layout Plain Layout
4784 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4787 \begin_layout Plain Layout
4793 <cell alignment="center" valignment="top" topline="true" usebox="none">
4796 \begin_layout Plain Layout
4802 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4805 \begin_layout Plain Layout
4811 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4814 \begin_layout Plain Layout
4822 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4825 \begin_layout Plain Layout
4831 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4834 \begin_layout Plain Layout
4840 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4843 \begin_layout Plain Layout
4849 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4852 \begin_layout Plain Layout
4858 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4861 \begin_layout Plain Layout
4867 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4870 \begin_layout Plain Layout
4876 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4879 \begin_layout Plain Layout
4898 \begin_layout Subsection
4902 \begin_layout Standard
4903 These tests check whether a .lyx file loads without any terminal messages.
4904 They correspond to the manual operations of simply opening a .lyx file on
4905 the terminal, exiting LyX once the file is loaded, and then checking whether
4906 there is any output from the terminal.
4907 These tests are useful for catching malformed .lyx files and parsing bugs.
4908 They can also be used to find a .lyx file in which an instance of something
4910 To do this, compile LyX with a local patch that outputs something to the
4911 terminal when an instance is found, and then run the check_load tests to
4912 see if any fail, which would mean that the situation occurs in the LyX
4913 documentation files corresponding to the failed tests.
4914 These tests are expectedly fragile: any LyX diagnostic message, which is
4915 not necessarily an error, would cause the tests to fail.
4916 Similarly, any message output by a library (e.g.
4917 Qt) would also cause failure.
4918 There are some messages that the check_load tests are instructed to ignore,
4919 which are stored in the file
4920 \begin_inset Flex Code
4923 \begin_layout Plain Layout
4924 development/autotests/filterCheckWarnings
4932 \begin_layout Standard
4933 Under cmake, the tests are labeled as 'load'.
4936 \begin_layout Subsection
4940 \begin_layout Standard
4941 Automated tests based on the "MonKey Testing" keytest program are enabled
4942 if the necessary dependencies are found and if the CMake flag
4943 \begin_inset Flex Code
4946 \begin_layout Plain Layout
4947 -DLYX_ENABLE_KEYTESTS=ON
4953 They are documented in the README document in
4954 \begin_inset Flex Code
4957 \begin_layout Plain Layout
4958 development/autotests
4963 subfolder of the \SpecialChar LyX
4964 source code distribution.
4967 \begin_layout Subsection
4971 \begin_layout Standard
4972 These tests combine lyx2lyx tests with check_load tests.
4973 They fail if either fails.
4976 \begin_layout Subsection
4980 \begin_layout Standard
4981 The URL tests are enabled with the
4982 \begin_inset Flex Code
4985 \begin_layout Plain Layout
4986 -DLYX_ENABLE_URLTESTS=ON
4991 CMake flag and are useful for finding broken links in our documentation
4993 If a URL test fails, to see which link in particular was reported as broken,
4995 \begin_inset Flex Code
4998 \begin_layout Plain Layout
5005 These tests are extremely fragile (e.g.
5006 a test can depend on your Internet connection) and a failed URL test should
5007 not be taken too seriously.
5008 URL tests are labeled as
5013 \begin_layout Subsubsection
5017 \begin_layout Standard
5018 cmake is required to run the \SpecialChar LyX
5019 tests, running them is not implemented for
5023 \begin_layout Standard
5024 The appropriate commands are:
5027 \begin_layout Itemize
5033 \begin_inset Newline newline
5036 runs all tests with label
5041 \begin_layout Itemize
5044 ctest -R 'check_.*urls'
5047 \begin_inset Newline newline
5050 runs the tests 'check_accessible_urls'
5053 \begin_layout Standard
5054 Associated test results can be examined in ctest-log directory in files
5055 of the form 'LastFailed.*URLS.log'
5058 \begin_layout Chapter
5059 Development policies
5062 \begin_layout Standard
5063 This chapter lists some guidelines that should be followed.
5064 This list is not complete, and many guidelines are in separate chapters,
5066 \begin_inset Quotes eld
5069 When is an update of the .lyx file format number needed?
5070 \begin_inset Quotes erd
5074 \begin_inset CommandInset ref
5076 reference "sec:When-is-an"
5083 \begin_layout Section
5084 When to set a fixed milestone?
5087 \begin_layout Standard
5088 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5092 \begin_layout Enumerate
5093 Somebody is actively working on a fix.
5096 \begin_layout Enumerate
5097 The bug is so severe that it would block the release if it is not fixed.
5100 \begin_layout Standard
5101 If a bug is important, but nobody is working on it, and it is no showstopper,
5102 use a milestone like 2.1.x or 2.2.x.
5103 For all other bugs, do not set a milestone at all.
5106 \begin_layout Section
5107 Can we add rc entries in stable branch?
5110 \begin_layout Standard
5112 We are supposed to increase the prefs2prefs version number with such things.
5115 \begin_layout Chapter
5116 \begin_inset CommandInset label
5118 name "sec:Documentation-policies"
5122 Documentation policies
5125 \begin_layout Section
5129 \begin_layout Standard
5131 \begin_inset space ~
5134 rules in editing the docs:
5137 \begin_layout Enumerate
5138 \begin_inset CommandInset label
5140 name "enu:If-you-are"
5144 If you are not the maintainer of a doc file or a chapter/section, you MUST
5145 use change tracking so that the maintainer could review your changes
5148 \begin_layout Enumerate
5149 Respect the formatting of the document.
5150 The different files use different formatting styles.
5151 That is OK and has historic reasons nobody fully knows ;-).
5152 But it is important to be consistent within one file.
5155 \begin_layout Enumerate
5156 All changes you make to a file in one language MUST also go the file in
5157 the other actively maintained languages.
5158 Normally the maintainer does this for you, if you are the maintainer, you
5159 must do this by copying or changing the changed or added text to the other
5160 files so that the translators sees the blue underlined text and know what
5161 they have to translate and what was changed.
5164 \begin_layout Enumerate
5165 You MUST assure that the document is compilable as
5166 \begin_inset Quotes eld
5170 \begin_inset Quotes erd
5173 or the document's default output format after your changes.
5176 \begin_layout Enumerate
5177 All fixes (typos, compilation fixes, updates info etc.) go at first into
5178 the current Git branch because the user should benefit from all fixes with
5179 every minor release.
5180 Feel free to commit directly to branch as long as you follow rule
5181 \begin_inset space ~
5185 \begin_inset CommandInset ref
5187 reference "enu:If-you-are"
5192 You can immediately commit to master as well.
5195 \begin_layout Enumerate
5196 \begin_inset CommandInset label
5198 name "enu:The-fileformat-of"
5202 The fileformat of a file must not be changed unless you document a new feature
5203 in LyX that requires a new fileformat.
5204 The reason for this rule is to keep it easy for the doc maintainers to
5205 port/backport changes to from master/branch.
5208 \begin_layout Standard
5209 The main documentation consists of these files:
5212 \begin_layout Description
5213 Welcome.lyx It is the first file you see after an installation.
5214 We assume that a new user sees this.
5215 It is therefore designed to be as simple as possible.
5216 Therefore please don't add any new formatting, only fix typos etc.
5219 \begin_layout Description
5220 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5222 It therefore uses a limited set of formatting.
5223 For example a standard document class.
5224 Since new users will first learn about the formatting possibilities of
5226 please keep this file that simple.
5229 \begin_layout Description
5230 Tutorial.lyx Our tutorial.
5231 It must be always up to date.
5232 Normally there is nothing to add since we don't want to overwhelm new users
5233 with too much details.
5234 They will learn these details while using \SpecialChar LyX
5235 and we have special manuals.
5238 \begin_layout Description
5239 UserGuide.lyx Our main user guide.
5240 It covers a mixture of basic and detailed information.
5241 Some information is also in the Math and EmbeddedObjects manual so that
5242 the UserGuide refers to these files.
5245 \begin_layout Description
5246 EmbeddedObjects.lyx A special manual to explain things like tables floats
5251 \begin_layout Description
5252 Math.lyx A special manual to explain everything regarding math in all detail.
5255 \begin_layout Description
5256 Additional.lyx This manual covers information that would be too much detail
5257 for the UserGuide or would make the UserGuide uncompilable or only compilable
5258 when installing a lot of special \SpecialChar LaTeX
5260 What should be in the UserGuide or better in Additional is a matter of
5262 It is up to you to decide that.
5263 Additional.lyx is not completely up to date (only chapter
5264 \begin_inset space ~
5268 It certainly needs a rewrite and update.
5269 For example many info in chapter
5270 \begin_inset space ~
5273 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5277 \begin_layout Description
5278 Customization.lyx This manual covers information how to customize \SpecialChar LyX
5280 output formats, operating systems, languages etc.
5281 It is currently completely out of date and needs a major rewrite and update.
5282 If you do this please assure that your information are given for all OSes
5283 and \SpecialChar LaTeX
5284 distributions (meaning be as objective as possible).
5287 \begin_layout Chapter
5291 \begin_layout Standard
5292 The aim of this chapter is to serve as a guide for the developers, to aid
5293 us to get clean and uniform code.
5295 We really like to have new developers joining the \SpecialChar LyX
5297 However, we have had problems in the past with developers leaving the project
5298 and their contributed code in a far from perfect state.
5299 Most of this happened before we really became aware of these issues, but
5300 still, we don't want it to happen again.
5301 So we have put together some guidelines and rules for the developers.
5304 \begin_layout Section
5308 \begin_layout Standard
5309 These guidelines should save us a lot of work while cleaning up the code
5310 and help us to have quality code.
5312 has been haunted by problems coming from unfinished projects by people
5313 who have left the team.
5314 Those problems will hopefully disappear if the code is easy to hand over
5316 In general, if you want to contribute to the main source, we expect at
5320 \begin_layout Itemize
5321 The most important rule first: KISS (Keep It Simple Stupid), always use
5322 a simple implementation in favor of a more complicated one.
5323 This eases maintenance a lot.
5326 \begin_layout Itemize
5327 Write good C++ code: readable, well commented, and taking advantage of the
5329 Follow the formatting guidelines.
5331 \begin_inset space ~
5335 \begin_inset CommandInset ref
5337 reference "sec:Formatting"
5347 \begin_layout Itemize
5348 As of LyX 2.4.0, you can use features of C++11.
5349 Accordingly you have to use C++11 standard conforming compiler, e.
5350 \begin_inset space \thinspace{}
5354 not too dated version of GCC or Clang.
5357 \begin_layout Itemize
5358 Adapt the code to the structures already existing in \SpecialChar LyX
5359 , or in the case that
5360 you have better ideas, discuss them on the developer's list before writing
5364 \begin_layout Itemize
5365 Take advantage of the C++ standard library.
5366 Especially don't use custom containers when a standard container is usable;
5367 learn to use the algorithms and functors in the standard library.
5370 \begin_layout Itemize
5371 Be aware of exceptions and write exception safe code.
5373 \begin_inset space ~
5377 \begin_inset CommandInset ref
5379 reference "sec:Exceptions"
5389 \begin_layout Itemize
5390 Document all variables, methods, functions, classes etc.
5391 We are using the source documentation program doxygen, a program that handles
5392 javadoc syntax, to document sources.
5393 You can download doxygen from:
5394 \begin_inset Flex URL
5397 \begin_layout Plain Layout
5399 http://www.stack.nl/~dimitri/doxygen/
5407 \begin_layout Itemize
5408 We have certain code constructs that we try to follow.
5410 \begin_inset space ~
5414 \begin_inset CommandInset ref
5416 reference "sec:Code-constructs"
5426 \begin_layout Section
5430 \begin_layout Standard
5431 It is implicitly understood that all patches contributed to The \SpecialChar LyX
5433 is under the Gnu General Public License, version 2 or later.
5434 If you have a problem with that, don't contribute code.
5435 Also please don't just pop up out of the blue with a huge patch (or small)
5436 that changes something substantial in \SpecialChar LyX
5438 Always discuss your ideas with the developers on the developer's mailing
5440 When you create the patch, please use
5441 \begin_inset Quotes eld
5449 \begin_inset Quotes erd
5452 since we find that a lot easier to read than the other diff formats.
5453 Also please do not send patches that implements or fixes several different
5454 things; several patches is a much better option.
5455 We also require you to provide a commit message entry with every patch,
5456 this describes in detail what the patch is doing.
5460 \begin_layout Section
5462 \begin_inset CommandInset label
5464 name "sec:Code-constructs"
5471 \begin_layout Standard
5472 We have several guidelines on code constructs, some of these exist to make
5473 the code faster, others to make the code clearer.
5474 Yet others exist to allow us to take advantage of the strong type checking
5478 \begin_layout Itemize
5479 Declaration of variables should wait as long as possible.
5481 \begin_inset Quotes eld
5484 Don't declare it until you need it.
5485 \begin_inset Quotes erd
5488 In C++ there are a lot of user defined types, and these can very often
5489 be expensive to initialize.
5490 This rule connects to the next rule too.
5494 \begin_layout Itemize
5495 Declare the variable as
5496 \begin_inset Flex Code
5499 \begin_layout Plain Layout
5505 if you don't need to change it.
5506 This applies to POD types like
5507 \begin_inset Flex Code
5510 \begin_layout Plain Layout
5520 \begin_layout Itemize
5521 Make the scope of a variable as small as possible.
5524 \begin_layout Itemize
5525 Make good use of namespaces.
5526 Prefer anonymous namespaces to declaring
5527 \begin_inset Flex Code
5530 \begin_layout Plain Layout
5539 \begin_layout Itemize
5540 Prefer preincrement to postincrement whenever possible.
5543 \begin_layout Itemize
5544 Preincrement has potential of being faster than postincrement.
5545 Just think about the obvious implementations of pre/post-increment.
5546 This rule applies to decrement too.
5549 \begin_layout Itemize
5551 \begin_inset Separator latexpar
5558 \begin_layout Standard
5559 \begin_inset listings
5560 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5564 \begin_layout Plain Layout
5569 \begin_layout Plain Layout
5579 \begin_layout Standard
5583 \begin_layout Standard
5584 \begin_inset listings
5585 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5589 \begin_layout Plain Layout
5591 T++; // not used in LyX
5594 \begin_layout Plain Layout
5596 U--; // not used in LyX
5605 \begin_layout Itemize
5606 Try to minimize evaluation of the same code over and over.
5607 This is aimed especially at loops.
5609 \begin_inset Newline newline
5613 \begin_inset Separator latexpar
5620 \begin_layout Standard
5621 \begin_inset listings
5622 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5626 \begin_layout Plain Layout
5628 Container::iterator end = large.end();
5631 \begin_layout Plain Layout
5633 for (Container::iterator it = large.begin(); it != end; ++it) {
5636 \begin_layout Plain Layout
5641 \begin_layout Plain Layout
5651 \begin_layout Standard
5655 \begin_layout Standard
5656 \begin_inset listings
5657 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5661 \begin_layout Plain Layout
5663 for (auto const & it : large) {
5666 \begin_layout Plain Layout
5671 \begin_layout Plain Layout
5681 \begin_layout Standard
5685 \begin_layout Standard
5686 \begin_inset listings
5687 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5691 \begin_layout Plain Layout
5693 for (Container::iterator it = large.begin(); it != large.end(); ++it) {
5696 \begin_layout Plain Layout
5701 \begin_layout Plain Layout
5712 \begin_layout Itemize
5713 For functions and methods that return a non-POD type
5717 \begin_layout Plain Layout
5724 \begin_inset Flex Code
5727 \begin_layout Plain Layout
5734 \begin_inset Flex Code
5737 \begin_layout Plain Layout
5744 This gives better type checking, and will give a compiler warning when
5745 temporaries are used wrongly.
5746 \begin_inset Separator latexpar
5753 \begin_layout Standard
5757 \begin_layout Standard
5758 \begin_inset listings
5759 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5763 \begin_layout Plain Layout
5773 \begin_layout Standard
5777 \begin_layout Standard
5778 \begin_inset listings
5779 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5783 \begin_layout Plain Layout
5794 \begin_layout Itemize
5795 Avoid using the default cases in switch statements unless you have too.
5796 Use the correct type for the switch expression and let the compiler ensure
5797 that all cases are exhausted.
5800 \begin_layout Itemize
5801 \begin_inset listings
5802 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5806 \begin_layout Plain Layout
5811 \begin_layout Plain Layout
5816 \begin_layout Plain Layout
5821 \begin_layout Plain Layout
5826 \begin_layout Plain Layout
5830 \begin_layout Plain Layout
5835 \begin_layout Plain Layout
5839 \begin_layout Plain Layout
5844 \begin_layout Plain Layout
5849 \begin_layout Plain Layout
5854 \begin_layout Plain Layout
5859 \begin_layout Plain Layout
5864 \begin_layout Plain Layout
5869 \begin_layout Plain Layout
5874 \begin_layout Plain Layout
5876 default: // not needed and would shadow a wrong use of Foo
5879 \begin_layout Plain Layout
5884 \begin_layout Plain Layout
5889 \begin_layout Plain Layout
5899 \begin_layout Itemize
5900 Use default initialization such as
5901 \begin_inset listings
5905 \begin_layout Plain Layout
5910 \begin_layout Plain Layout
5912 Class * ptr = nullptr;
5917 rather than brace initialization:
5918 \begin_inset listings
5922 \begin_layout Plain Layout
5927 \begin_layout Plain Layout
5935 Use brace initialization only for more complex data structures.
5939 \begin_layout Section
5941 \begin_inset CommandInset label
5943 name "sec:Exceptions"
5950 \begin_layout Standard
5951 Be aware of the presence of exceptions.
5952 One important thing to realize is that you often do not have to use throw,
5953 try or catch to be exception safe.
5954 Let's look at the different types of exceptions safety (these are taken
5955 from Herb Sutter's book
5956 \begin_inset CommandInset citation
5966 \begin_layout Enumerate
5967 Basic guarantee: Even in the presence of exceptions thrown by T or other
5968 exceptions, Stack objects don't leak resources.
5969 Note that this also implies that the container will be destructible and
5970 usable even if an exception is thrown while performing some container operation.
5971 However, if an exception is thrown, the container will be in a consistent,
5972 but not necessarily predictable, state.
5973 Containers that support the basic guarantee can work safely in some settings.
5977 \begin_layout Enumerate
5978 Strong guarantee: If an operation terminates because of an exception, program
5979 state will remain unchanged.
5980 This always implies commit-or-rollback semantics, including that no references
5981 or iterators into the container be invalidated if an operation fails.
5982 For example, if a Stack client calls Top and then attempts a Push that
5983 fails because of an exception, then the state of the Stack object must
5984 be unchanged and the reference returned from the prior call to Top must
5986 For more information on these guarantees, see Dave Abrahams's documentation
5987 of the SGI exception-safe standard library adaption at:
5988 \begin_inset Flex URL
5991 \begin_layout Plain Layout
5993 http://www.stlport.org/doc/exception_safety.html
5998 Probably the most interesting point here is that when you implement the
5999 basic guarantee, the strong guarantee often comes for free.
6000 For example, in our Stack implementation, almost everything we did was
6001 needed to satisfy just the basic guarantee – and what's presented above
6002 very nearly satisfies the strong guarantee, with little or no extra work.
6003 Not half bad, considering all the trouble we went to.
6004 In addition to these two guarantees, there is one more guarantee that certain
6005 functions must provide in order to make overall exception safety possible:
6008 \begin_layout Enumerate
6009 No throw guarantee: The function will not emit an exception under any circumstan
6011 Overall exception safety isn't possible unless certain functions are guaranteed
6013 In particular, we've seen that this is true for destructors; later in this
6014 miniseries, we'll see that it's also needed in certain helper functions,
6022 \begin_layout Standard
6023 For all cases where we might be able to write exception safe functions without
6024 using try, throw or catch we should do so.
6025 In particular we should look over all destructors to ensure that they are
6026 as exception safe as possible.
6029 \begin_layout Section
6031 \begin_inset CommandInset label
6033 name "sec:Formatting"
6040 \begin_layout Itemize
6041 Only one declaration on each line.
6042 \begin_inset Separator latexpar
6049 \begin_layout Standard
6053 \begin_layout Standard
6054 \begin_inset listings
6055 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6059 \begin_layout Plain Layout
6064 \begin_layout Plain Layout
6074 \begin_layout Standard
6078 \begin_layout Standard
6079 \begin_inset listings
6080 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6084 \begin_layout Plain Layout
6086 int a, b; // not used in LyX
6094 \begin_layout Standard
6095 This is especially important when initialization is done at the same time:
6098 \begin_layout Standard
6102 \begin_layout Standard
6103 \begin_inset listings
6104 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6108 \begin_layout Plain Layout
6113 \begin_layout Plain Layout
6115 string b = "Gullik";
6123 \begin_layout Standard
6127 \begin_layout Standard
6128 \begin_inset listings
6129 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6133 \begin_layout Plain Layout
6135 string a = "Lars", b = "Gullik"; // not used in LyX
6143 \begin_layout Standard
6145 \begin_inset Flex Code
6148 \begin_layout Plain Layout
6154 is formally calling a copy constructor on a temporary constructed from
6155 a string literal and therefore has the potential of being more expensive
6156 then direct construction by
6157 \begin_inset Flex Code
6160 \begin_layout Plain Layout
6167 However the compiler is allowed to elide the copy (even if it had side
6168 effects), and modern compilers typically do so.
6169 Given these equal costs, \SpecialChar LyX
6170 code favours the '=' idiom as it is in line with
6171 the traditional C-style initialization,
6175 cannot be mistaken as function declaration,
6179 reduces the level of nested parentheses in more initializations.]
6183 \begin_layout Itemize
6184 Pointers and references:
6185 \begin_inset Separator latexpar
6192 \begin_layout Standard
6196 \begin_layout Standard
6197 \begin_inset listings
6198 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6202 \begin_layout Plain Layout
6207 \begin_layout Plain Layout
6217 \begin_layout Standard
6221 \begin_layout Standard
6222 \begin_inset listings
6223 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6227 \begin_layout Plain Layout
6229 char *p = "flop"; // not used in LyX
6232 \begin_layout Plain Layout
6234 char &c = *p; // not used in LyX
6242 \begin_layout Standard
6243 Some time ago we had a huge discussion on this subject and after convincing
6244 argumentation from Asger this is what we decided.
6245 Also note that we will have:
6248 \begin_layout Standard
6249 \begin_inset listings
6250 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6254 \begin_layout Plain Layout
6264 \begin_layout Standard
6268 \begin_layout Standard
6269 \begin_inset listings
6270 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6274 \begin_layout Plain Layout
6276 const char * p; // not used in LyX
6285 \begin_layout Itemize
6286 Operator names and parentheses
6287 \begin_inset Separator latexpar
6294 \begin_layout Standard
6295 \begin_inset listings
6296 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6300 \begin_layout Plain Layout
6310 \begin_layout Standard
6314 \begin_layout Standard
6315 \begin_inset listings
6316 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6320 \begin_layout Plain Layout
6322 operator == (type) // not used in LyX
6330 \begin_layout Standard
6331 The == is part of the function name, separating it makes the declaration
6332 look like an expression.
6336 \begin_layout Itemize
6337 Function names and parentheses
6338 \begin_inset Separator latexpar
6345 \begin_layout Standard
6346 \begin_inset listings
6347 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6351 \begin_layout Plain Layout
6361 \begin_layout Standard
6365 \begin_layout Standard
6366 \begin_inset listings
6367 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6371 \begin_layout Plain Layout
6373 void mangle () // not used in LyX
6382 \begin_layout Itemize
6384 \begin_inset Separator latexpar
6391 \begin_layout Standard
6392 \begin_inset listings
6393 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6397 \begin_layout Plain Layout
6402 \begin_layout Plain Layout
6407 \begin_layout Plain Layout
6412 \begin_layout Plain Layout
6417 \begin_layout Plain Layout
6427 \begin_layout Standard
6431 \begin_layout Standard
6432 \begin_inset listings
6433 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6437 \begin_layout Plain Layout
6442 \begin_layout Plain Layout
6447 \begin_layout Plain Layout
6452 \begin_layout Plain Layout
6457 \begin_layout Plain Layout
6467 \begin_layout Standard
6468 \begin_inset listings
6469 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6473 \begin_layout Plain Layout
6475 enum { one = 1, two = 2, three 3 }; // not used in LyX
6483 \begin_layout Standard
6487 \begin_layout Standard
6488 \begin_inset listings
6489 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6493 \begin_layout Plain Layout
6498 \begin_layout Plain Layout
6503 \begin_layout Plain Layout
6508 \begin_layout Plain Layout
6513 \begin_layout Plain Layout
6524 \begin_layout Itemize
6526 \begin_inset Separator latexpar
6533 \begin_layout Standard
6534 Use nullptr (C++11):
6537 \begin_layout Standard
6538 \begin_inset listings
6539 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6543 \begin_layout Plain Layout
6553 \begin_layout Standard
6557 \begin_layout Standard
6558 \begin_inset listings
6559 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6563 \begin_layout Plain Layout
6565 void * p = NULL; // not used in LyX
6573 \begin_layout Standard
6577 \begin_layout Standard
6578 \begin_inset listings
6579 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6583 \begin_layout Plain Layout
6587 0'; // not used in LyX
6595 \begin_layout Standard
6599 \begin_layout Standard
6600 \begin_inset listings
6601 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6605 \begin_layout Plain Layout
6607 void * p = 42 - 7 * 6; // not used in LyX
6615 \begin_layout Standard
6616 Note: As an exception, imported third party code as well as code interfacing
6618 \begin_inset Quotes eld
6622 \begin_inset Quotes erd
6626 \begin_inset Flex Code
6629 \begin_layout Plain Layout
6639 \begin_layout Itemize
6640 Naming rules for classes
6641 \begin_inset Separator latexpar
6648 \begin_layout Itemize
6649 Use descriptive but simple and short names.
6653 \begin_layout Itemize
6654 Class names are usually capitalized, and function names lowercased.
6657 \begin_layout Itemize
6658 Enums are named like Classes, values are usually in lower-case.
6661 \begin_layout Itemize
6662 Public API functions are camel-case (
6663 \begin_inset Flex Code
6666 \begin_layout Plain Layout
6667 void setAFlagToAValue(bool)
6675 \begin_layout Itemize
6676 Member variables are underscored (
6677 \begin_inset Flex Code
6680 \begin_layout Plain Layout
6681 enable_this_feature_flag_
6687 \begin_inset Quotes eld
6691 \begin_inset Quotes erd
6697 \begin_layout Itemize
6698 Private/protected functions are also camel-case.
6701 \begin_layout Itemize
6702 New types are capitalized, so this goes for typedefs, classes, structs and
6707 \begin_layout Itemize
6709 \begin_inset Separator latexpar
6716 \begin_layout Itemize
6717 Adapt the formatting of your code to the one used in the other parts of
6720 In case there is different formatting for the same construct, use the one
6725 \begin_layout Itemize
6726 Use existing structures
6727 \begin_inset Separator latexpar
6734 \begin_layout Itemize
6735 \begin_inset CommandInset label
6737 name "Use-string-wherever"
6742 \begin_inset Flex Code
6745 \begin_layout Plain Layout
6752 Unicode strings should prefer using
6753 \begin_inset Flex Code
6756 \begin_layout Plain Layout
6762 instead of UTF-8 encoded
6763 \begin_inset Flex Code
6766 \begin_layout Plain Layout
6775 \begin_layout Itemize
6776 Check out the filename and path tools in
6777 \begin_inset Flex Code
6780 \begin_layout Plain Layout
6789 \begin_layout Itemize
6790 Check out the string tools in
6791 \begin_inset Flex Code
6794 \begin_layout Plain Layout
6803 \begin_layout Itemize
6804 Use the \SpecialChar LyX
6805 Err class to report errors and messages using the lyxerr instantiation.
6806 [add description of other existing structures]
6810 \begin_layout Itemize
6812 \begin_inset Separator latexpar
6819 \begin_layout Itemize
6820 Use this order for the access sections of your class: public, protected,
6822 The public section is interesting for every user of the class.
6823 The private section is only of interest for the implementors of the class
6825 [Obviously not true since this is for developers, and we do not want one
6826 developer only to be able to read and understand the implementation of
6831 \begin_layout Itemize
6832 Avoid declaring global objects in the declaration file of the class.
6833 If the same variable is used for all objects, use a static member.
6836 \begin_layout Itemize
6837 Avoid global or static variables.
6841 \begin_layout Itemize
6843 \begin_inset Separator latexpar
6850 \begin_layout Standard
6851 If you create a new file, the top of the file should look something like
6855 \begin_layout Standard
6856 \begin_inset listings
6857 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6861 \begin_layout Plain Layout
6866 \begin_layout Plain Layout
6873 \begin_layout Plain Layout
6875 * This file is part of LyX, the document processor.
6878 \begin_layout Plain Layout
6880 * Licence details can be found in the file COPYING.
6883 \begin_layout Plain Layout
6888 \begin_layout Plain Layout
6895 \begin_layout Plain Layout
6900 \begin_layout Plain Layout
6902 * Full author contact details are available
6905 \begin_layout Plain Layout
6910 \begin_layout Plain Layout
6921 \begin_layout Itemize
6923 \begin_inset Separator latexpar
6930 \begin_layout Itemize
6931 The documentation is generated from the header files.
6934 \begin_layout Itemize
6935 You document for the other developers, not for yourself.
6938 \begin_layout Itemize
6939 You should document what the function does, not the implementation.
6940 \begin_inset Separator latexpar
6947 \begin_layout Itemize
6948 in the .cpp files you document the implementation.
6952 \begin_layout Itemize
6953 Single line description (
6954 \begin_inset Flex Code
6957 \begin_layout Plain Layout
6963 ), multiple lines description (
6964 \begin_inset Flex Code
6967 \begin_layout Plain Layout
6974 ), see the doxygen webpage referenced above.
6978 \begin_layout Section
6979 Naming rules for \SpecialChar LyX
6980 User Functions (LFUNs)
6983 \begin_layout Standard
6984 Here is the set of rules to apply when a new command name is introduced:
6987 \begin_layout Enumerate
6988 Use the object.event order.
6989 That is, use `word-forward' instead of `forward-word'.
6992 \begin_layout Enumerate
6993 Don't introduce an alias for an already named object.
6997 \begin_layout Enumerate
6998 Forward movement or focus is called `forward' (not `right').
7001 \begin_layout Enumerate
7002 Backward movement or focus is called `backward' (not `left').
7005 \begin_layout Enumerate
7006 Upward movement of focus is called `up'.
7009 \begin_layout Enumerate
7010 Downward movement is called `down'.
7013 \begin_layout Enumerate
7014 The begin of an object is called `begin' (not `start').
7017 \begin_layout Enumerate
7018 The end of an object is called `end'.
7021 \begin_layout Section
7022 How to create class interfaces
7025 \begin_layout Standard
7026 (a.k.a How Non-Member Functions Improve Encapsulation)
7029 \begin_layout Standard
7030 I recently read an article by Scott Meyers, where he makes a strong case
7031 on how non-member functions makes classes more encapsulated, not less.
7032 Just skipping to the core of this provides us with the following algorithm
7033 for deciding what kind of function to add to a class interface:
7036 \begin_layout Itemize
7037 We need to add a function f to the class C's API.
7038 \begin_inset Separator latexpar
7045 \begin_layout Standard
7046 \begin_inset listings
7047 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7051 \begin_layout Plain Layout
7053 if (f needs to be virtual)
7056 \begin_layout Plain Layout
7058 make f a member function of C;
7061 \begin_layout Plain Layout
7063 else if (f is operator>> or operator<<) {
7066 \begin_layout Plain Layout
7068 make f a non-member function;
7071 \begin_layout Plain Layout
7073 if (f needs access to non-public members of C)
7076 \begin_layout Plain Layout
7078 make f a friend of C;
7081 \begin_layout Plain Layout
7083 } else if (f needs type conversions on its left-most argument) {
7086 \begin_layout Plain Layout
7088 make f a non-member function;
7091 \begin_layout Plain Layout
7093 if (f needs access to non-public members of C)
7096 \begin_layout Plain Layout
7098 make f a friend of C;
7101 \begin_layout Plain Layout
7103 } else if (f can be implemented via C's public interface)
7106 \begin_layout Plain Layout
7108 make f a non-member function;
7111 \begin_layout Plain Layout
7116 \begin_layout Plain Layout
7118 make f a member function of C;
7127 \begin_layout Chapter
7128 Coding recommendations
7131 \begin_layout Standard
7132 These are some rules for effective C++ programming.
7133 These are taken from Scott Meyers
7134 \begin_inset CommandInset citation
7141 , and are presented in their short form.
7142 These are not all the rules Meyers presents, only the most important of
7145 does not yet follow these rules, but they should be the goal.
7148 \begin_layout Itemize
7162 \begin_layout Itemize
7163 use the same form in corresponding calls to new and delete, i.e.
7165 \begin_inset Flex Code
7168 \begin_layout Plain Layout
7175 \begin_inset Flex Code
7178 \begin_layout Plain Layout
7184 was used to create the object and write
7185 \begin_inset Flex Code
7188 \begin_layout Plain Layout
7195 \begin_inset Flex Code
7198 \begin_layout Plain Layout
7204 Notice strings should be
7205 \begin_inset Flex Code
7208 \begin_layout Plain Layout
7215 \begin_inset Flex Code
7218 \begin_layout Plain Layout
7225 (this contradicts to
7226 \begin_inset CommandInset ref
7228 reference "Use-string-wherever"
7235 \begin_layout Itemize
7236 define a default constructor, copy constructor and an assignment operator
7237 for all classes with dynamically allocated memory that are not made noncopyable
7240 \begin_layout Itemize
7241 do not define default constructor, copy constructor and an assignment operator
7242 if the compiler generated one would do the same
7245 \begin_layout Itemize
7246 make destructors virtual in base classes and only there
7249 \begin_layout Itemize
7250 assign to all data members in operator=()
7253 \begin_layout Itemize
7254 strive for class interfaces that are complete and minimal
7257 \begin_layout Itemize
7258 differentiate among member functions, global functions and friend functions
7261 \begin_layout Itemize
7262 avoid data members in the public interface
7265 \begin_layout Itemize
7266 use const whenever possible
7269 \begin_layout Itemize
7270 pass and return objects by reference instead of by value
7273 \begin_layout Itemize
7274 choose carefully between function overloading and parameter defaulting
7277 \begin_layout Itemize
7278 never return a reference to a local object or a dereferenced pointer initialized
7279 by new within the function
7282 \begin_layout Itemize
7283 use enums for integral constants
7286 \begin_layout Itemize
7287 minimize compilation dependencies between files
7290 \begin_layout Itemize
7291 pay attention to compiler warnings
7294 \begin_layout Itemize
7295 differentiate between inheritance of interface and inheritance of implementation
7298 \begin_layout Itemize
7299 differentiate between inheritance and templates
7302 \begin_layout Itemize
7303 ensure that global objects are initialized before they are used
7306 \begin_layout Itemize
7308 \begin_inset Flex Code
7311 \begin_layout Plain Layout
7318 \begin_inset Flex Code
7321 \begin_layout Plain Layout
7327 that span more than a line
7330 \begin_layout Chapter
7335 \begin_layout Itemize
7336 And one of mine: (Lgb)
7337 \begin_inset Separator latexpar
7344 \begin_layout Itemize
7345 when switching on enums, refrain from using "default:" if possible
7349 \begin_layout Itemize
7350 And one of mine: (Andre')
7351 \begin_inset Separator latexpar
7358 \begin_layout Itemize
7359 try to implement your class in a way that the automatically generated copy
7360 constructor and copy assignment work out-of-the box
7363 \begin_layout Itemize
7364 I don't have problems with using boost in the implementation _if and only
7365 if_ it provides actual benefits over less intrusive alternatives.
7366 I do have a problem with needlessly sprinkling 'boost::' over interfaces,
7367 especially if it does not add any value.
7368 \begin_inset Separator latexpar
7375 \begin_layout Standard
7376 Given that there seems to be an unconditional "typedef unsigned int quint32;"
7377 in qglobal.h I don't think there's any platform supported by current \SpecialChar LyX
7379 could not use 'unsigned int' (and an static assert in some implementation
7380 file for the unlikely case some ILP64 zombie raises its ugly head again.
7381 And if that happens, using <cstdint> would still be a better choice...)
7384 \begin_layout Standard
7385 The idea is to create something that's not compilable as soon as the condition
7387 There are lots of possibilities to achieve this, some examples follow:
7390 \begin_layout Standard
7391 In C++11 there's a "built-in":
7394 \begin_layout Standard
7395 \begin_inset listings
7396 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7400 \begin_layout Plain Layout
7402 static_assert(sizeof(int) == 4, "Funny platform")
7410 \begin_layout Standard
7411 until then on namespace scope:
7414 \begin_layout Standard
7415 \begin_inset listings
7416 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7420 \begin_layout Plain Layout
7422 #include <boost/static_assert.hpp>
7425 \begin_layout Plain Layout
7427 BOOST_STATIC_ASSERT(sizeof(int) == 4)
7435 \begin_layout Standard
7439 \begin_layout Standard
7440 \begin_inset listings
7441 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7445 \begin_layout Plain Layout
7447 template<bool Condition>
7450 \begin_layout Plain Layout
7452 struct static_assert_helper;
7455 \begin_layout Plain Layout
7460 \begin_layout Plain Layout
7462 struct static_assert_helper<true> {};
7465 \begin_layout Plain Layout
7470 \begin_layout Plain Layout
7472 dummy = sizeof(static_assert_helper<sizeof(int) == 4>)
7475 \begin_layout Plain Layout
7485 \begin_layout Standard
7486 or somewhat brutish without templates, in any function:
7489 \begin_layout Standard
7490 \begin_inset listings
7491 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7495 \begin_layout Plain Layout
7497 const int d = sizeof(int) - 4;
7500 \begin_layout Plain Layout
7505 \begin_layout Plain Layout
7510 \begin_layout Plain Layout
7515 \begin_layout Plain Layout
7520 \begin_layout Plain Layout
7530 \begin_layout Standard
7531 Any of them in a .cpp file will break compilation as soon as
7532 \begin_inset Flex Code
7535 \begin_layout Plain Layout
7542 Personally I prefer something like the third version (or the first, if
7543 using C++11 is allowed).
7548 \begin_layout Itemize
7549 And one of mine: (vfr)
7550 \begin_inset Separator latexpar
7557 \begin_layout Itemize
7559 \begin_inset Flex URL
7562 \begin_layout Plain Layout
7564 http://www.lyx.org/trac/changeset/35855
7570 \begin_inset Separator latexpar
7577 \begin_layout Standard
7578 A dynamic_cast is necessary when:
7581 \begin_layout Itemize
7582 the object to be casted is from an external library because we can't add
7583 Qxxx::asXxxx() to Qt e.g.:
7584 \begin_inset Separator latexpar
7591 \begin_layout Itemize
7592 QAbstractListModel to GuiIdListModel,
7595 \begin_layout Itemize
7596 QValidator to PathValidator,
7599 \begin_layout Itemize
7600 QWidget to TabWorkArea,
7603 \begin_layout Itemize
7604 QWidget to GuiWorkArea;
7608 \begin_layout Itemize
7609 the object is to be casted from an interface to the implementing class,
7610 because the Interface does not know by whom it is implemented:
7611 \begin_inset Separator latexpar
7618 \begin_layout Itemize
7619 ProgressInterface to GuiProgress,
7622 \begin_layout Itemize
7623 Application to GuiApplication.
7627 \begin_layout Standard
7628 A dynamic_cast can be replaced by:
7631 \begin_layout Itemize
7632 already existing as***Inset() functions, e.g.:
7633 \begin_inset Separator latexpar
7640 \begin_layout Itemize
7644 \begin_layout Itemize
7645 asInsetMath()->asMacro(),
7648 \begin_layout Itemize
7653 \begin_layout Itemize
7654 A static_cast when we are sure this can't go wrong, e.g.:
7655 \begin_inset Separator latexpar
7662 \begin_layout Itemize
7663 we are sure that CellData::inset->clone() is an InsetTableCell,
7666 \begin_layout Itemize
7667 in cases where we explicitly check it->lyxCode().
7673 \begin_layout Bibliography
7674 \begin_inset CommandInset bibitem
7675 LatexCommand bibitem
7682 Effective C++: 50 Specific Ways to Improve Your Programs and Design.
7683 Addison-Wesley, 1992.
7686 \begin_layout Bibliography
7687 \begin_inset CommandInset bibitem
7688 LatexCommand bibitem
7695 Exceptional C++: 47 engineering puzzles, programming problems, and solutions.
7699 \begin_layout Bibliography
7700 \begin_inset CommandInset bibitem
7701 LatexCommand bibitem
7708 C/C++ User's Journal (Vol.18, No.2).