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
109 Developing \SpecialChar LyX
113 \begin_layout Subtitle
118 by the \SpecialChar LyX
123 \begin_layout Plain Layout
124 If you have comments on or error corrections to this documentation, please
125 send them to the \SpecialChar LyX
126 Documentation mailing list:
127 \begin_inset CommandInset href
129 target "lyx-docs@lists.lyx.org"
143 \begin_layout Standard
144 \begin_inset CommandInset toc
145 LatexCommand tableofcontents
152 \begin_layout Chapter
156 \begin_layout Standard
157 This manual documents some aspects of \SpecialChar LyX
159 It is currently rather incomplete, but will hopefully be extended in the
161 Meanwhile, additional information can be found in the
162 \begin_inset Flex Code
165 \begin_layout Plain Layout
171 subfolder of the \SpecialChar LyX
172 source code distribution.
173 This document is not translated, since the development language of \SpecialChar LyX
176 If you just want to use \SpecialChar LyX
177 , then you don't need to read this manual.
178 However, if you want to learn more about how \SpecialChar LyX
179 is developed, or even want
180 to participate in \SpecialChar LyX
181 development, you may find some interesting information
185 \begin_layout Chapter
189 \begin_layout Standard
191 uses several custom file formats for configuration files and documents.
192 This chapter contains some background concerning these file formats.
193 Several file formats are also described in detail in the regular user documenta
197 \begin_layout Section
201 \begin_layout Section
202 When is an update of the .lyx file format number needed?
203 \begin_inset CommandInset label
205 name "sec:When-is-an"
212 \begin_layout Standard
213 When you are working on a new feature you may ask yourself whether it needs
214 an update of the .lyx file format number.
215 Whether an update is needed or not is not always obvious.
220 Whenever there is the danger that a previous version of LyX cannot open
221 a file using the new feature, a file format update is needed.
224 \begin_layout Standard
225 The file format change allows lyx2lyx rules to implement backwards compatibility.
226 Below you can find a list of reasons for file format updates with explanations:
229 \begin_layout Description
238 setting Whenever you introduce a new setting that is stored in the document
239 header, a file format update is needed.
242 \begin_layout Description
251 setting If a certain setting becomes obsolete and gets removed, a file format
255 \begin_layout Description
281 \begin_inset space \thinspace{}
288 \begin_layout Description
289 \paragraph_spacing single
302 package The reason for this is that there is no true ERT inset for math
303 formulas: Each command is parsed, and if a user happens to define a local
304 command with the same name as a command that triggers an automatic load
305 of a package, they need to be able to switch off the automatic loading
307 This switch is stored by the
308 \begin_inset Flex Code
311 \begin_layout Plain Layout
320 \begin_layout Description
325 language that is stored in
326 \begin_inset Flex Code
329 \begin_layout Plain Layout
339 \begin_inset Note Note
342 \begin_layout Plain Layout
343 This requirement is under discussion.
352 \begin_layout Description
357 inset Of course a new inset requires a file format update.
360 \begin_layout Description
365 style If a new style or inset layout is added to any layout file or module
366 shipped with \SpecialChar LyX
367 , then a new file format is needed in the master (development)
369 It is possible to backport new styles to the stable version without a file
372 \begin_inset CommandInset ref
374 reference "subsec:Backporting-new-styles"
378 for more information.
381 \begin_layout Description
386 style If a style or inset layout is removed in any layout file or module
387 shipped with \SpecialChar LyX
388 , a new file format is required.
391 \begin_layout Standard
396 layouts and modules do
400 require a file format update (changed 03/16, see
401 \begin_inset CommandInset ref
403 reference "subsec:New-layouts"
411 \begin_layout Standard
412 If you are still unsure, please ask on the development list.
415 \begin_layout Section
416 \begin_inset CommandInset label
418 name "subsec:update_lyx_files"
422 How to update the file format number of .lyx files
425 \begin_layout Standard
426 Once you come to the conclusion that a file format update is needed, you
427 should use the following procedure to perform the update:
430 \begin_layout Enumerate
431 Implement and test the new feature, including the reading and writing of
433 Note that any file produced at this stage does not use a valid format,
434 so do not use this version of \SpecialChar LyX
435 for working on any important documents.
438 \begin_layout Enumerate
439 \begin_inset CommandInset label
441 name "enu:Describe_format"
445 Describe the new format in
446 \begin_inset Flex Code
449 \begin_layout Plain Layout
458 \begin_layout Enumerate
459 Update the \SpecialChar LyX
460 file format number in
461 \begin_inset Flex Code
464 \begin_layout Plain Layout
473 \begin_layout Enumerate
474 \begin_inset CommandInset label
476 name "enu:Add-an-entry"
480 Add an entry to both format lists (for conversion and reversion) in
481 \begin_inset Newline newline
485 \begin_inset Flex Code
488 \begin_layout Plain Layout
489 lib/lyx2lyx/lyx_2_4.py
495 Add a conversion routine if needed (e.
496 \begin_inset space \thinspace{}
499 g., a new header setting always needs a conversion that adds the new setting,
500 but a new document language does not need one).
501 Add a reversion routine if needed.
503 \begin_inset Newline newline
506 While the conversion routine is required to produce a document that is equivalen
507 t to the old version, the requirements of the reversion are not that strict.
508 If possible, try to produce a proper reversion, using ERT if needed, but
509 for some features this might be too complicated.
510 In this case, the minimum requirement of the reversion routine is that
511 it produces a valid document which can be read by an older \SpecialChar LyX
513 If absolutely needed, even data loss is allowed for the reversion.
514 (In that case, you might want to add a LyX comment that indicates what
515 you have had to do, so the user is at least warned).
518 \begin_layout Enumerate
519 Since tex2lyx has several implicit file format dependencies caused by sharing
520 code with \SpecialChar LyX
521 , updating the file format of .lyx files produced by tex2lyx at
522 the same time as updating the main .lyx file format is strongly recommended.
523 Therefore, a compiler warning will be issued if the \SpecialChar LyX
524 and tex2lyx .lyx file
525 format numbers differ.
526 In many cases the tex2lyx update requires only the first and last item
531 \begin_layout Enumerate
532 Update the tex2lyx file format number in
533 \begin_inset Flex Code
536 \begin_layout Plain Layout
545 \begin_layout Enumerate
546 If the lyx2lyx conversion from the old to the new format is empty, or if
547 tex2lyx does not yet output the changed feature, you do not need any further
549 Otherwise, search for the changed feature in tex2lyx, and adjust the output
550 according to the lyx2lyx changes.
553 \begin_layout Enumerate
554 Update the tex2lyx test references as described in
555 \begin_inset CommandInset ref
556 LatexCommand formatted
557 reference "sec:Updating-test-references"
565 \begin_layout Enumerate
566 If you did not implement full tex2lyx support for the new feature, add a
568 \begin_inset Flex Code
571 \begin_layout Plain Layout
577 describing the missing bits.
578 Note that it is perfectly fine if you do not add full tex2lyx support for
579 a new feature: The updating recommendation above is only issued for the
580 syntax of the produced .lyx file.
581 It is no problem if some features supported by \SpecialChar LyX
582 are still output as ERT
584 The problems in the past that resulted in the update recommendation were
585 related to mixed version syntax, not ERT.
588 \begin_layout Enumerate
589 It would be nice if you could create a .lyx test file which contains instances
590 of all changed or added features.
591 This could then be used to test lyx2lyx and tex2lyx.
592 Test samples are collected under the corresponding subdirectories of
599 \begin_layout Enumerate
600 \begin_inset CommandInset label
602 name "enu:updatefiles"
606 Test your lyx2lyx code by updating LyX's .lyx documentation files to the
608 The developer who makes the change knows best what changes to expect when
609 inspecting the resulting diff.
610 Because of this, you might be able to catch a bug in the lyx2lyx code that
611 updates the format just by taking a quick scan through the large diff that
613 \begin_inset Note Note
616 \begin_layout Plain Layout
617 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
618 see which layout update made an unexpected change by looking at the git
619 log of a .lyx file that suffers the problem.
624 To do this, first make sure that there are no changes to the git repository
625 that you will not want to commit (this is needed because it will be convenient
626 to commit with the command
627 \begin_inset Flex Code
630 \begin_layout Plain Layout
637 Then run the following command in the root folder of the source:
638 \begin_inset Flex Code
641 \begin_layout Plain Layout
642 python development/tools/updatedocs.py
648 Look at the resulting changes using the command
649 \begin_inset Flex Code
652 \begin_layout Plain Layout
659 If anything looks surprising, please investigate.
660 Keep in mind that the case of
661 \begin_inset Flex Code
664 \begin_layout Plain Layout
670 is special, because it is first generated with
671 \begin_inset Flex Code
674 \begin_layout Plain Layout
680 before being converted to the latest format.
681 \begin_inset Newline newline
685 \begin_inset Note Greyedout
688 \begin_layout Plain Layout
693 Only commit file format changes in the doc files if these files are using
694 the new feature of the new file format.
700 \begin_inset CommandInset ref
702 reference "enu:The-fileformat-of"
706 of the documentation policies described in sec.
711 \begin_inset CommandInset ref
713 reference "sec:Documentation-policies"
725 \begin_layout Enumerate
726 Finally, commit using
727 \begin_inset Flex Code
730 \begin_layout Plain Layout
739 \begin_layout Section
740 Updating the file format number of layout files
743 \begin_layout Standard
744 The procedure for updating the layout files is similar to that in step
745 \begin_inset CommandInset ref
747 reference "enu:updatefiles"
752 \begin_inset CommandInset ref
754 reference "subsec:update_lyx_files"
760 \begin_inset Flex Code
763 \begin_layout Plain Layout
764 python development/tools/updatelayouts.py
770 \begin_inset Flex Code
773 \begin_layout Plain Layout
782 \begin_layout Standard
783 Note that we do not automatically update any local layout used in the
784 \begin_inset Flex Code
787 \begin_layout Plain Layout
793 files shipped with \SpecialChar LyX
794 because users would then not be able to export to older
796 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
797 to open the file in \SpecialChar LyX
798 2.1.x, there would be an error because the file would
799 contain a local layout whose format is too new.
800 The root reason for this is that we do not support converting layouts to
801 older layout formats, as we do for the
802 \begin_inset Flex Code
805 \begin_layout Plain Layout
814 \begin_layout Section
815 Updating the file format number of bind/ui files
818 \begin_layout Standard
819 A change to the functionality of existing LFUNs can require a conversion
821 \begin_inset Flex Code
824 \begin_layout Plain Layout
831 \begin_inset Flex Code
834 \begin_layout Plain Layout
840 files, and therefore an increment of the LFUN format, as well as a conversion
842 \begin_inset Flex Code
845 \begin_layout Plain Layout
852 The latter cannot be done automatically and also requires an update of
856 \begin_inset space \space{}
859 of someone who might have made a set of \SpecialChar LyX
860 teaching manuals for use in their
865 \begin_layout Plain Layout
866 \begin_inset Flex URL
869 \begin_layout Plain Layout
871 https://www.lyx.org/trac/ticket/9794
884 \begin_layout Standard
885 To update the LFUN format:
888 \begin_layout Enumerate
889 Increment the LFUN file format number in
890 \begin_inset Flex Code
893 \begin_layout Plain Layout
902 \begin_layout Enumerate
903 Implement the LFUN conversion in
904 \begin_inset Flex Code
907 \begin_layout Plain Layout
908 lib/scripts/prefs2prefs_lfuns.py
916 \begin_layout Enumerate
918 \begin_inset CommandInset ref
920 reference "enu:updatefiles"
925 \begin_inset CommandInset ref
927 reference "subsec:update_lyx_files"
932 \begin_inset Flex Code
935 \begin_layout Plain Layout
941 command, use this command:
942 \begin_inset Flex Code
945 \begin_layout Plain Layout
946 bash development/tools/updatelfuns.sh
953 \begin_inset Note Note
956 \begin_layout Plain Layout
957 This file should really be converted to python.
965 \begin_layout Enumerate
966 Update Info insets in
967 \begin_inset Flex Code
970 \begin_layout Plain Layout
977 To do so, increment the \SpecialChar LyX
978 format and proceed as in
979 \begin_inset CommandInset ref
981 reference "subsec:update_lyx_files"
986 \begin_inset CommandInset ref
988 reference "enu:Describe_format"
993 \begin_inset CommandInset ref
995 reference "enu:updatefiles"
1000 In the lyx2lyx implementation (step
1001 \begin_inset CommandInset ref
1003 reference "enu:Add-an-entry"
1007 ), implement a conversion similar to the one in
1008 \begin_inset Flex Code
1011 \begin_layout Plain Layout
1012 prefs2prefs_lfuns.py
1017 above, as well as a corresponding reversion; for this one can use
1018 \begin_inset Flex Code
1021 \begin_layout Plain Layout
1028 \begin_inset Flex Code
1031 \begin_layout Plain Layout
1032 lib/lyx2lyx/lyx2lyx_tools.py
1041 \begin_layout Section
1042 Backporting new styles to the stable version
1043 \begin_inset CommandInset label
1045 name "subsec:Backporting-new-styles"
1052 \begin_layout Standard
1053 Starting with the stable \SpecialChar LyX
1054 2.1 branch, there is a mechanism in place to backport
1055 new styles to the stable version without the need to update the file format.
1056 The basic idea is that the new style definition is automatically copied
1057 to the document preamble so that it can even be used by older minor versions
1058 that did not yet include the style.
1059 To backport a new style to the stable version, the following steps are
1063 \begin_layout Enumerate
1065 \begin_inset Flex Code
1068 \begin_layout Plain Layout
1074 to the style definition in the development version.
1077 \begin_layout Enumerate
1078 Copy the style definition to the stable version, but use
1079 \begin_inset Flex Code
1082 \begin_layout Plain Layout
1089 If needed adjust the format to the one used by the stable version (see
1090 the customization manual for details of the layout file format).
1093 \begin_layout Enumerate
1094 For each update of the style in a later stable version, increase the argument
1096 \begin_inset Flex Code
1099 \begin_layout Plain Layout
1106 (In the stable version, the development version should not be touched.)
1109 \begin_layout Standard
1110 For details about the
1111 \begin_inset Flex Code
1114 \begin_layout Plain Layout
1120 flag see the customization manual.
1122 \begin_inset Flex Code
1125 \begin_layout Plain Layout
1131 support is needed for backported styles: Since the style of the development
1132 version has an infinite version number, it will always be used.
1133 Furthermore, since its version number is less than one, the style will
1134 not be written anymore to the document header for files saved by the new
1138 \begin_layout Chapter
1139 New layouts and modules
1142 \begin_layout Section
1143 \begin_inset CommandInset label
1145 name "subsec:New-layouts"
1152 \begin_layout Standard
1153 Adding a new layout file to the \SpecialChar LyX
1155 \begin_inset Quotes eld
1158 officially supported
1159 \begin_inset Quotes erd
1163 You should therefore think carefully about whether you really want to do
1164 this and discuss it on lyx-devel, since you will need to be prepared to
1165 update and fix the layout if necessary.
1166 If the layout is experimental or for a rarely used document class, then
1167 it may be better to add it to the relevant portion of the \SpecialChar LyX
1171 \begin_inset CommandInset href
1173 target "https://wiki.lyx.org/Layouts/Layouts"
1181 \begin_layout Standard
1182 In older versions of this document, it was stated that new layout files
1183 require a file format change.
1184 After some discussion, it was decided that this is not needed.
1188 \begin_layout Plain Layout
1190 \begin_inset CommandInset href
1192 name "the thread “Proposal for a guide on updating layouts”"
1193 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1207 For reference, here are the arguments on each side
1211 \begin_layout Description
1213 \begin_inset Quotes eld
1216 New layout files are a file format change
1217 \begin_inset Quotes erd
1223 \begin_layout Itemize
1224 All documents produced by 2.2.
1225 \begin_inset Formula $x$
1228 can always be edited and exported even if
1229 \begin_inset Formula $x$
1233 This is important for people using different machines, or exchanging work
1237 \begin_layout Description
1239 \begin_inset Quotes eld
1242 New layout files are not a file format change
1243 \begin_inset Quotes erd
1249 \begin_layout Itemize
1250 No new LaTeX classes can be supported in a stable version, and stable versions
1251 have a typical lifetime of 2–3 years.
1254 \begin_layout Itemize
1255 We have the same situation already with custom layout files: If a document
1256 using a custom layout file is moved between machines or people, then the
1257 layout file needs to be exchanged as well.
1258 If that is not done, then we have a fallback implemented so that such documents
1259 can still be edited, but not exported, and the user gets a warning.
1263 \begin_layout Itemize
1264 The lyx2lyx script cannot do anything useful in such a case.
1268 \begin_layout Standard
1269 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1271 then, you should do the following:
1274 \begin_layout Enumerate
1275 Put your new layout file in
1276 \begin_inset Flex Code
1279 \begin_layout Plain Layout
1286 \begin_inset Flex Code
1289 \begin_layout Plain Layout
1290 git add lib/layouts/newlayout.layout
1295 ) so that it will be committed.
1298 \begin_layout Enumerate
1300 \begin_inset Flex Code
1303 \begin_layout Plain Layout
1309 , so that the new layout actually gets installed.
1312 \begin_layout Enumerate
1314 \begin_inset Flex Code
1317 \begin_layout Plain Layout
1318 lib/doc/LaTeXConfig.lyx
1323 containing in particular a line like
1331 \begin_layout Standard
1332 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1333 \begin_inset Flex Code
1336 \begin_layout Plain Layout
1337 info-insert textclass <name>
1343 This inset will automatically display a boxed
1344 \begin_inset Quotes eld
1348 \begin_inset Quotes erd
1352 \begin_inset Quotes eld
1356 \begin_inset Quotes erd
1359 depending on the availability of the package.
1363 \begin_layout Enumerate
1364 A template or example is strongly encouraged (but not necessarily required).
1365 It is also possible to provide both.
1367 \begin_inset Flex Code
1370 \begin_layout Plain Layout
1377 \begin_inset Flex Code
1380 \begin_layout Plain Layout
1389 \begin_layout Enumerate
1390 Reconfigure \SpecialChar LyX
1394 \begin_layout Enumerate
1395 Ensure the autotests for the new layout pass (see
1396 \begin_inset CommandInset ref
1398 reference "par:when-to-run-an-export-test"
1405 \begin_layout Section
1409 \begin_layout Standard
1410 Adding a new module is very similar to adding a new layout.
1411 Therefore, the previous section applies to new modules as well, with two
1415 \begin_layout Enumerate
1416 You only need to add an entry to
1417 \begin_inset Flex Code
1420 \begin_layout Plain Layout
1421 lib/doc/LaTeXConfig.lyx
1426 if the module requires a LaTeX package.
1427 In that case, the command for entering the InsetInfo is:
1428 \begin_inset Flex Code
1431 \begin_layout Plain Layout
1432 info-insert package <name>
1440 \begin_layout Enumerate
1441 Modules do not need a template, only an example, which is strongly encouraged
1442 but not necessarily required.
1445 \begin_layout Section
1446 Layouts for document classes with incompatible versions
1449 \begin_layout Standard
1450 \begin_inset Note Greyedout
1453 \begin_layout Description
1454 Note: This section is currently only a proposal under discussion.
1455 Please correct/amend as suited.
1456 Remove this note once a consensus is found.
1459 \begin_layout Plain Layout
1461 \begin_inset Quotes eld
1464 Proposal for a guide on updating layouts
1465 \begin_inset Quotes erd
1468 for details and background
1471 \begin_layout Plain Layout
1472 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1480 \begin_layout Standard
1481 Every now and then, there are changes to LaTeX document classes that break
1482 backwards compatibility.
1486 \begin_layout Plain Layout
1487 Uwe has suggested we implement automatic detection of changes in class files.
1488 This could be done by running a script every month that checks if a document
1489 class was changed at CTAN and at the homepages of the scientific journals.
1490 If it reports a change, we can check if our template and layout file are
1491 still usable with the changed document class.
1492 (This is different from the autotests insofar, as this would also catch
1493 changes that do not result in compilation errors.)
1498 Reasons can be a new name for the
1499 \begin_inset Flex Code
1502 \begin_layout Plain Layout
1508 file, removed \SpecialChar LaTeX
1510 How should this best be handled in \SpecialChar LyX
1514 \begin_layout Standard
1515 The idea is to support the new version with a new \SpecialChar LyX
1519 \begin_layout Itemize
1520 Existing documents can still be opened in \SpecialChar LyX
1521 and will continue to work on
1522 systems where the old version is still installed.
1526 \begin_layout Itemize
1527 With differently named
1528 \begin_inset Flex Code
1531 \begin_layout Plain Layout
1537 files, \SpecialChar LyX
1538 can check for the availability of the particular version and reflect
1540 Different document class versions with the same file name are currently
1541 (2.2.x) not detected by the configuration script.
1542 This is planned for 2.3.
1546 \begin_layout Plain Layout
1547 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1550 \begin_layout Plain Layout
1551 However, what we really need is version detection for the configuration,
1552 so that the user can be warned if the required class file has the wrong
1554 (If the class file keeps the name over the version change, only one of
1555 the two layout files generates compilable documents.)
1558 \begin_layout Plain Layout
1559 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1568 \begin_layout Itemize
1569 The new layout can be added both to the master and the stable branches,
1570 in accord with the policy discussed in
1571 \begin_inset CommandInset ref
1572 LatexCommand formatted
1573 reference "subsec:New-layouts"
1578 No lyx2lyx conversion is then required when a new major version is released.
1581 \begin_layout Standard
1582 The user can move an existing document to the new version simply by selecting
1583 a new document class.
1584 This step is well supported by \SpecialChar LyX
1585 , with established methods for handling
1586 unsupported styles and other changes.
1587 This way, no lyx2lyx code is required.
1590 \begin_layout Standard
1591 The steps to support a new version of an existing document class are thus:
1594 \begin_layout Itemize
1595 Create a new layout file including the upstream version in the name (avoid
1596 special characters like spaces and dots), e.g.
1598 \begin_inset Flex Code
1601 \begin_layout Plain Layout
1602 acmsiggraph-v0-92.layout
1610 \begin_layout Itemize
1611 Include the name of the
1612 \begin_inset Flex Code
1615 \begin_layout Plain Layout
1621 file as an optional argument in the
1622 \begin_inset Flex Code
1625 \begin_layout Plain Layout
1633 line and include the version number in the GUI name:
1634 \begin_inset Newline newline
1638 \begin_inset Flex Code
1641 \begin_layout Plain Layout
1644 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1645 \begin_inset space ~
1656 \begin_layout Itemize
1657 Update the GUI name in the old layout file (whose name should not be changed),
1659 \begin_inset Newline newline
1663 \begin_inset Flex Code
1666 \begin_layout Plain Layout
1669 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1670 \begin_inset space ~
1681 \begin_layout Itemize
1682 To avoid duplicate definitions, the new layout can
1683 \begin_inset Flex Code
1686 \begin_layout Plain Layout
1692 the old layout file and add\SpecialChar breakableslash
1693 remove\SpecialChar breakableslash
1694 obsolete\SpecialChar breakableslash
1695 modify settings and styles (similar
1697 \begin_inset Flex Code
1700 \begin_layout Plain Layout
1710 \begin_layout Standard
1711 It may be tempting to let the new layout be the
1712 \begin_inset Quotes eld
1716 \begin_inset Quotes erd
1719 and have the old layout import it.
1720 However, this should not be done because any changes to the new layout
1721 would need undo steps in the importing old layout.
1725 \begin_layout Itemize
1726 If the new LaTeX document class obsoletes the old one, update the example
1727 and template files to use the new layout.
1728 Add a note about the changes (preferably with a pointer to the documentation
1733 \begin_layout Standard
1734 This way, new documents based on the template or example will use the up-to-date
1735 document class version.
1739 \begin_layout Standard
1740 \begin_inset Newpage newpage
1746 \begin_layout Chapter
1750 \begin_layout Standard
1751 Automated tests are an important tool to detect bugs and regressions in
1752 software development.
1753 Some projects like gcc even require each bug fix to be accompanied by a
1754 test case for the automatic test suite, that would detect this bug.
1755 Testing interactive features automatically is of course very hard, but
1756 core functionality like document import and export can be tested quite
1757 easily, and some tests of this kind exist.
1760 \begin_layout Section
1764 \begin_layout Standard
1765 There are attempts to set up a suite of unit tests for LyX.
1768 \begin_layout Standard
1769 TODO: describe what is done and what is still to do.
1772 \begin_layout Section
1776 \begin_layout Standard
1777 The tex2lyx tests are located in the
1778 \begin_inset Flex Code
1781 \begin_layout Plain Layout
1787 subfolder of the \SpecialChar LyX
1788 source code distribution.
1789 The actual testing is performed by the simple python script
1790 \begin_inset Flex Code
1793 \begin_layout Plain Layout
1794 src/tex2lyx/test/runtests.py
1800 Each test consists of two files:
1801 \begin_inset Flex Code
1804 \begin_layout Plain Layout
1810 contains the \SpecialChar LaTeX
1811 code that should be tested.
1813 \begin_inset Flex Code
1816 \begin_layout Plain Layout
1822 contains the expected output of tex2lyx.
1823 When a test is run, the actual produced output is compared with the stored
1825 The test passes if both are identical.
1826 The test machinery is also able to generate a file
1827 \begin_inset Flex Code
1830 \begin_layout Plain Layout
1836 by exporting the produced .lyx file with \SpecialChar LyX
1838 This may be useful for roundtrip comparisons.
1841 \begin_layout Subsection
1845 \begin_layout Standard
1846 The tex2lyx tests can be run in several ways.
1848 \begin_inset Flex Code
1851 \begin_layout Plain Layout
1857 subfolder of the build directory, the commands
1858 \begin_inset Flex Code
1861 \begin_layout Plain Layout
1867 (cmake, all platforms),
1868 \begin_inset Flex Code
1871 \begin_layout Plain Layout
1877 (cmake, when using a make based build system and not MSVC) or
1878 \begin_inset Flex Code
1881 \begin_layout Plain Layout
1887 (autotools) will run the tex2lyx tests.
1888 Alternatively, in the root of the build directory, the command
1889 \begin_inset Flex Code
1892 \begin_layout Plain Layout
1898 runs all tests whose names match the regex
1899 \begin_inset Quotes eld
1903 \begin_inset Quotes erd
1907 Another way to run the tex2lyx tests in the root build directory is to
1908 instead use the command
1909 \begin_inset Flex Code
1912 \begin_layout Plain Layout
1913 ctest -L '(cmplyx|roundtrip)'
1918 , which runs all tests categorized with the label
1919 \begin_inset Quotes eld
1923 \begin_inset Quotes erd
1927 \begin_inset Quotes eld
1931 \begin_inset Quotes erd
1935 If a test fails, the differences between the expected and actual results
1936 are output in unified diff format.
1939 \begin_layout Subsection
1940 Updating test references
1941 \begin_inset CommandInset label
1943 name "sec:Updating-test-references"
1950 \begin_layout Standard
1951 In some cases a changed tex2lyx output is not a test failure, but wanted,
1953 \begin_inset space \thinspace{}
1957 \begin_inset space \space{}
1960 if a tex2lyx bug was fixed, or a new feature was added.
1961 In these cases the stored references need to be updated.
1962 To do so if using autotools, call
1963 \begin_inset Flex Code
1966 \begin_layout Plain Layout
1973 \begin_inset Flex Code
1976 \begin_layout Plain Layout
1982 subdirectory of the build directory.
1983 If instead using CMake, call
1984 \begin_inset Flex Code
1987 \begin_layout Plain Layout
1988 make updatetex2lyxtests
1993 in the build directory or in the
1994 \begin_inset Flex Code
1997 \begin_layout Plain Layout
2003 subdirectory of the build directory.
2007 \begin_layout Plain Layout
2008 Note that this is a case where a make target in the build directory can
2009 affect the source directory, which might not be advisable.
2014 On Windows do the following:
2017 \begin_layout Itemize
2018 Assure that the path to the python.exe is in your system PATH variable.
2021 \begin_layout Itemize
2022 Double-click on the file
2023 \begin_inset Flex Code
2026 \begin_layout Plain Layout
2027 updatetex2lyxtests.vcxproj
2032 in the build directory or in the
2033 \begin_inset Flex Code
2036 \begin_layout Plain Layout
2042 subdirectory of your build directory.
2045 \begin_layout Itemize
2046 In the appearing MSVC program assure that you build the
2050 version, then right-click on the project
2054 in the project explorer and choose then
2057 \begin_inset space ~
2060 Only\SpecialChar menuseparator
2062 \begin_inset space ~
2070 \begin_layout Standard
2071 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2073 Please examine the changed output carefully before committing the changed
2074 files to the repository: Since the test machinery does not do a roundtrip
2076 \begin_inset Formula $\Rightarrow$
2080 \begin_inset Formula $\Rightarrow$
2083 .tex, and does not compare the produced dvi or pdf output, it assumes that
2084 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2086 There is only one chance to detect wrong output: before committing a new
2088 Once it is committed, it is quite difficult to verify whether it is correct.
2091 \begin_layout Standard
2096 update the test references by opening them with \SpecialChar LyX
2097 or directly running lyx2lyx
2099 This would not work, since lyx2lyx and \SpecialChar LyX
2100 produce slightly different files
2101 regarding insignificant whitespace and line breaks.
2104 \begin_layout Subsection
2108 \begin_layout Standard
2109 In many cases tests for new features may be added to one of the existing
2110 test files, but sometimes this is not possible or not wanted.
2111 Then a new test file needs to be added:
2114 \begin_layout Enumerate
2116 \begin_inset Flex Code
2119 \begin_layout Plain Layout
2120 src/tex2lyx/test/<test name>.tex
2125 and run tex2lyx in roundtrip mode to produce the file
2126 \begin_inset Flex Code
2129 \begin_layout Plain Layout
2130 src/tex2lyx/test/<test name>.lyx.lyx
2136 This file will be the new reference.
2139 \begin_layout Enumerate
2140 Once you confirmed that the tex2lyx output is correct, add the new files
2141 to the corresponding lists in
2142 \begin_inset Flex Code
2145 \begin_layout Plain Layout
2146 src/tex2lyx/test/runtests.py
2152 \begin_inset Flex Code
2155 \begin_layout Plain Layout
2156 src/tex2lyx/Makefile.am
2162 \begin_inset Flex Code
2165 \begin_layout Plain Layout
2166 src/tex2lyx/test/CMakeLists.txt
2174 \begin_layout Enumerate
2175 Commit the changes to the repository, or send a patch to the development
2176 list and ask for committing if you do not have commit rights.
2179 \begin_layout Section
2180 ctest automatic tests
2183 \begin_layout Standard
2184 Some tests are located in the
2185 \begin_inset Flex Code
2188 \begin_layout Plain Layout
2189 development/autotests/
2194 subfolder of the \SpecialChar LyX
2195 source code distribution.
2200 \begin_layout Plain Layout
2201 The README document in this folder only describes the
2202 \begin_inset Quotes eld
2206 \begin_inset Quotes erd
2209 subset of autotests!
2217 \begin_layout Standard
2218 These tests can be run by the commands
2219 \begin_inset Flex Code
2222 \begin_layout Plain Layout
2232 (all platforms) or (when using a make based build system and not MSVC)
2234 \begin_inset Flex Code
2237 \begin_layout Plain Layout
2244 \begin_inset Flex Code
2247 \begin_layout Plain Layout
2258 The test logs are written to the
2259 \begin_inset Flex Code
2262 \begin_layout Plain Layout
2276 \begin_layout Subsection
2280 \begin_layout Standard
2281 The export tests are integration tests.
2282 They take longer to run and are more likely to break than the tex2lyx tests.
2283 Nevertheless, they have caught many regressions and without a better alternativ
2284 e it is important to keep them up-to-date and understand how they work.
2287 \begin_layout Standard
2289 \begin_inset Quotes eld
2293 \begin_inset Quotes erd
2296 documentation, template, and example documents.
2297 In addition, there are a number of dedicated sample documents in the
2298 \begin_inset Flex Code
2301 \begin_layout Plain Layout
2307 subfolder of the \SpecialChar LyX
2308 source code distribution.
2309 All samples are (after copying and eventual processing by scripts) exported
2310 to various output formats via the
2311 \begin_inset Flex Code
2314 \begin_layout Plain Layout
2320 command line option.
2321 The tests checks for errors reported by LyX.
2322 (However, error-free export is no guarantee for an error-free output document.)
2325 \begin_layout Subsubsection
2326 \begin_inset CommandInset label
2328 name "par:when-to-run-an-export-test"
2332 Expectations of LyX developers
2335 \begin_layout Standard
2336 Because the export tests are integration tests and take a long time to run,
2337 LyX developers are rarely expected to run all of the tests.
2338 Here are some good practices to follow by developers:
2341 \begin_layout Itemize
2342 When making a non-trivial change to a .layout file, run the export and layout
2343 tests corresponding with that .layout file.
2346 \begin_layout Itemize
2347 When making non-trivial changes to a .lyx file, run the export tests correspondin
2348 g to that .lyx file.
2353 \begin_layout Plain Layout
2354 This rule is due to revision.
2358 \begin_layout Plain Layout
2359 There is an objection from the documentation maintainer that working on
2360 the documentation must not be complicated by having to consider non-standard
2364 \begin_layout Itemize
2365 successful compiling/testing an edited documentation file with pdflatex
2366 suffices to ensure it can be commited, not tests with other exports are
2370 \begin_layout Plain Layout
2371 If sudden failures with other exports due to “half-tested” documentation
2372 updates are a problem for the test maintainer, the test suite should use
2376 \begin_layout Itemize
2377 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2380 \begin_layout Itemize
2381 updated regularely (but on a time chosen by the test suite maintainer) from
2382 the originals in lib/doc/
2385 \begin_layout Plain Layout
2389 \begin_layout Itemize
2390 no test will fail due to ongoing work on documentation,
2393 \begin_layout Itemize
2394 the documentation is still tested in full (with some delay),
2397 \begin_layout Itemize
2398 failures with non-default export can be examined and handled accordingly
2399 in one run with the cache update,
2402 \begin_layout Itemize
2403 “interesting failures” (like the nested-language+polyglossia problem in
2404 es/Customization can be separated and moved into dedicated test samples.
2412 \begin_layout Itemize
2413 When making non-trivial changes to LyX's \SpecialChar LaTeX
2415 touching the encoding code or package handling code that you expect will
2416 change the exported \SpecialChar LaTeX
2421 \begin_layout Standard
2422 \paragraph_spacing single
2423 Consider running all of the export tests before and after your change.
2424 If there are differences, please reconcile these (i.e.
2425 fix the bug or fix the tests)
2430 Ask for help if you're not sure what to.
2433 \begin_layout Standard
2434 If you do not want to run the tests,
2437 \begin_layout Itemize
2438 post the patch on the list and others will run the tests and eventually
2442 \begin_layout Itemize
2443 commit, but be prepared to fix eventually arising problems or to revert
2444 the commit if there is no easy fix.
2448 \begin_layout Itemize
2449 Understand how to interpret test failures.
2450 If your commit is found to have broken a test, you should be able to interpret
2451 the test results when made aware of them.
2453 \begin_inset CommandInset ref
2455 reference "subsec:Interpreting-export-tests"
2462 \begin_layout Subsubsection
2463 \begin_inset CommandInset label
2465 name "par:export-test-output-formats"
2472 \begin_layout Standard
2473 The following output formats are currently tested for each sample document
2475 \begin_inset CommandInset ref
2477 reference "par:Export-test-filtering"
2484 \begin_layout Labeling
2485 \labelwidthstring 00.00.0000
2490 \begin_layout Labeling
2491 \labelwidthstring 00.00.0000
2492 lyx16 LyX 1.6 file format (lyx2lyx)
2495 \begin_layout Labeling
2496 \labelwidthstring 00.00.0000
2497 lyx21 LyX 2.1 file format (lyx2lyx)
2500 \begin_layout Labeling
2501 \labelwidthstring 00.00.0000
2502 xhtml LyXHTML (native LyX HTML export)
2506 \begin_layout Labeling
2507 \labelwidthstring 00.00.0000
2509 \begin_inset space ~
2513 \begin_inset space ~
2520 \begin_layout Labeling
2521 \labelwidthstring pdf5msystemFM
2522 dvi DVI (8-bit latex)
2525 \begin_layout Labeling
2526 \labelwidthstring pdf5msystemFM
2527 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2530 \begin_layout Labeling
2531 \labelwidthstring pdf5msystemFM
2532 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2535 \begin_layout Labeling
2536 \labelwidthstring pdf5msystemFM
2540 \begin_layout Labeling
2541 \labelwidthstring pdf5msystemFM
2542 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2545 \begin_layout Labeling
2546 \labelwidthstring pdf5msystemFM
2547 pdf4_systemF PDF (XeTeX with Unicode fonts)
2550 \begin_layout Labeling
2551 \labelwidthstring pdf5msystemFM
2552 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2555 \begin_layout Labeling
2556 \labelwidthstring pdf5msystemFM
2557 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2561 \begin_layout Labeling
2562 \labelwidthstring 00.00.0000
2564 \begin_inset space ~
2568 \begin_inset space ~
2572 \begin_inset space ~
2576 \begin_inset space ~
2583 \begin_layout Labeling
2584 \labelwidthstring pdf5msystemFM
2585 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2588 \begin_layout Labeling
2589 \labelwidthstring pdf5msystemFM
2590 pdf3 DVI -> PDF (dvipdfm)
2594 \begin_layout Labeling
2595 \labelwidthstring 00.00.0000
2597 \begin_inset space ~
2600 tested: (or only if set as default output format in the document source)
2604 \begin_layout Labeling
2605 \labelwidthstring pdf5msystemFM
2609 \begin_layout Labeling
2610 \labelwidthstring pdf5msystemFM
2611 luatex LaTeX (LuaTeX)
2614 \begin_layout Labeling
2615 \labelwidthstring pdf5msystemFM
2616 dviluatex LaTeX (dviluatex)
2619 \begin_layout Labeling
2620 \labelwidthstring pdf5msystemFM
2621 pdflatex LaTeX (pdflatex)
2624 \begin_layout Labeling
2625 \labelwidthstring pdf5msystemFM
2626 platex LaTeX (pLaTeX)
2629 \begin_layout Labeling
2630 \labelwidthstring pdf5msystemFM
2634 \begin_layout Labeling
2635 \labelwidthstring pdf5msystemFM
2636 eps3 EPS (encapsulated Postscript) (cropped)
2639 \begin_layout Labeling
2640 \labelwidthstring pdf5msystemFM
2641 ps DVI -> Postscript (dvips)
2644 \begin_layout Labeling
2645 \labelwidthstring pdf5msystemFM
2649 \begin_layout Labeling
2650 \labelwidthstring pdf5msystemFM
2651 text (nor text2, ..., text4)
2654 \begin_layout Labeling
2655 \labelwidthstring pdf5msystemFM
2659 \begin_layout Labeling
2660 \labelwidthstring pdf5msystemFM
2664 \begin_layout Labeling
2665 \labelwidthstring pdf5msystemFM
2669 \begin_layout Labeling
2670 \labelwidthstring pdf5msystemFM
2675 \begin_layout Subsubsection
2676 \begin_inset CommandInset label
2678 name "par:Configuring-ctests"
2682 Configuring the tests
2685 \begin_layout Standard
2686 To enable the export autotests, add the
2687 \begin_inset Flex Code
2690 \begin_layout Plain Layout
2691 -DLYX_ENABLE_EXPORT_TESTS=ON
2700 \begin_layout Standard
2701 \begin_inset Flex Code
2704 \begin_layout Plain Layout
2705 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2713 \begin_layout Standard
2715 This flag will increase the time for the cmake command by several seconds,
2716 mainly because of the process of inverting tests (see Section
2717 \begin_inset CommandInset ref
2719 reference "subsec:Interpreting-export-tests"
2726 \begin_layout Subsubsection
2727 \begin_inset CommandInset label
2729 name "par:ctest-options"
2736 \begin_layout Standard
2737 To run all tests, in the build directory simply run the command
2738 \begin_inset Flex Code
2741 \begin_layout Plain Layout
2748 A full, up-to-date TeXLive installation is recommended to run the tests.
2749 Otherwise, some tests will fail.
2750 Tests with additional requirements are labeled
2751 \begin_inset Quotes eld
2754 unreliable:nonstandard
2755 \begin_inset Quotes erd
2762 \begin_layout Standard
2763 To run only some of the tests, use command line options (see examples below):
2766 \begin_layout Labeling
2767 \labelwidthstring -R
2768 \begin_inset Flex Code
2771 \begin_layout Plain Layout
2777 Run only the tests whose names match the given regular expression.
2780 \begin_layout Labeling
2781 \labelwidthstring -R
2782 \begin_inset Flex Code
2785 \begin_layout Plain Layout
2791 Run only the tests whose labels match the given regular expression.
2792 A test may have more that one label.
2796 \begin_layout Labeling
2797 \labelwidthstring -R
2798 \begin_inset Flex Code
2801 \begin_layout Plain Layout
2807 Exclude the tests whose names match the given regular expression.
2810 \begin_layout Labeling
2811 \labelwidthstring -R
2812 \begin_inset Flex Code
2815 \begin_layout Plain Layout
2821 Exclude the tests whose labels match the given regular expression.
2822 Cannot be combined with
2823 \begin_inset Flex Code
2826 \begin_layout Plain Layout
2835 \begin_layout Standard
2836 The following options help to find good selection patterns:
2839 \begin_layout Labeling
2840 \labelwidthstring -R
2841 \begin_inset Flex Code
2844 \begin_layout Plain Layout
2850 List the tests that would be run but not actually run them.
2855 \begin_layout Standard
2856 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2857 to know how many tests there are or whether your
2858 \begin_inset Flex Code
2861 \begin_layout Plain Layout
2867 regular expression did what you expected.
2871 \begin_layout Labeling
2872 \labelwidthstring -R
2873 \begin_inset Flex Code
2876 \begin_layout Plain Layout
2877 \SpecialChar nobreakdash
2878 \SpecialChar nobreakdash
2884 print the list of all labels associated with the test set.
2885 Can also be combined with -R, -L, -E, ...
2889 \begin_layout Standard
2890 Other useful options are:
2893 \begin_layout Labeling
2894 \labelwidthstring -R
2895 \begin_inset Flex Code
2898 \begin_layout Plain Layout
2904 Run the tests in parallel using the given number of jobs.
2908 \begin_layout Standard
2909 We are still working on getting the tests to run in parallel.
2910 However, when running the tests in parallel, sometimes tests fail that
2911 pass when run sequentially.
2912 A reasonable approach is to first run the tests in parallel and then run
2913 the failed tests sequentially.
2916 \begin_layout Standard
2917 For example, to run 8 jobs at a time:
2920 \begin_layout Standard
2921 \begin_inset Flex Code
2924 \begin_layout Plain Layout
2933 \begin_layout Standard
2934 \begin_inset Flex Code
2937 \begin_layout Plain Layout
2938 ctest \SpecialChar nobreakdash
2939 \SpecialChar nobreakdash
2948 \begin_layout Standard
2949 When specifying a subset of the tests (e.g.
2951 \begin_inset Flex Code
2954 \begin_layout Plain Layout
2955 \SpecialChar nobreakdash
2961 ), the same subset must be specified when using the
2962 \begin_inset Flex Code
2965 \begin_layout Plain Layout
2966 \SpecialChar nobreakdash
2967 \SpecialChar nobreakdash
2973 option because it is the test numbers that are used to index which tests
2974 failed on the previous run.
2977 \begin_layout Standard
2979 Note that some tests cannot be run in parallel.
2980 These tests are marked in the code with the
2981 \begin_inset Flex Code
2984 \begin_layout Plain Layout
2994 \begin_layout Labeling
2995 \labelwidthstring -R
2996 \begin_inset Flex Code
2999 \begin_layout Plain Layout
3000 \SpecialChar nobreakdash
3001 \SpecialChar nobreakdash
3007 Set a global timeout on all tests that do not already have a timeout set
3012 \begin_layout Standard
3013 There have been bugs in LyX and in \SpecialChar LaTeX
3014 which cause compilation to hang, and
3015 without a timeout a test might never stop (in one case there was even a
3017 If a test times out, the
3018 \begin_inset Flex Code
3021 \begin_layout Plain Layout
3027 command exits with error, but you can distinguish between a timed out test
3028 and a failed test in the output reported at the end of the
3029 \begin_inset Flex Code
3032 \begin_layout Plain Layout
3042 \begin_layout Standard
3044 \begin_inset Flex Code
3047 \begin_layout Plain Layout
3053 ) the full list of command line options.
3056 \begin_layout Subsubsection
3060 \begin_layout Itemize
3061 run only the export tests:
3062 \begin_inset Flex Code
3065 \begin_layout Plain Layout
3074 \begin_layout Itemize
3076 \begin_inset Flex Code
3079 \begin_layout Plain Layout
3080 ctest -L "inverted|suspended"
3088 \begin_layout Itemize
3089 list all export tests which match any of the labelling patterns:
3090 \begin_inset Flex Code
3093 \begin_layout Plain Layout
3104 \begin_layout Itemize
3105 exclude rarely used output formats and post-processing tests
3106 \begin_inset Flex Code
3109 \begin_layout Plain Layout
3110 ctest -L export -E "_(texF|dvi3|pdf3?)"
3118 \begin_layout Subsubsection
3119 \begin_inset CommandInset label
3121 name "subsec:Interpreting-export-tests"
3125 Interpreting the export test results
3128 \begin_layout Standard
3129 A test can fail for several reasons, not all of them bad.
3132 \begin_layout Enumerate
3133 A new or edited sample document may be incompatible with some output formats.
3136 \begin_layout Enumerate
3137 A dependency is not met (e.g.
3138 the \SpecialChar LaTeX
3140 One hint that this is the case is that the corresponding
3141 \begin_inset Flex Code
3144 \begin_layout Plain Layout
3150 test will likely also fail.
3153 \begin_layout Enumerate
3154 An inverted test fails to fail (i.e.
3155 export that previously failed now works).
3158 \begin_layout Enumerate
3159 An external dependency was updated (e.g.
3164 \begin_layout Enumerate
3165 A recent code change introduced a bug.
3168 \begin_layout Enumerate
3169 \begin_inset CommandInset label
3175 A change in a document exposed a previously unknown bug or an incompatibility
3176 with an export format (e.g.
3177 Lua\SpecialChar LaTeX
3181 \begin_layout Standard
3182 Because the .lyx files are exported in several formats, it is not surprising
3183 that many of the exports fail.
3184 This expectation of failure is addressed by
3185 \begin_inset Quotes eld
3189 \begin_inset Quotes erd
3192 the tests, that is, by marking the test as
3193 \begin_inset Quotes eld
3197 \begin_inset Quotes erd
3200 if the export exits with error and as
3201 \begin_inset Quotes eld
3205 \begin_inset Quotes erd
3208 if the export succeeds
3213 It follows that these expected failures will not show up as failed tests
3214 in the test results and thus will not pollute the
3215 \begin_inset Quotes eld
3219 \begin_inset Quotes erd
3223 If the export actually succeeds, then the test will fail.
3224 The purpose of this failure is to get your attention—something has changed,
3225 possibly for the better.
3228 \begin_layout Standard
3229 We try to document why a test is inverted or ignored.
3230 See the comment (prefixed with
3231 \begin_inset Flex Code
3234 \begin_layout Plain Layout
3240 ) above the block in which the test is listed as inverted or ignored in
3242 \begin_inset Flex Code
3245 \begin_layout Plain Layout
3246 development/autotests/invertedTests
3252 \begin_inset Flex Code
3255 \begin_layout Plain Layout
3256 development/autotests/unreliableTests
3262 \begin_inset Flex Code
3265 \begin_layout Plain Layout
3266 development/autotests/ignoredTests
3275 \begin_layout Standard
3276 A good question is why do we enable the tests for non-default formats? The
3277 answer is that if a non-default route is broken it is often because a bug
3278 was introduced in LyX and not because a document-specific change was made
3279 that is not supported by the route.
3280 In other words, there is a high signal/noise ratio in the export tests
3281 for some non-default formats.
3285 \begin_layout Standard
3286 When a test or several tests fail, consider checking the files in the
3287 \begin_inset Flex Code
3290 \begin_layout Plain Layout
3296 subdirectory of your build directory.
3297 In this subdirectory are three files: the file
3298 \begin_inset Flex Code
3301 \begin_layout Plain Layout
3307 simply lists the tests that failed on your last
3308 \begin_inset Flex Code
3311 \begin_layout Plain Layout
3318 \begin_inset Flex Code
3321 \begin_layout Plain Layout
3327 file contains the output from the tests (and often has details explaining
3328 why a test failed); and the
3329 \begin_inset Flex Code
3332 \begin_layout Plain Layout
3338 file lists the times that it took to run the tests.
3341 \begin_layout Subsubsection
3342 What action should you take if a test fails?
3345 \begin_layout Standard
3346 \paragraph_spacing single
3347 It is always good to check manually why something fails and if it passes
3348 if the PDF output is good.
3351 \begin_layout Itemize
3352 Generally, if a change breaks compilation for the target format (for the
3353 manuals pdf2) without solving some important other issue,
3355 fix or revert the commit
3357 that led to failure.
3360 \begin_layout Itemize
3361 If it is not possible to (immediately) fix the failure but there are reasons
3362 not to revert the commit (e.g.
3363 it fixes another more important issue),
3367 the failing test case (see
3368 \begin_inset CommandInset ref
3370 reference "par:Inverted-tests"
3377 \begin_layout Itemize
3382 test case fails because the export now works, first confirm that the output
3383 of the corresponding export looks good (e.g., not garbled text).
3388 the test by removing the pattern from the
3389 \begin_inset Quotes eld
3393 \begin_inset Quotes erd
3397 \begin_inset CommandInset ref
3399 reference "par:Inverted-tests"
3406 \begin_layout Itemize
3407 If the export did not fail previously but led to wrong output (PDF, say),
3411 \begin_layout Plain Layout
3412 Non-failing test with wrong output should be labeled as
3413 \begin_inset Quotes eld
3416 unreliable:wrong_output
3417 \begin_inset Quotes erd
3421 \begin_inset CommandInset ref
3423 reference "par:Unreliable-tests"
3432 it is in fact an improvement when the test now fails.
3437 the failing test case (see
3438 \begin_inset CommandInset ref
3440 reference "par:Inverted-tests"
3447 \begin_layout Itemize
3448 In case of tests failing due to missing requirements (tests labeled
3449 \begin_inset Quotes eld
3452 unreliable:nonstandard
3453 \begin_inset Quotes erd
3456 or testing on a system with only a subset of TeXLive installed), ignore
3457 the failure, ask for someone else to run the test, or install the missing
3458 resources and try again.
3461 \begin_layout Itemize
3462 Check the log file Testing/Temporary/LastTest.log.
3463 In case of latex-errors rerun the failing test with environment variable
3464 'LYX_DEBUG_LATEX' set to '1'.
3465 This will include latex messages in LastTest.log, so it should be easier
3466 to interpret the fail-reason.
3469 \begin_layout Subsubsection
3470 \begin_inset CommandInset label
3472 name "par:Inverted-tests"
3479 \begin_layout Standard
3480 Test cases whose name matches a pattern in the file
3481 \begin_inset Flex Code
3484 \begin_layout Plain Layout
3485 development/autotests/invertedTests
3495 They get also the test property
3496 \begin_inset Flex Code
3499 \begin_layout Plain Layout
3506 they are reported as failing if the export works without error
3507 \begin_inset Flex URL
3510 \begin_layout Plain Layout
3512 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3520 \begin_layout Standard
3521 Add failing cases to this file, if they cannot be solved
3522 \begin_inset Quotes eld
3526 \begin_inset Quotes erd
3529 but it is expected that the export will work in a foreseeable future, e.g.
3530 low priority issues like failures to export to a non-target format (for
3531 the manuals everything except pdf2).
3534 \begin_layout Standard
3535 The following sublabels are currently present in
3536 \begin_inset Flex Code
3539 \begin_layout Plain Layout
3548 \begin_layout Description
3549 todo test failures that require attention:
3553 \begin_layout Itemize
3554 minor issues to explore and properly sort later,
3557 \begin_layout Itemize
3561 \begin_layout Itemize
3562 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3566 \begin_layout Description
3567 lyxbugs LyX bugs with a Trac number.
3570 \begin_layout Description
3571 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3575 \begin_layout Standard
3576 "Wontfix" if demonstrating correct use and OK in the default output format.
3580 \begin_layout Description
3581 texissues Export fails due to LaTeX limitations like non-ASCII characters
3582 in verbatim or listings, incompatible packages, ...
3586 \begin_layout Standard
3587 "Wontfix" if documents demonstrate correct use in the default output format:
3590 \begin_layout Itemize
3591 If the source can be made more robust without becoming "hackish", fix the
3595 \begin_layout Itemize
3596 if LyX could be enhanced to care for a permanent TeX limitation, file a
3597 ticket at trac and add a pattern under lyxbugs,
3600 \begin_layout Itemize
3601 otherwise, add a pattern here.
3605 \begin_layout Description
3606 attic Documents in the attic (kept for reference and format conversion test).
3608 \begin_inset Quotes eld
3612 \begin_inset Quotes erd
3618 \begin_layout Paragraph
3622 \begin_layout Standard
3623 Test cases whose name additionally matches a pattern in the file
3624 \begin_inset Flex Code
3627 \begin_layout Plain Layout
3628 development/autotests/suspendedTests
3646 This means they are not executed using
3647 \begin_inset Flex Code
3650 \begin_layout Plain Layout
3657 \begin_inset Flex Code
3660 \begin_layout Plain Layout
3667 However, they also get the test property
3668 \begin_inset Flex Code
3671 \begin_layout Plain Layout
3678 they are reported as failing if the export works without error.
3679 From time to time they still have to be checked using
3680 \begin_inset Flex Code
3683 \begin_layout Plain Layout
3692 \begin_layout Standard
3693 These tests are suspended, because the export fails for known reasons which
3694 cannot ATM be resolved.
3695 But it is expected the reason might disappear in the future.
3696 Be it new TL or better handling in \SpecialChar LyX
3700 \begin_layout Standard
3701 For ctest commands without the
3702 \begin_inset Flex Code
3705 \begin_layout Plain Layout
3711 parameter nothing changes.
3712 Suspended or not, tests will be executed depending only on the selecting
3713 regular expression given to the ctest command (see
3714 \begin_inset CommandInset ref
3716 reference "par:ctest-options"
3723 \begin_layout Subsubsection
3724 \begin_inset CommandInset label
3726 name "par:Unreliable-tests"
3733 \begin_layout Standard
3734 Test cases whose name matches a pattern in the file
3735 \begin_inset Flex Code
3738 \begin_layout Plain Layout
3739 development/autotests/unreliableTests
3751 \begin_layout Standard
3752 These tests are not executed using
3753 \begin_inset Flex Code
3756 \begin_layout Plain Layout
3763 \begin_inset Flex Code
3766 \begin_layout Plain Layout
3776 \begin_layout Standard
3777 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3778 or pass but should rather fail (wrong output).
3780 \begin_inset Note Note
3783 \begin_layout Plain Layout
3784 *invalid* tests (wrong output) are not *unreliable*.
3785 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3794 \begin_layout Standard
3795 The following sublabels are currently present in
3796 \begin_inset Flex Code
3799 \begin_layout Plain Layout
3808 \begin_layout Description
3809 nonstandard Documents with additional requirements, e.g.
3810 a class or package file not in TeXLive.
3812 \begin_inset Note Note
3815 \begin_layout Plain Layout
3817 \begin_inset Quotes eld
3821 \begin_inset Quotes erd
3825 \begin_inset Quotes eld
3829 \begin_inset Quotes erd
3840 \begin_layout Description
3841 erratic Tests depending on local configuration or the phase of the moon.
3845 \begin_layout Description
3846 varying_versions Tests depending on e.g.
3847 OS or version of a non-TeX-Live dependency.
3848 Note that a full, up-to-date TeX Live installation is required so this
3849 sublabel is about versions of other dependencies.
3852 \begin_layout Description
3854 \begin_inset space ~
3857 output Export does not fail but the resulting document has (undetected)
3862 \begin_layout Standard
3863 \paragraph_spacing single
3864 \begin_inset Note Note
3867 \begin_layout Plain Layout
3868 \paragraph_spacing single
3869 These tests are in a strict sense not unreliable but
3873 (not measuring what they should measure).
3882 \begin_layout Subsubsection
3883 \begin_inset CommandInset label
3885 name "par:Export-test-filtering"
3889 Export test filtering
3892 \begin_layout Standard
3893 The assignment of a label to a test is controlled by a set of files with
3894 regular expressions that are matched against the test names.
3897 \begin_layout Description
3898 ignoredTests (small file)
3899 \begin_inset Newline newline
3902 Tests selected here are withdrawn in the configuration step (cf.
3904 \begin_inset CommandInset ref
3906 reference "par:Configuring-ctests"
3914 \begin_layout Labeling
3915 \labelwidthstring 00.00.0000
3916 Input Test of any export combination
3919 \begin_layout Labeling
3920 \labelwidthstring 00.00.0000
3921 Output Stop if tests not selected here
3925 \begin_layout Description
3926 unreliableTests: Tests selected pass or fail dependent on the system where
3928 Selected tests gain the label 'unreliable'.
3932 \begin_layout Labeling
3933 \labelwidthstring 00.00.0000
3934 Input Each test which passed 'ignoredTests'
3937 \begin_layout Labeling
3938 \labelwidthstring 00.00.0000
3939 Output Gain label 'unreliable', proceed with checking for 'inverted'.
3943 \begin_layout Description
3945 \begin_inset space \space{}
3952 \begin_layout Labeling
3953 \labelwidthstring 00.00.0000
3954 Input Each test which passed 'ignoredTests'
3957 \begin_layout Labeling
3958 \labelwidthstring 00.00.0000
3959 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3960 tests are reported as failing if the export works without error.) If no
3961 subselection applies, gain labels 'export' and 'inverted'.
3964 \begin_layout Standard
3965 The following filter perfoms a subselection of 'invertedTests':
3968 \begin_layout Description
3969 suspendedTests Tests selected here gain the label 'suspended' but _not_
3970 'export' or 'inverted', although in ctest they remain inverted.
3971 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3975 \begin_layout Labeling
3976 \labelwidthstring 00.00.0000
3977 Input Each test selected by 'invertedTests'
3980 \begin_layout Labeling
3981 \labelwidthstring 00.00.0000
3982 Output Selected test gains label 'suspended'.
3988 \begin_layout Standard
3989 The following table may clarify label assignement
3992 \begin_layout Standard
3993 \begin_inset space \hspace{}
3998 \begin_inset Tabular
3999 <lyxtabular version="3" rows="6" columns="8">
4000 <features tabularvalignment="middle">
4001 <column alignment="left" valignment="top" width="2cm">
4002 <column alignment="left" valignment="top" width="2.5cm">
4003 <column alignment="left" valignment="top" width="2cm">
4004 <column alignment="center" valignment="top" width="2.5cm">
4005 <column alignment="center" valignment="top">
4006 <column alignment="center" valignment="top">
4007 <column alignment="center" valignment="top">
4008 <column alignment="center" valignment="top">
4010 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4013 \begin_layout Plain Layout
4014 Test matching pattern in file:
4019 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4022 \begin_layout Plain Layout
4028 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4031 \begin_layout Plain Layout
4037 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4040 \begin_layout Plain Layout
4046 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4049 \begin_layout Plain Layout
4055 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4058 \begin_layout Plain Layout
4064 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4067 \begin_layout Plain Layout
4073 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4076 \begin_layout Plain Layout
4084 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4087 \begin_layout Plain Layout
4088 ignored\SpecialChar softhyphen
4094 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4097 \begin_layout Plain Layout
4098 unreliable\SpecialChar softhyphen
4104 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4107 \begin_layout Plain Layout
4108 inverted\SpecialChar softhyphen
4114 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4117 \begin_layout Plain Layout
4118 suspended\SpecialChar softhyphen
4124 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4127 \begin_layout Plain Layout
4133 <cell alignment="center" valignment="top" topline="true" usebox="none">
4136 \begin_layout Plain Layout
4142 <cell alignment="center" valignment="top" topline="true" usebox="none">
4145 \begin_layout Plain Layout
4151 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4154 \begin_layout Plain Layout
4162 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4165 \begin_layout Plain Layout
4171 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4174 \begin_layout Plain Layout
4180 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4183 \begin_layout Plain Layout
4189 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4192 \begin_layout Plain Layout
4198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4201 \begin_layout Plain Layout
4207 <cell alignment="center" valignment="top" topline="true" usebox="none">
4210 \begin_layout Plain Layout
4216 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4219 \begin_layout Plain Layout
4225 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4228 \begin_layout Plain Layout
4236 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4239 \begin_layout Plain Layout
4245 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4248 \begin_layout Plain Layout
4250 \begin_inset Newline newline
4254 \begin_inset Newline newline
4262 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4265 \begin_layout Plain Layout
4271 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4274 \begin_layout Plain Layout
4280 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4283 \begin_layout Plain Layout
4289 <cell alignment="center" valignment="top" topline="true" usebox="none">
4292 \begin_layout Plain Layout
4298 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4301 \begin_layout Plain Layout
4307 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4310 \begin_layout Plain Layout
4318 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4321 \begin_layout Plain Layout
4327 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4330 \begin_layout Plain Layout
4336 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4339 \begin_layout Plain Layout
4345 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4348 \begin_layout Plain Layout
4354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4357 \begin_layout Plain Layout
4363 <cell alignment="center" valignment="top" topline="true" usebox="none">
4366 \begin_layout Plain Layout
4372 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4375 \begin_layout Plain Layout
4381 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4384 \begin_layout Plain Layout
4392 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4395 \begin_layout Plain Layout
4401 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4404 \begin_layout Plain Layout
4410 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4413 \begin_layout Plain Layout
4419 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4422 \begin_layout Plain Layout
4428 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4431 \begin_layout Plain Layout
4437 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4440 \begin_layout Plain Layout
4446 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4449 \begin_layout Plain Layout
4455 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4458 \begin_layout Plain Layout
4472 \begin_layout Standard
4473 \begin_inset Note Note
4476 \begin_layout Plain Layout
4478 \begin_inset Quotes eld
4482 \begin_inset Quotes erd
4485 filter, this would be far less complicated:
4488 \begin_layout Plain Layout
4489 \begin_inset Tabular
4490 <lyxtabular version="3" rows="6" columns="7">
4491 <features tabularvalignment="middle">
4492 <column alignment="left" valignment="top" width="0pt">
4493 <column alignment="left" valignment="top" width="0pt">
4494 <column alignment="left" valignment="top" width="0pt">
4495 <column alignment="center" valignment="top">
4496 <column alignment="center" valignment="top">
4497 <column alignment="center" valignment="top">
4498 <column alignment="center" valignment="top">
4500 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4503 \begin_layout Plain Layout
4504 Test matching pattern in file:
4509 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4512 \begin_layout Plain Layout
4518 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4521 \begin_layout Plain Layout
4527 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4530 \begin_layout Plain Layout
4536 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4539 \begin_layout Plain Layout
4545 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4548 \begin_layout Plain Layout
4554 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4557 \begin_layout Plain Layout
4565 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4568 \begin_layout Plain Layout
4574 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4577 \begin_layout Plain Layout
4583 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4586 \begin_layout Plain Layout
4592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4595 \begin_layout Plain Layout
4601 <cell alignment="center" valignment="top" topline="true" usebox="none">
4604 \begin_layout Plain Layout
4610 <cell alignment="center" valignment="top" topline="true" usebox="none">
4613 \begin_layout Plain Layout
4619 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4622 \begin_layout Plain Layout
4630 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4633 \begin_layout Plain Layout
4639 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4642 \begin_layout Plain Layout
4648 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4651 \begin_layout Plain Layout
4657 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4660 \begin_layout Plain Layout
4666 <cell alignment="center" valignment="top" topline="true" usebox="none">
4669 \begin_layout Plain Layout
4675 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4678 \begin_layout Plain Layout
4684 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4687 \begin_layout Plain Layout
4695 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4698 \begin_layout Plain Layout
4704 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4707 \begin_layout Plain Layout
4713 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4716 \begin_layout Plain Layout
4722 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4725 \begin_layout Plain Layout
4731 <cell alignment="center" valignment="top" topline="true" usebox="none">
4734 \begin_layout Plain Layout
4740 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4743 \begin_layout Plain Layout
4749 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4752 \begin_layout Plain Layout
4760 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4763 \begin_layout Plain Layout
4769 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4772 \begin_layout Plain Layout
4778 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4781 \begin_layout Plain Layout
4787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4790 \begin_layout Plain Layout
4796 <cell alignment="center" valignment="top" topline="true" usebox="none">
4799 \begin_layout Plain Layout
4805 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4808 \begin_layout Plain Layout
4814 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4817 \begin_layout Plain Layout
4825 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4828 \begin_layout Plain Layout
4834 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4837 \begin_layout Plain Layout
4843 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4846 \begin_layout Plain Layout
4852 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4855 \begin_layout Plain Layout
4861 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4864 \begin_layout Plain Layout
4870 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4873 \begin_layout Plain Layout
4879 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4882 \begin_layout Plain Layout
4901 \begin_layout Subsection
4905 \begin_layout Standard
4906 These tests check whether a .lyx file loads without any terminal messages.
4907 They correspond to the manual operations of simply opening a .lyx file on
4908 the terminal, exiting LyX once the file is loaded, and then checking whether
4909 there is any output from the terminal.
4910 These tests are useful for catching malformed .lyx files and parsing bugs.
4911 They can also be used to find a .lyx file in which an instance of something
4913 To do this, compile LyX with a local patch that outputs something to the
4914 terminal when an instance is found, and then run the check_load tests to
4915 see if any fail, which would mean that the situation occurs in the LyX
4916 documentation files corresponding to the failed tests.
4917 These tests are expectedly fragile: any LyX diagnostic message, which is
4918 not necessarily an error, would cause the tests to fail.
4919 Similarly, any message output by a library (e.g.
4920 Qt) would also cause failure.
4921 There are some messages that the check_load tests are instructed to ignore,
4922 which are stored in the file
4923 \begin_inset Flex Code
4926 \begin_layout Plain Layout
4927 development/autotests/filterCheckWarnings
4935 \begin_layout Standard
4936 Under cmake, the tests are labeled as 'load'.
4939 \begin_layout Subsection
4943 \begin_layout Standard
4944 Automated tests based on the "MonKey Testing" keytest program are enabled
4945 if the necessary dependencies are found and if the CMake flag
4946 \begin_inset Flex Code
4949 \begin_layout Plain Layout
4950 -DLYX_ENABLE_KEYTESTS=ON
4956 They are documented in the README document in
4957 \begin_inset Flex Code
4960 \begin_layout Plain Layout
4961 development/autotests
4966 subfolder of the \SpecialChar LyX
4967 source code distribution.
4970 \begin_layout Subsection
4974 \begin_layout Standard
4975 These tests combine lyx2lyx tests with check_load tests.
4976 They fail if either fails.
4979 \begin_layout Subsection
4983 \begin_layout Standard
4984 The URL tests are enabled with the
4985 \begin_inset Flex Code
4988 \begin_layout Plain Layout
4989 -DLYX_ENABLE_URLTESTS=ON
4994 CMake flag and are useful for finding broken links in our documentation
4996 If a URL test fails, to see which link in particular was reported as broken,
4998 \begin_inset Flex Code
5001 \begin_layout Plain Layout
5008 These tests are extremely fragile (e.g.
5009 a test can depend on your Internet connection) and a failed URL test should
5010 not be taken too seriously.
5011 URL tests are labeled as
5016 \begin_layout Subsubsection
5020 \begin_layout Standard
5021 cmake is required to run the \SpecialChar LyX
5022 tests, running them is not implemented for
5026 \begin_layout Standard
5027 The appropriate commands are:
5030 \begin_layout Itemize
5036 \begin_inset Newline newline
5039 runs all tests with label
5044 \begin_layout Itemize
5047 ctest -R 'check_.*urls'
5050 \begin_inset Newline newline
5053 runs the tests 'check_accessible_urls'
5056 \begin_layout Standard
5057 Associated test results can be examined in ctest-log directory in files
5058 of the form 'LastFailed.*URLS.log'
5061 \begin_layout Chapter
5062 Development policies
5065 \begin_layout Standard
5066 This chapter lists some guidelines that should be followed.
5067 This list is not complete, and many guidelines are in separate chapters,
5069 \begin_inset Quotes eld
5072 When is an update of the .lyx file format number needed?
5073 \begin_inset Quotes erd
5077 \begin_inset CommandInset ref
5079 reference "sec:When-is-an"
5086 \begin_layout Section
5087 When to set a fixed milestone?
5090 \begin_layout Standard
5091 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5095 \begin_layout Enumerate
5096 Somebody is actively working on a fix.
5099 \begin_layout Enumerate
5100 The bug is so severe that it would block the release if it is not fixed.
5103 \begin_layout Standard
5104 If a bug is important, but nobody is working on it, and it is no showstopper,
5105 use a milestone like 2.1.x or 2.2.x.
5106 For all other bugs, do not set a milestone at all.
5109 \begin_layout Section
5110 Can we add rc entries in stable branch?
5113 \begin_layout Standard
5115 We are supposed to increase the prefs2prefs version number with such things.
5118 \begin_layout Chapter
5119 \begin_inset CommandInset label
5121 name "sec:Documentation-policies"
5125 Documentation policies
5128 \begin_layout Section
5132 \begin_layout Standard
5134 \begin_inset space ~
5137 rules in editing the docs:
5140 \begin_layout Enumerate
5141 \begin_inset CommandInset label
5143 name "enu:If-you-are"
5147 If you are not the maintainer of a doc file or a chapter/section, you MUST
5148 use change tracking so that the maintainer could review your changes
5151 \begin_layout Enumerate
5152 Respect the formatting of the document.
5153 The different files use different formatting styles.
5154 That is OK and has historic reasons nobody fully knows ;-).
5155 But it is important to be consistent within one file.
5158 \begin_layout Enumerate
5159 All changes you make to a file in one language MUST also go the file in
5160 the other actively maintained languages.
5161 Normally the maintainer does this for you, if you are the maintainer, you
5162 must do this by copying or changing the changed or added text to the other
5163 files so that the translators sees the blue underlined text and know what
5164 they have to translate and what was changed.
5167 \begin_layout Enumerate
5168 You MUST assure that the document is compilable as
5169 \begin_inset Quotes eld
5173 \begin_inset Quotes erd
5176 or the document's default output format after your changes.
5179 \begin_layout Enumerate
5180 All fixes (typos, compilation fixes, updates info etc.) go at first into
5181 the current GIT branch because the user should benefit from all fixes with
5182 every minor release.
5183 Feel free to commit directly to branch as long as you follow rule
5184 \begin_inset space ~
5188 \begin_inset CommandInset ref
5190 reference "enu:If-you-are"
5195 You can immediately commit to master as well.
5198 \begin_layout Enumerate
5199 \begin_inset CommandInset label
5201 name "enu:The-fileformat-of"
5205 The fileformat of a file must not be changed unless you document a new feature
5206 in LyX that requires a new fileformat.
5207 The reason for this rule is to keep it easy for the doc maintainers to
5208 port/backport changes to from master/branch.
5211 \begin_layout Standard
5212 The main documentation consists of these files:
5215 \begin_layout Description
5216 Welcome.lyx it is the first file you see after an installation.
5217 We assume that a new user sees this.
5218 It is therefore designed to be as simple as possible.
5219 Therefore please don't add any new formatting, only fix typos etc.
5220 Welcome.lyx is up to date for \SpecialChar LyX
5221 2.1.x, currently maintained by Uwe Stöhr.
5224 \begin_layout Description
5225 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5227 It therefore uses a limited set of formatting.
5228 For example a standard document class.
5229 Since new users will first learn about the formatting possibilities of
5231 please keep this file that simple.
5232 Intro.lyx is up to date for \SpecialChar LyX
5233 2.1.x, currently maintained by Uwe Stöhr.
5236 \begin_layout Description
5237 Tutorial.lyx our tutorial.
5238 It must be always up to date.
5239 Normally there is nothing to add since we don't want to overwhelm new users
5240 with too much details.
5241 The will learn these details while using \SpecialChar LyX
5242 and we have special manuals.
5243 Tutorial.lyx is up to date for \SpecialChar LyX
5244 2.1.x, currently maintained by Uwe Stöhr.
5247 \begin_layout Description
5248 UserGuide.lyx our main user guide.
5249 It covers a mixture of basic and detailed information.
5250 Some information is also in the Math and EmbeddedObjects manual so that
5251 the UserGuide refers to these files.
5252 UserGuide.lyx is up to date for \SpecialChar LyX
5253 2.1.x, currently maintained by Uwe Stöhr.
5256 \begin_layout Description
5257 EmbeddedObjects.lyx a special manual to explain things like tables floats
5260 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5261 2.1.x, currently maintained by Uwe
5265 \begin_layout Description
5266 Math.lyx a special manual to explain everything regarding math in all detail.
5267 Math.lyx is up to date for \SpecialChar LyX
5268 2.1.x, currently maintained by Uwe Stöhr.
5271 \begin_layout Description
5272 Additional.lyx this manual covers information that would be too much detail
5273 for the UserGuide or would make the UserGuide uncompilable or only compilable
5274 when installing a lot of special \SpecialChar LaTeX
5276 What should be in the UserGuide or better in Additional is a matter of
5278 it is up to you to decide that.
5279 Additional.lyx is not completely up to date for \SpecialChar LyX
5282 \begin_inset space ~
5285 8 is up to date and currently maintained by Uwe Stöhr.
5286 It certainly needs a rewrite and update.
5287 For example many info in chapter
5288 \begin_inset space ~
5291 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5295 \begin_layout Description
5296 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5298 output formats, operating systems, languages etc.
5299 It is currently completely out of date and needs a major rewrite and update.
5300 If you do this please assure that your information are given for all OSes
5301 and \SpecialChar LaTeX
5302 distributions (meaning be as objective as possible).
5305 \begin_layout Chapter
5309 \begin_layout Standard
5310 The aim of this chapter is to serve as a guide for the developers, to aid
5311 us to get clean and uniform code.
5313 We really like to have new developers joining the \SpecialChar LyX
5315 However, we have had problems in the past with developers leaving the project
5316 and their contributed code in a far from perfect state.
5317 Most of this happened before we really became aware of these issues, but
5318 still, we don't want it to happen again.
5319 So we have put together some guidelines and rules for the developers.
5322 \begin_layout Section
5326 \begin_layout Standard
5327 These guidelines should save us a lot of work while cleaning up the code
5328 and help us to have quality code.
5330 has been haunted by problems coming from unfinished projects by people
5331 who have left the team.
5332 Those problems will hopefully disappear if the code is easy to hand over
5334 In general, if you want to contribute to the main source, we expect at
5338 \begin_layout Itemize
5339 The most important rule first: KISS (Keep It Simple Stupid), always use
5340 a simple implementation in favor of a more complicated one.
5341 This eases maintenance a lot.
5344 \begin_layout Itemize
5345 Write good C++ code: readable, well commented, and taking advantage of the
5347 Follow the formatting guidelines.
5349 \begin_inset space ~
5353 \begin_inset CommandInset ref
5355 reference "sec:Formatting"
5365 \begin_layout Itemize
5366 As of LyX 2.4.0, you can use features of C++11.
5367 Accordingly you have to use C++11 standard conforming compiler, e.
5368 \begin_inset space \thinspace{}
5372 not too dated version of GCC or Clang.
5375 \begin_layout Itemize
5376 Adapt the code to the structures already existing in \SpecialChar LyX
5377 , or in the case that
5378 you have better ideas, discuss them on the developer's list before writing
5382 \begin_layout Itemize
5383 Take advantage of the C++ standard library.
5384 Especially don't use custom containers when a standard container is usable;
5385 learn to use the algorithms and functors in the standard library.
5388 \begin_layout Itemize
5389 Be aware of exceptions and write exception safe code.
5391 \begin_inset space ~
5395 \begin_inset CommandInset ref
5397 reference "sec:Exceptions"
5407 \begin_layout Itemize
5408 Document all variables, methods, functions, classes etc.
5409 We are using the source documentation program doxygen, a program that handles
5410 javadoc syntax, to document sources.
5411 You can download doxygen from:
5412 \begin_inset Flex URL
5415 \begin_layout Plain Layout
5417 http://www.stack.nl/~dimitri/doxygen/
5425 \begin_layout Itemize
5426 We have certain code constructs that we try to follow.
5428 \begin_inset space ~
5432 \begin_inset CommandInset ref
5434 reference "sec:Code-constructs"
5444 \begin_layout Section
5448 \begin_layout Standard
5449 It is implicitly understood that all patches contributed to The \SpecialChar LyX
5451 is under the Gnu General Public License, version 2 or later.
5452 If you have a problem with that, don't contribute code.
5453 Also please don't just pop up out of the blue with a huge patch (or small)
5454 that changes something substantial in \SpecialChar LyX
5456 Always discuss your ideas with the developers on the developer's mailing
5458 When you create the patch, please use
5459 \begin_inset Quotes eld
5467 \begin_inset Quotes erd
5470 since we find that a lot easier to read than the other diff formats.
5471 Also please do not send patches that implements or fixes several different
5472 things; several patches is a much better option.
5473 We also require you to provide a commit message entry with every patch,
5474 this describes in detail what the patch is doing.
5478 \begin_layout Section
5480 \begin_inset CommandInset label
5482 name "sec:Code-constructs"
5489 \begin_layout Standard
5490 We have several guidelines on code constructs, some of these exist to make
5491 the code faster, others to make the code clearer.
5492 Yet others exist to allow us to take advantage of the strong type checking
5496 \begin_layout Itemize
5497 Declaration of variables should wait as long as possible.
5499 \begin_inset Quotes eld
5502 Don't declare it until you need it.
5503 \begin_inset Quotes erd
5506 In C++ there are a lot of user defined types, and these can very often
5507 be expensive to initialize.
5508 This rule connects to the next rule too.
5512 \begin_layout Itemize
5513 Declare the variable as
5514 \begin_inset Flex Code
5517 \begin_layout Plain Layout
5523 if you don't need to change it.
5524 This applies to POD types like
5525 \begin_inset Flex Code
5528 \begin_layout Plain Layout
5538 \begin_layout Itemize
5539 Make the scope of a variable as small as possible.
5542 \begin_layout Itemize
5543 Make good use of namespaces.
5544 Prefer anonymous namespaces to declaring
5545 \begin_inset Flex Code
5548 \begin_layout Plain Layout
5557 \begin_layout Itemize
5558 Prefer preincrement to postincrement whenever possible.
5561 \begin_layout Itemize
5562 Preincrement has potential of being faster than postincrement.
5563 Just think about the obvious implementations of pre/post-increment.
5564 This rule applies to decrement too.
5567 \begin_layout Itemize
5569 \begin_inset Separator latexpar
5576 \begin_layout Standard
5577 \begin_inset listings
5578 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5582 \begin_layout Plain Layout
5587 \begin_layout Plain Layout
5597 \begin_layout Standard
5601 \begin_layout Standard
5602 \begin_inset listings
5603 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5607 \begin_layout Plain Layout
5609 T++; // not used in LyX
5612 \begin_layout Plain Layout
5614 U--; // not used in LyX
5623 \begin_layout Itemize
5624 Try to minimize evaluation of the same code over and over.
5625 This is aimed especially at loops.
5627 \begin_inset Newline newline
5631 \begin_inset Separator latexpar
5638 \begin_layout Standard
5639 \begin_inset listings
5640 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5644 \begin_layout Plain Layout
5646 Container::iterator end = large.end();
5649 \begin_layout Plain Layout
5651 for (Container::iterator it = large.begin(); it != end; ++it) {
5654 \begin_layout Plain Layout
5659 \begin_layout Plain Layout
5669 \begin_layout Standard
5673 \begin_layout Standard
5674 \begin_inset listings
5675 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5679 \begin_layout Plain Layout
5681 for (auto const & it : large) {
5684 \begin_layout Plain Layout
5689 \begin_layout Plain Layout
5699 \begin_layout Standard
5703 \begin_layout Standard
5704 \begin_inset listings
5705 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5709 \begin_layout Plain Layout
5711 for (Container::iterator it = large.begin(); it != large.end(); ++it) {
5714 \begin_layout Plain Layout
5719 \begin_layout Plain Layout
5730 \begin_layout Itemize
5731 For functions and methods that return a non-POD type
5735 \begin_layout Plain Layout
5742 \begin_inset Flex Code
5745 \begin_layout Plain Layout
5752 \begin_inset Flex Code
5755 \begin_layout Plain Layout
5762 This gives better type checking, and will give a compiler warning when
5763 temporaries are used wrongly.
5764 \begin_inset Separator latexpar
5771 \begin_layout Standard
5775 \begin_layout Standard
5776 \begin_inset listings
5777 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5781 \begin_layout Plain Layout
5791 \begin_layout Standard
5795 \begin_layout Standard
5796 \begin_inset listings
5797 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5801 \begin_layout Plain Layout
5812 \begin_layout Itemize
5813 Avoid using the default cases in switch statements unless you have too.
5814 Use the correct type for the switch expression and let the compiler ensure
5815 that all cases are exhausted.
5818 \begin_layout Itemize
5819 \begin_inset listings
5820 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5824 \begin_layout Plain Layout
5829 \begin_layout Plain Layout
5834 \begin_layout Plain Layout
5839 \begin_layout Plain Layout
5844 \begin_layout Plain Layout
5848 \begin_layout Plain Layout
5853 \begin_layout Plain Layout
5857 \begin_layout Plain Layout
5862 \begin_layout Plain Layout
5867 \begin_layout Plain Layout
5872 \begin_layout Plain Layout
5877 \begin_layout Plain Layout
5882 \begin_layout Plain Layout
5887 \begin_layout Plain Layout
5889 // not needed and would shadow a wrong use of Foo
5892 \begin_layout Plain Layout
5897 \begin_layout Plain Layout
5907 \begin_layout Section
5909 \begin_inset CommandInset label
5911 name "sec:Exceptions"
5918 \begin_layout Standard
5919 Be aware of the presence of exceptions.
5920 One important thing to realize is that you often do not have to use throw,
5921 try or catch to be exception safe.
5922 Let's look at the different types of exceptions safety (these are taken
5923 from Herb Sutter's book
5924 \begin_inset CommandInset citation
5934 \begin_layout Enumerate
5935 Basic guarantee: Even in the presence of exceptions thrown by T or other
5936 exceptions, Stack objects don't leak resources.
5937 Note that this also implies that the container will be destructible and
5938 usable even if an exception is thrown while performing some container operation.
5939 However, if an exception is thrown, the container will be in a consistent,
5940 but not necessarily predictable, state.
5941 Containers that support the basic guarantee can work safely in some settings.
5945 \begin_layout Enumerate
5946 Strong guarantee: If an operation terminates because of an exception, program
5947 state will remain unchanged.
5948 This always implies commit-or-rollback semantics, including that no references
5949 or iterators into the container be invalidated if an operation fails.
5950 For example, if a Stack client calls Top and then attempts a Push that
5951 fails because of an exception, then the state of the Stack object must
5952 be unchanged and the reference returned from the prior call to Top must
5954 For more information on these guarantees, see Dave Abrahams's documentation
5955 of the SGI exception-safe standard library adaption at:
5956 \begin_inset Flex URL
5959 \begin_layout Plain Layout
5961 http://www.stlport.org/doc/exception_safety.html
5966 Probably the most interesting point here is that when you implement the
5967 basic guarantee, the strong guarantee often comes for free.
5968 For example, in our Stack implementation, almost everything we did was
5969 needed to satisfy just the basic guarantee – and what's presented above
5970 very nearly satisfies the strong guarantee, with little or no extra work.
5971 Not half bad, considering all the trouble we went to.
5972 In addition to these two guarantees, there is one more guarantee that certain
5973 functions must provide in order to make overall exception safety possible:
5976 \begin_layout Enumerate
5977 No throw guarantee: The function will not emit an exception under any circumstan
5979 Overall exception safety isn't possible unless certain functions are guaranteed
5981 In particular, we've seen that this is true for destructors; later in this
5982 miniseries, we'll see that it's also needed in certain helper functions,
5990 \begin_layout Standard
5991 For all cases where we might be able to write exception safe functions without
5992 using try, throw or catch we should do so.
5993 In particular we should look over all destructors to ensure that they are
5994 as exception safe as possible.
5997 \begin_layout Section
5999 \begin_inset CommandInset label
6001 name "sec:Formatting"
6008 \begin_layout Itemize
6009 Only one declaration on each line.
6010 \begin_inset Separator latexpar
6017 \begin_layout Standard
6021 \begin_layout Standard
6022 \begin_inset listings
6023 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6027 \begin_layout Plain Layout
6032 \begin_layout Plain Layout
6042 \begin_layout Standard
6046 \begin_layout Standard
6047 \begin_inset listings
6048 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6052 \begin_layout Plain Layout
6054 int a, b; // not used in LyX
6062 \begin_layout Standard
6063 This is especially important when initialization is done at the same time:
6066 \begin_layout Standard
6070 \begin_layout Standard
6071 \begin_inset listings
6072 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6076 \begin_layout Plain Layout
6081 \begin_layout Plain Layout
6083 string b = "Gullik";
6091 \begin_layout Standard
6095 \begin_layout Standard
6096 \begin_inset listings
6097 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6101 \begin_layout Plain Layout
6103 string a = "Lars", b = "Gullik"; // not used in LyX
6111 \begin_layout Standard
6113 \begin_inset Flex Code
6116 \begin_layout Plain Layout
6122 is formally calling a copy constructor on a temporary constructed from
6123 a string literal and therefore has the potential of being more expensive
6124 then direct construction by
6125 \begin_inset Flex Code
6128 \begin_layout Plain Layout
6135 However the compiler is allowed to elide the copy (even if it had side
6136 effects), and modern compilers typically do so.
6137 Given these equal costs, \SpecialChar LyX
6138 code favours the '=' idiom as it is in line with
6139 the traditional C-style initialization,
6143 cannot be mistaken as function declaration,
6147 reduces the level of nested parentheses in more initializations.]
6151 \begin_layout Itemize
6152 Pointers and references:
6153 \begin_inset Separator latexpar
6160 \begin_layout Standard
6164 \begin_layout Standard
6165 \begin_inset listings
6166 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6170 \begin_layout Plain Layout
6175 \begin_layout Plain Layout
6185 \begin_layout Standard
6189 \begin_layout Standard
6190 \begin_inset listings
6191 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6195 \begin_layout Plain Layout
6197 char *p = "flop"; // not used in LyX
6200 \begin_layout Plain Layout
6202 char &c = *p; // not used in LyX
6210 \begin_layout Standard
6211 Some time ago we had a huge discussion on this subject and after convincing
6212 argumentation from Asger this is what we decided.
6213 Also note that we will have:
6216 \begin_layout Standard
6217 \begin_inset listings
6218 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6222 \begin_layout Plain Layout
6232 \begin_layout Standard
6236 \begin_layout Standard
6237 \begin_inset listings
6238 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6242 \begin_layout Plain Layout
6244 const char * p; // not used in LyX
6253 \begin_layout Itemize
6254 Operator names and parentheses
6255 \begin_inset Separator latexpar
6262 \begin_layout Standard
6263 \begin_inset listings
6264 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6268 \begin_layout Plain Layout
6278 \begin_layout Standard
6282 \begin_layout Standard
6283 \begin_inset listings
6284 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6288 \begin_layout Plain Layout
6290 operator == (type) // not used in LyX
6298 \begin_layout Standard
6299 The == is part of the function name, separating it makes the declaration
6300 look like an expression.
6304 \begin_layout Itemize
6305 Function names and parentheses
6306 \begin_inset Separator latexpar
6313 \begin_layout Standard
6314 \begin_inset listings
6315 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6319 \begin_layout Plain Layout
6329 \begin_layout Standard
6333 \begin_layout Standard
6334 \begin_inset listings
6335 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6339 \begin_layout Plain Layout
6341 void mangle () // not used in LyX
6350 \begin_layout Itemize
6352 \begin_inset Separator latexpar
6359 \begin_layout Standard
6360 \begin_inset listings
6361 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6365 \begin_layout Plain Layout
6370 \begin_layout Plain Layout
6375 \begin_layout Plain Layout
6380 \begin_layout Plain Layout
6385 \begin_layout Plain Layout
6395 \begin_layout Standard
6399 \begin_layout Standard
6400 \begin_inset listings
6401 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6405 \begin_layout Plain Layout
6407 enum { one = 1, two = 2, three 3 }; // not used in LyX
6415 \begin_layout Standard
6419 \begin_layout Standard
6420 \begin_inset listings
6421 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6425 \begin_layout Plain Layout
6430 \begin_layout Plain Layout
6435 \begin_layout Plain Layout
6440 \begin_layout Plain Layout
6445 \begin_layout Plain Layout
6456 \begin_layout Itemize
6458 \begin_inset Separator latexpar
6465 \begin_layout Standard
6466 Use nullptr (C++11):
6469 \begin_layout Standard
6470 \begin_inset listings
6471 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6475 \begin_layout Plain Layout
6485 \begin_layout Standard
6489 \begin_layout Standard
6490 \begin_inset listings
6491 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6495 \begin_layout Plain Layout
6497 void * p = NULL; // not used in LyX
6505 \begin_layout Standard
6509 \begin_layout Standard
6510 \begin_inset listings
6511 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6515 \begin_layout Plain Layout
6519 0'; // not used in LyX
6527 \begin_layout Standard
6531 \begin_layout Standard
6532 \begin_inset listings
6533 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6537 \begin_layout Plain Layout
6539 void * p = 42 - 7 * 6; // not used in LyX
6547 \begin_layout Standard
6548 Note: As an exception, imported third party code as well as code interfacing
6550 \begin_inset Quotes eld
6554 \begin_inset Quotes erd
6558 \begin_inset Flex Code
6561 \begin_layout Plain Layout
6571 \begin_layout Itemize
6572 Naming rules for classes
6573 \begin_inset Separator latexpar
6580 \begin_layout Itemize
6581 Use descriptive but simple and short names.
6585 \begin_layout Itemize
6586 Class names are usually capitalized, and function names lowercased.
6589 \begin_layout Itemize
6590 Enums are named like Classes, values are usually in lower-case.
6593 \begin_layout Itemize
6594 Public API functions are camel-case (
6595 \begin_inset Flex Code
6598 \begin_layout Plain Layout
6599 void setAFlagToAValue(bool)
6607 \begin_layout Itemize
6608 Member variables are underscored (
6609 \begin_inset Flex Code
6612 \begin_layout Plain Layout
6613 enable_this_feature_flag_
6619 \begin_inset Quotes eld
6623 \begin_inset Quotes erd
6629 \begin_layout Itemize
6630 Private/protected functions are also camel-case.
6633 \begin_layout Itemize
6634 New types are capitalized, so this goes for typedefs, classes, structs and
6639 \begin_layout Itemize
6641 \begin_inset Separator latexpar
6648 \begin_layout Itemize
6649 Adapt the formatting of your code to the one used in the other parts of
6652 In case there is different formatting for the same construct, use the one
6657 \begin_layout Itemize
6658 Use existing structures
6659 \begin_inset Separator latexpar
6666 \begin_layout Itemize
6667 \begin_inset CommandInset label
6669 name "Use-string-wherever"
6674 \begin_inset Flex Code
6677 \begin_layout Plain Layout
6684 Unicode strings should prefer using
6685 \begin_inset Flex Code
6688 \begin_layout Plain Layout
6694 instead of UTF-8 encoded
6695 \begin_inset Flex Code
6698 \begin_layout Plain Layout
6707 \begin_layout Itemize
6708 Check out the filename and path tools in
6709 \begin_inset Flex Code
6712 \begin_layout Plain Layout
6721 \begin_layout Itemize
6722 Check out the string tools in
6723 \begin_inset Flex Code
6726 \begin_layout Plain Layout
6735 \begin_layout Itemize
6736 Use the \SpecialChar LyX
6737 Err class to report errors and messages using the lyxerr instantiation.
6738 [add description of other existing structures]
6742 \begin_layout Itemize
6744 \begin_inset Separator latexpar
6751 \begin_layout Itemize
6752 Use this order for the access sections of your class: public, protected,
6754 The public section is interesting for every user of the class.
6755 The private section is only of interest for the implementors of the class
6757 [Obviously not true since this is for developers, and we do not want one
6758 developer only to be able to read and understand the implementation of
6763 \begin_layout Itemize
6764 Avoid declaring global objects in the declaration file of the class.
6765 If the same variable is used for all objects, use a static member.
6768 \begin_layout Itemize
6769 Avoid global or static variables.
6773 \begin_layout Itemize
6775 \begin_inset Separator latexpar
6782 \begin_layout Standard
6783 If you create a new file, the top of the file should look something like
6787 \begin_layout Standard
6788 \begin_inset listings
6789 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6793 \begin_layout Plain Layout
6798 \begin_layout Plain Layout
6805 \begin_layout Plain Layout
6807 * This file is part of LyX, the document processor.
6810 \begin_layout Plain Layout
6812 * Licence details can be found in the file COPYING.
6815 \begin_layout Plain Layout
6820 \begin_layout Plain Layout
6827 \begin_layout Plain Layout
6832 \begin_layout Plain Layout
6834 * Full author contact details are available
6837 \begin_layout Plain Layout
6842 \begin_layout Plain Layout
6853 \begin_layout Itemize
6855 \begin_inset Separator latexpar
6862 \begin_layout Itemize
6863 The documentation is generated from the header files.
6866 \begin_layout Itemize
6867 You document for the other developers, not for yourself.
6870 \begin_layout Itemize
6871 You should document what the function does, not the implementation.
6872 \begin_inset Separator latexpar
6879 \begin_layout Itemize
6880 in the .cpp files you document the implementation.
6884 \begin_layout Itemize
6885 Single line description (
6886 \begin_inset Flex Code
6889 \begin_layout Plain Layout
6895 ), multiple lines description (
6896 \begin_inset Flex Code
6899 \begin_layout Plain Layout
6906 ), see the doxygen webpage referenced above.
6910 \begin_layout Section
6911 Naming rules for \SpecialChar LyX
6912 User Functions (LFUNs)
6915 \begin_layout Standard
6916 Here is the set of rules to apply when a new command name is introduced:
6919 \begin_layout Enumerate
6920 Use the object.event order.
6921 That is, use `word-forward' instead of `forward-word'.
6924 \begin_layout Enumerate
6925 Don't introduce an alias for an already named object.
6929 \begin_layout Enumerate
6930 Forward movement or focus is called `forward' (not `right').
6933 \begin_layout Enumerate
6934 Backward movement or focus is called `backward' (not `left').
6937 \begin_layout Enumerate
6938 Upward movement of focus is called `up'.
6941 \begin_layout Enumerate
6942 Downward movement is called `down'.
6945 \begin_layout Enumerate
6946 The begin of an object is called `begin' (not `start').
6949 \begin_layout Enumerate
6950 The end of an object is called `end'.
6953 \begin_layout Section
6954 How to create class interfaces
6957 \begin_layout Standard
6958 (a.k.a How Non-Member Functions Improve Encapsulation)
6961 \begin_layout Standard
6962 I recently read an article by Scott Meyers, where he makes a strong case
6963 on how non-member functions makes classes more encapsulated, not less.
6964 Just skipping to the core of this provides us with the following algorithm
6965 for deciding what kind of function to add to a class interface:
6968 \begin_layout Itemize
6969 We need to add a function f to the class C's API.
6970 \begin_inset Separator latexpar
6977 \begin_layout Standard
6978 \begin_inset listings
6979 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6983 \begin_layout Plain Layout
6985 if (f needs to be virtual)
6988 \begin_layout Plain Layout
6990 make f a member function of C;
6993 \begin_layout Plain Layout
6995 else if (f is operator>> or operator<<) {
6998 \begin_layout Plain Layout
7000 make f a non-member function;
7003 \begin_layout Plain Layout
7005 if (f needs access to non-public members of C)
7008 \begin_layout Plain Layout
7010 make f a friend of C;
7013 \begin_layout Plain Layout
7015 } else if (f needs type conversions on its left-most argument) {
7018 \begin_layout Plain Layout
7020 make f a non-member function;
7023 \begin_layout Plain Layout
7025 if (f needs access to non-public members of C)
7028 \begin_layout Plain Layout
7030 make f a friend of C;
7033 \begin_layout Plain Layout
7035 } else if (f can be implemented via C's public interface)
7038 \begin_layout Plain Layout
7040 make f a non-member function;
7043 \begin_layout Plain Layout
7048 \begin_layout Plain Layout
7050 make f a member function of C;
7059 \begin_layout Chapter
7060 Coding recommendations
7063 \begin_layout Standard
7064 These are some rules for effective C++ programming.
7065 These are taken from Scott Meyers
7066 \begin_inset CommandInset citation
7073 , and are presented in their short form.
7074 These are not all the rules Meyers presents, only the most important of
7077 does not yet follow these rules, but they should be the goal.
7080 \begin_layout Itemize
7094 \begin_layout Itemize
7095 use the same form in corresponding calls to new and delete, i.e.
7097 \begin_inset Flex Code
7100 \begin_layout Plain Layout
7107 \begin_inset Flex Code
7110 \begin_layout Plain Layout
7116 was used to create the object and write
7117 \begin_inset Flex Code
7120 \begin_layout Plain Layout
7127 \begin_inset Flex Code
7130 \begin_layout Plain Layout
7136 Notice strings should be
7137 \begin_inset Flex Code
7140 \begin_layout Plain Layout
7147 \begin_inset Flex Code
7150 \begin_layout Plain Layout
7157 (this contradicts to
7158 \begin_inset CommandInset ref
7160 reference "Use-string-wherever"
7167 \begin_layout Itemize
7168 define a default constructor, copy constructor and an assignment operator
7169 for all classes with dynamically allocated memory that are not made noncopyable
7172 \begin_layout Itemize
7173 do not define default constructor, copy constructor and an assignment operator
7174 if the compiler generated one would do the same
7177 \begin_layout Itemize
7178 make destructors virtual in base classes and only there
7181 \begin_layout Itemize
7182 assign to all data members in operator=()
7185 \begin_layout Itemize
7186 strive for class interfaces that are complete and minimal
7189 \begin_layout Itemize
7190 differentiate among member functions, global functions and friend functions
7193 \begin_layout Itemize
7194 avoid data members in the public interface
7197 \begin_layout Itemize
7198 use const whenever possible
7201 \begin_layout Itemize
7202 pass and return objects by reference instead of by value
7205 \begin_layout Itemize
7206 choose carefully between function overloading and parameter defaulting
7209 \begin_layout Itemize
7210 never return a reference to a local object or a dereferenced pointer initialized
7211 by new within the function
7214 \begin_layout Itemize
7215 use enums for integral constants
7218 \begin_layout Itemize
7219 minimize compilation dependencies between files
7222 \begin_layout Itemize
7223 pay attention to compiler warnings
7226 \begin_layout Itemize
7227 differentiate between inheritance of interface and inheritance of implementation
7230 \begin_layout Itemize
7231 differentiate between inheritance and templates
7234 \begin_layout Itemize
7235 ensure that global objects are initialized before they are used
7238 \begin_layout Itemize
7240 \begin_inset Flex Code
7243 \begin_layout Plain Layout
7250 \begin_inset Flex Code
7253 \begin_layout Plain Layout
7259 that span more than a line
7262 \begin_layout Chapter
7267 \begin_layout Itemize
7268 And one of mine: (Lgb)
7269 \begin_inset Separator latexpar
7276 \begin_layout Itemize
7277 when switching on enums, refrain from using "default:" if possible
7281 \begin_layout Itemize
7282 And one of mine: (Andre')
7283 \begin_inset Separator latexpar
7290 \begin_layout Itemize
7291 try to implement your class in a way that the automatically generated copy
7292 constructor and copy assignment work out-of-the box
7295 \begin_layout Itemize
7296 I don't have problems with using boost in the implementation _if and only
7297 if_ it provides actual benefits over less intrusive alternatives.
7298 I do have a problem with needlessly sprinkling 'boost::' over interfaces,
7299 especially if it does not add any value.
7300 \begin_inset Separator latexpar
7307 \begin_layout Standard
7308 Given that there seems to be an unconditional "typedef unsigned int quint32;"
7309 in qglobal.h I don't think there's any platform supported by current \SpecialChar LyX
7311 could not use 'unsigned int' (and an static assert in some implementation
7312 file for the unlikely case some ILP64 zombie raises its ugly head again.
7313 And if that happens, using <cstdint> would still be a better choice...)
7316 \begin_layout Standard
7317 The idea is to create something that's not compilable as soon as the condition
7319 There are lots of possibilities to achieve this, some examples follow:
7322 \begin_layout Standard
7323 In C++11 there's a "built-in":
7326 \begin_layout Standard
7327 \begin_inset listings
7328 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7332 \begin_layout Plain Layout
7334 static_assert(sizeof(int) == 4, "Funny platform")
7342 \begin_layout Standard
7343 until then on namespace scope:
7346 \begin_layout Standard
7347 \begin_inset listings
7348 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7352 \begin_layout Plain Layout
7354 #include <boost/static_assert.hpp>
7357 \begin_layout Plain Layout
7359 BOOST_STATIC_ASSERT(sizeof(int) == 4)
7367 \begin_layout Standard
7371 \begin_layout Standard
7372 \begin_inset listings
7373 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7377 \begin_layout Plain Layout
7379 template<bool Condition>
7382 \begin_layout Plain Layout
7384 struct static_assert_helper;
7387 \begin_layout Plain Layout
7392 \begin_layout Plain Layout
7394 struct static_assert_helper<true> {};
7397 \begin_layout Plain Layout
7402 \begin_layout Plain Layout
7404 dummy = sizeof(static_assert_helper<sizeof(int) == 4>)
7407 \begin_layout Plain Layout
7417 \begin_layout Standard
7418 or somewhat brutish without templates, in any function:
7421 \begin_layout Standard
7422 \begin_inset listings
7423 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7427 \begin_layout Plain Layout
7429 const int d = sizeof(int) - 4;
7432 \begin_layout Plain Layout
7437 \begin_layout Plain Layout
7442 \begin_layout Plain Layout
7447 \begin_layout Plain Layout
7452 \begin_layout Plain Layout
7462 \begin_layout Standard
7463 Any of them in a .cpp file will break compilation as soon as
7464 \begin_inset Flex Code
7467 \begin_layout Plain Layout
7474 Personally I prefer something like the third version (or the first, if
7475 using C++11 is allowed).
7480 \begin_layout Itemize
7481 And one of mine: (vfr)
7482 \begin_inset Separator latexpar
7489 \begin_layout Itemize
7491 \begin_inset Flex URL
7494 \begin_layout Plain Layout
7496 http://www.lyx.org/trac/changeset/35855
7502 \begin_inset Separator latexpar
7509 \begin_layout Standard
7510 A dynamic_cast is necessary when:
7513 \begin_layout Itemize
7514 the object to be casted is from an external library because we can't add
7515 Qxxx::asXxxx() to Qt e.g.:
7516 \begin_inset Separator latexpar
7523 \begin_layout Itemize
7524 QAbstractListModel to GuiIdListModel,
7527 \begin_layout Itemize
7528 QValidator to PathValidator,
7531 \begin_layout Itemize
7532 QWidget to TabWorkArea,
7535 \begin_layout Itemize
7536 QWidget to GuiWorkArea;
7540 \begin_layout Itemize
7541 the object is to be casted from an interface to the implementing class,
7542 because the Interface does not know by whom it is implemented:
7543 \begin_inset Separator latexpar
7550 \begin_layout Itemize
7551 ProgressInterface to GuiProgress,
7554 \begin_layout Itemize
7555 Application to GuiApplication.
7559 \begin_layout Standard
7560 A dynamic_cast can be replaced by:
7563 \begin_layout Itemize
7564 already existing as***Inset() functions, e.g.:
7565 \begin_inset Separator latexpar
7572 \begin_layout Itemize
7576 \begin_layout Itemize
7577 asInsetMath()->asMacro(),
7580 \begin_layout Itemize
7585 \begin_layout Itemize
7586 A static_cast when we are sure this can't go wrong, e.g.:
7587 \begin_inset Separator latexpar
7594 \begin_layout Itemize
7595 we are sure that CellData::inset->clone() is an InsetTableCell,
7598 \begin_layout Itemize
7599 in cases where we explicitly check it->lyxCode().
7605 \begin_layout Bibliography
7606 \begin_inset CommandInset bibitem
7607 LatexCommand bibitem
7614 Effective C++: 50 Specific Ways to Improve Your Programs and Design.
7615 Addison-Wesley, 1992.
7618 \begin_layout Bibliography
7619 \begin_inset CommandInset bibitem
7620 LatexCommand bibitem
7627 Exceptional C++: 47 engineering puzzles, programming problems, and solutions.
7631 \begin_layout Bibliography
7632 \begin_inset CommandInset bibitem
7633 LatexCommand bibitem
7640 C/C++ User's Journal (Vol.18, No.2).