1 #LyX 2.4 created this file. For more info see https://www.lyx.org/
5 \save_transient_properties true
6 \origin /systemlyxdir/doc/
8 \options BCOR8mm,captions=tableheading
9 \use_default_options false
13 \maintain_unincluded_children no
15 \language_package default
18 \font_roman "lmodern" "default"
19 \font_sans "lmss" "default"
20 \font_typewriter "lmtt" "default"
21 \font_math "auto" "auto"
22 \font_default_family default
23 \use_non_tex_fonts false
27 \font_typewriter_osf false
28 \font_sf_scale 100 100
29 \font_tt_scale 100 100
31 \use_dash_ligatures true
33 \default_output_format pdf2
35 \bibtex_command default
36 \index_command default
37 \float_placement class
38 \float_alignment class
42 \pdf_title "LyX's Development manual"
43 \pdf_author "LyX Team"
44 \pdf_subject "LyX's development documentation"
45 \pdf_keywords "LyX, Documentation, Development"
47 \pdf_bookmarksnumbered true
48 \pdf_bookmarksopen true
49 \pdf_bookmarksopenlevel 1
54 \pdf_pdfusetitle false
55 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
58 \use_package amsmath 1
59 \use_package amssymb 1
62 \use_package mathdots 1
63 \use_package mathtools 1
65 \use_package stackrel 1
66 \use_package stmaryrd 1
67 \use_package undertilde 1
69 \cite_engine_type default
73 \paperorientation portrait
79 \notefontcolor #0000ff
86 \paragraph_separation indent
87 \paragraph_indentation default
89 \math_numbering_side default
94 \paperpagestyle headings
96 \tracking_changes false
99 \postpone_fragile_content false
103 \docbook_table_output 0
104 \docbook_mathml_prefix 1
110 Developing \SpecialChar LyX
114 \begin_layout Subtitle
119 by the \SpecialChar LyX
124 \begin_layout Plain Layout
125 If you have comments on or error corrections to this documentation,
126 please send them to the \SpecialChar LyX
127 Documentation mailing list:
129 \begin_inset CommandInset href
131 target "lyx-docs@lists.lyx.org"
145 \begin_layout Standard
146 \begin_inset CommandInset toc
147 LatexCommand tableofcontents
154 \begin_layout Chapter
158 \begin_layout Standard
159 This manual documents some aspects of \SpecialChar LyX
161 It is currently rather incomplete,
162 but will hopefully be extended in the future.
164 additional information can be found in the
165 \begin_inset Flex Code
168 \begin_layout Plain Layout
174 subfolder of the \SpecialChar LyX
175 source code distribution.
176 This document is not translated,
177 since the development language of \SpecialChar LyX
179 If you just want to use \SpecialChar LyX
181 then you don't need to read this manual.
183 if you want to learn more about how \SpecialChar LyX
185 or even want to participate in \SpecialChar LyX
187 you may find some interesting information here.
190 \begin_layout Chapter
194 \begin_layout Standard
196 uses several custom file formats for configuration files and documents.
197 This chapter contains some background concerning these file formats.
198 Several file formats are also described in detail in the regular user documentation.
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 an update of the .lyx file format number.
214 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 a file using the new feature,
221 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 header,
239 a file format update is needed.
242 \begin_layout Description
251 setting If a certain setting becomes obsolete and gets removed,
252 a file format update is needed.
255 \begin_layout Description
282 \begin_inset space \thinspace{}
289 \begin_layout Description
290 \paragraph_spacing single
303 package The reason for this is that there is no true ERT inset for math formulas:
304 Each command is parsed,
305 and if a user happens to define a local command with the same name as a command that triggers an automatic load of a package,
306 they need to be able to switch off the automatic loading of that package.
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 shipped with \SpecialChar LyX
367 then a new file format is needed in the master (development) branch.
368 It is possible to backport new styles to the stable version without a file format change.
370 \begin_inset CommandInset ref
372 reference "subsec:Backporting-new-styles"
377 for more information.
380 \begin_layout Description
385 style If a style or inset layout is removed in any layout file or module shipped with \SpecialChar LyX
387 a new file format is required.
390 \begin_layout Standard
396 layouts and modules do
400 require a file format update (changed 03/16,
402 \begin_inset CommandInset ref
404 reference "subsec:New-layouts"
413 \begin_layout Standard
414 If you are still unsure,
415 please ask on the development list.
418 \begin_layout Section
419 \begin_inset CommandInset label
421 name "subsec:update_lyx_files"
425 How to update the file format number of .lyx files
428 \begin_layout Standard
429 Once you come to the conclusion that a file format update is needed,
430 you should use the following procedure to perform the update:
433 \begin_layout Enumerate
434 Implement and test the new feature,
435 including the reading and writing of .lyx files.
436 Note that any file produced at this stage does not use a valid format,
437 so do not use this version of \SpecialChar LyX
438 for working on any important documents.
441 \begin_layout Enumerate
442 \begin_inset CommandInset label
444 name "enu:Describe_format"
448 Describe the new format in
449 \begin_inset Flex Code
452 \begin_layout Plain Layout
461 \begin_layout Enumerate
462 Update the \SpecialChar LyX
463 file format number in
464 \begin_inset Flex Code
467 \begin_layout Plain Layout
476 \begin_layout Enumerate
477 \begin_inset CommandInset label
479 name "enu:Add-an-entry"
483 Add an entry to both format lists (for conversion and reversion) in
484 \begin_inset Newline newline
488 \begin_inset Flex Code
491 \begin_layout Plain Layout
492 lib/lyx2lyx/lyx_2_4.py
498 Add a conversion routine if needed (e.
499 \begin_inset space \thinspace{}
503 a new header setting always needs a conversion that adds the new setting,
504 but a new document language does not need one).
505 Add a reversion routine if needed.
507 \begin_inset Newline newline
510 While the conversion routine is required to produce a document that is equivalent to the old version,
511 the requirements of the reversion are not that strict.
513 try to produce a proper reversion,
515 but for some features this might be too complicated.
517 the minimum requirement of the reversion routine is that it produces a valid document which can be read by an older \SpecialChar LyX
519 If absolutely needed,
520 even data loss is allowed for the reversion.
522 you might want to add a LyX comment that indicates what you have had to do,
523 so the user is at least warned).
526 \begin_layout Enumerate
527 Since tex2lyx has several implicit file format dependencies caused by sharing code with \SpecialChar LyX
529 updating the file format of .lyx files produced by tex2lyx at the same time as updating the main .lyx file format is strongly recommended.
531 a compiler warning will be issued if the \SpecialChar LyX
532 and tex2lyx .lyx file format numbers differ.
533 In many cases the tex2lyx update requires only the first and last item of the list below:
537 \begin_layout Enumerate
538 Update the tex2lyx file format number in
539 \begin_inset Flex Code
542 \begin_layout Plain Layout
551 \begin_layout Enumerate
552 If the lyx2lyx conversion from the old to the new format is empty,
553 or if tex2lyx does not yet output the changed feature,
554 you do not need any further tex2lyx changes.
556 search for the changed feature in tex2lyx,
557 and adjust the output according to the lyx2lyx changes.
560 \begin_layout Enumerate
561 Update the tex2lyx test references as described in
562 \begin_inset CommandInset ref
563 LatexCommand formatted
564 reference "sec:Updating-test-references"
573 \begin_layout Enumerate
574 If you did not implement full tex2lyx support for the new feature,
576 \begin_inset Flex Code
579 \begin_layout Plain Layout
585 describing the missing bits.
586 Note that it is perfectly fine if you do not add full tex2lyx support for a new feature:
587 The updating recommendation above is only issued for the syntax of the produced .lyx file.
588 It is no problem if some features supported by \SpecialChar LyX
589 are still output as ERT by tex2lyx.
590 The problems in the past that resulted in the update recommendation were related to mixed version syntax,
594 \begin_layout Enumerate
595 It would be nice if you could create a .lyx test file which contains instances of all changed or added features.
596 This could then be used to test lyx2lyx and tex2lyx.
597 Test samples are collected under the corresponding subdirectories of
604 \begin_layout Enumerate
605 \begin_inset CommandInset label
607 name "enu:updatefiles"
611 Test your lyx2lyx code by updating LyX's .lyx documentation files to the new format.
612 The developer who makes the change knows best what changes to expect when inspecting the resulting diff.
614 you might be able to catch a bug in the lyx2lyx code that updates the format just by taking a quick scan through the large diff that is the result.
615 \begin_inset Note Note
618 \begin_layout Plain Layout
619 Another advantage is that if later we suspect a bug in lyx2lyx we can easily see which layout update made an unexpected change by looking at the git log of a .lyx file that suffers the problem.
625 first make sure that there are no changes to the git repository that you will not want to commit (this is needed because it will be convenient to commit with the command
626 \begin_inset Flex Code
629 \begin_layout Plain Layout
636 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,
661 Keep in mind that the case of
662 \begin_inset Flex Code
665 \begin_layout Plain Layout
672 because it is first generated with
673 \begin_inset Flex Code
676 \begin_layout Plain Layout
682 before being converted to the latest format.
683 \begin_inset Newline newline
687 \begin_inset Note Greyedout
690 \begin_layout Plain Layout
696 Only commit file format changes in the doc files if these files are using the new feature of the new file format.
702 \begin_inset CommandInset ref
704 reference "enu:The-fileformat-of"
709 of the documentation policies described in sec.
714 \begin_inset CommandInset ref
716 reference "sec:Documentation-policies"
729 \begin_layout Enumerate
732 \begin_inset Flex Code
735 \begin_layout Plain Layout
744 \begin_layout Section
745 Updating the file format number of layout files
748 \begin_layout Standard
749 The procedure for updating the layout files is similar to that in step
750 \begin_inset CommandInset ref
752 reference "enu:updatefiles"
758 \begin_inset CommandInset ref
760 reference "subsec:update_lyx_files"
767 \begin_inset Flex Code
770 \begin_layout Plain Layout
771 python development/tools/updatelayouts.py
777 \begin_inset Flex Code
780 \begin_layout Plain Layout
789 \begin_layout Standard
790 Note that we do not automatically update any local layout used in the
791 \begin_inset Flex Code
794 \begin_layout Plain Layout
800 files shipped with \SpecialChar LyX
801 because users would then not be able to export to older formats.
803 if a 2.2.0 user exported a template to 2.1.x format and tried to open the file in \SpecialChar LyX
805 there would be an error because the file would contain a local layout whose format is too new.
806 The root reason for this is that we do not support converting layouts to older layout formats,
808 \begin_inset Flex Code
811 \begin_layout Plain Layout
820 \begin_layout Section
821 Backporting new styles to the stable version
822 \begin_inset CommandInset label
824 name "subsec:Backporting-new-styles"
831 \begin_layout Standard
832 Starting with the stable \SpecialChar LyX
834 there is a mechanism in place to backport new styles to the stable version without the need to update the file format.
835 The basic idea is that the new style definition is automatically copied to the document preamble so that it can even be used by older minor versions that did not yet include the style.
836 To backport a new style to the stable version,
837 the following steps are needed:
840 \begin_layout Enumerate
842 \begin_inset Flex Code
845 \begin_layout Plain Layout
851 to the style definition in the development version.
854 \begin_layout Enumerate
855 Copy the style definition to the stable version,
857 \begin_inset Flex Code
860 \begin_layout Plain Layout
867 If needed adjust the format to the one used by the stable version (see the customization manual for details of the layout file format).
870 \begin_layout Enumerate
871 For each update of the style in a later stable version,
872 increase the argument of
873 \begin_inset Flex Code
876 \begin_layout Plain Layout
883 (In the stable version,
884 the development version should not be touched.)
887 \begin_layout Standard
888 For details about the
889 \begin_inset Flex Code
892 \begin_layout Plain Layout
898 flag see the customization manual.
900 \begin_inset Flex Code
903 \begin_layout Plain Layout
909 support is needed for backported styles:
910 Since the style of the development version has an infinite version number,
911 it will always be used.
913 since its version number is less than one,
914 the style will not be written anymore to the document header for files saved by the new version.
917 \begin_layout Section
918 Updating the file format number of bind/ui files
921 \begin_layout Standard
922 A change to the functionality of existing LFUNs can require a conversion of
923 \begin_inset Flex Code
926 \begin_layout Plain Layout
933 \begin_inset Flex Code
936 \begin_layout Plain Layout
943 and therefore an increment of the LFUN format,
944 as well as a conversion of Info insets in
945 \begin_inset Flex Code
948 \begin_layout Plain Layout
955 The latter cannot be done automatically and also requires an update of the \SpecialChar LyX
958 \begin_inset space \space{}
961 of someone who might have made a set of \SpecialChar LyX
962 teaching manuals for use in their own group.)
966 \begin_layout Plain Layout
967 \begin_inset Flex URL
970 \begin_layout Plain Layout
972 https://www.lyx.org/trac/ticket/9794
985 \begin_layout Standard
986 To update the LFUN format:
989 \begin_layout Enumerate
990 Increment the LFUN file format number in
991 \begin_inset Flex Code
994 \begin_layout Plain Layout
1003 \begin_layout Enumerate
1004 Implement the LFUN conversion in
1005 \begin_inset Flex Code
1008 \begin_layout Plain Layout
1009 lib/scripts/prefs2prefs_lfuns.py
1017 \begin_layout Enumerate
1019 \begin_inset CommandInset ref
1021 reference "enu:updatefiles"
1027 \begin_inset CommandInset ref
1029 reference "subsec:update_lyx_files"
1035 \begin_inset Flex Code
1038 \begin_layout Plain Layout
1047 \begin_inset Flex Code
1050 \begin_layout Plain Layout
1051 bash development/tools/updatelfuns.sh
1058 \begin_inset Note Note
1061 \begin_layout Plain Layout
1062 This file should really be converted to python.
1070 \begin_layout Enumerate
1071 Update Info insets in
1072 \begin_inset Flex Code
1075 \begin_layout Plain Layout
1083 increment the \SpecialChar LyX
1084 format and proceed as in
1085 \begin_inset CommandInset ref
1087 reference "subsec:update_lyx_files"
1094 \begin_inset CommandInset ref
1096 reference "enu:Describe_format"
1102 \begin_inset CommandInset ref
1104 reference "enu:updatefiles"
1110 In the lyx2lyx implementation (step
1111 \begin_inset CommandInset ref
1113 reference "enu:Add-an-entry"
1119 implement a conversion similar to the one in
1120 \begin_inset Flex Code
1123 \begin_layout Plain Layout
1124 prefs2prefs_lfuns.py
1130 as well as a corresponding reversion;
1131 for this one can use
1132 \begin_inset Flex Code
1135 \begin_layout Plain Layout
1142 \begin_inset Flex Code
1145 \begin_layout Plain Layout
1146 lib/lyx2lyx/lyx2lyx_tools.py
1155 \begin_layout Chapter
1156 New layouts and modules
1159 \begin_layout Section
1160 \begin_inset CommandInset label
1162 name "subsec:New-layouts"
1169 \begin_layout Standard
1170 Adding a new layout file to the \SpecialChar LyX
1172 \begin_inset Quotes eld
1175 officially supported
1176 \begin_inset Quotes erd
1180 You should therefore think carefully about whether you really want to do this and discuss it on lyx-devel,
1181 since you will need to be prepared to update and fix the layout if necessary.
1182 If the layout is experimental or for a rarely used document class,
1183 then it may be better to add it to the relevant portion of the \SpecialChar LyX
1185 as a user contribution.
1187 \begin_inset CommandInset href
1189 target "https://wiki.lyx.org/Layouts/Layouts"
1197 \begin_layout Standard
1198 In older versions of this document,
1199 it was stated that new layout files require a file format change.
1200 After some discussion,
1201 it was decided that this is not needed.
1205 \begin_layout Plain Layout
1207 \begin_inset CommandInset href
1209 name "the thread “Proposal for a guide on updating layouts”"
1210 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1225 here are the arguments on each side
1229 \begin_layout Description
1231 \begin_inset Quotes eld
1234 New layout files are a file format change
1235 \begin_inset Quotes erd
1241 \begin_layout Itemize
1242 All documents produced by 2.2.
1243 \begin_inset Formula $x$
1246 can always be edited and exported even if
1247 \begin_inset Formula $x$
1251 This is important for people using different machines,
1252 or exchanging work with colleagues.
1255 \begin_layout Description
1257 \begin_inset Quotes eld
1260 New layout files are not a file format change
1261 \begin_inset Quotes erd
1267 \begin_layout Itemize
1268 No new LaTeX classes can be supported in a stable version,
1269 and stable versions have a typical lifetime of 2–3 years.
1272 \begin_layout Itemize
1273 We have the same situation already with custom layout files:
1274 If a document using a custom layout file is moved between machines or people,
1275 then the layout file needs to be exchanged as well.
1276 If that is not done,
1277 then we have a fallback implemented so that such documents can still be edited,
1279 and the user gets a warning.
1283 \begin_layout Itemize
1284 The lyx2lyx script cannot do anything useful in such a case.
1288 \begin_layout Standard
1289 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1292 you should do the following:
1295 \begin_layout Enumerate
1296 Put your new layout file in
1297 \begin_inset Flex Code
1300 \begin_layout Plain Layout
1307 \begin_inset Flex Code
1310 \begin_layout Plain Layout
1311 git add lib/layouts/newlayout.layout
1316 ) so that it will be committed.
1319 \begin_layout Enumerate
1321 \begin_inset Flex Code
1324 \begin_layout Plain Layout
1331 so that the new layout actually gets installed.
1334 \begin_layout Enumerate
1336 \begin_inset Flex Code
1339 \begin_layout Plain Layout
1340 lib/doc/LaTeXConfig.lyx
1345 containing in particular a line like
1354 \begin_layout Standard
1355 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1356 \begin_inset Flex Code
1359 \begin_layout Plain Layout
1360 info-insert textclass <name>
1366 This inset will automatically display a boxed
1367 \begin_inset Quotes eld
1371 \begin_inset Quotes erd
1375 \begin_inset Quotes eld
1379 \begin_inset Quotes erd
1382 depending on the availability of the package.
1386 \begin_layout Enumerate
1387 A template or example is strongly encouraged (but not necessarily required).
1388 It is also possible to provide both.
1390 \begin_inset Flex Code
1393 \begin_layout Plain Layout
1400 \begin_inset Flex Code
1403 \begin_layout Plain Layout
1413 \begin_layout Enumerate
1414 Reconfigure \SpecialChar LyX
1418 \begin_layout Enumerate
1419 Ensure the autotests for the new layout pass (see
1420 \begin_inset CommandInset ref
1422 reference "par:when-to-run-an-export-test"
1430 \begin_layout Section
1434 \begin_layout Standard
1435 Adding a new module is very similar to adding a new layout.
1437 the previous section applies to new modules as well,
1438 with two exceptions:
1442 \begin_layout Enumerate
1443 You only need to add an entry to
1444 \begin_inset Flex Code
1447 \begin_layout Plain Layout
1448 lib/doc/LaTeXConfig.lyx
1453 if the module requires a LaTeX package.
1455 the command for entering the InsetInfo is:
1457 \begin_inset Flex Code
1460 \begin_layout Plain Layout
1461 info-insert package <name>
1469 \begin_layout Enumerate
1470 Modules do not need a template,
1472 which is strongly encouraged but not necessarily required.
1475 \begin_layout Section
1476 Layouts for document classes with incompatible versions
1479 \begin_layout Standard
1480 \begin_inset Note Greyedout
1483 \begin_layout Description
1485 This section is currently only a proposal under discussion.
1486 Please correct/amend as suited.
1487 Remove this note once a consensus is found.
1490 \begin_layout Plain Layout
1492 \begin_inset Quotes eld
1495 Proposal for a guide on updating layouts
1496 \begin_inset Quotes erd
1499 for details and background
1502 \begin_layout Plain Layout
1503 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1511 \begin_layout Standard
1513 there are changes to LaTeX document classes that break backwards compatibility.
1517 \begin_layout Plain Layout
1518 Uwe has suggested we implement automatic detection of changes in class files.
1519 This could be done by running a script every month that checks if a document class was changed at CTAN and at the homepages of the scientific journals.
1520 If it reports a change,
1521 we can check if our template and layout file are still usable with the changed document class.
1522 (This is different from the autotests insofar,
1523 as this would also catch changes that do not result in compilation errors.)
1528 Reasons can be a new name for the
1529 \begin_inset Flex Code
1532 \begin_layout Plain Layout
1539 removed \SpecialChar LaTeX
1542 How should this best be handled in \SpecialChar LyX
1547 \begin_layout Standard
1548 The idea is to support the new version with a new \SpecialChar LyX
1552 \begin_layout Itemize
1553 Existing documents can still be opened in \SpecialChar LyX
1554 and will continue to work on systems where the old version is still installed.
1558 \begin_layout Itemize
1559 With differently named
1560 \begin_inset Flex Code
1563 \begin_layout Plain Layout
1571 can check for the availability of the particular version and reflect this in the GUI.
1572 Different document class versions with the same file name are currently (2.2.x) not detected by the configuration script.
1573 This is planned for 2.3.
1577 \begin_layout Plain Layout
1578 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1581 \begin_layout Plain Layout
1583 what we really need is version detection for the configuration,
1584 so that the user can be warned if the required class file has the wrong version.
1585 (If the class file keeps the name over the version change,
1586 only one of the two layout files generates compilable documents.)
1589 \begin_layout Plain Layout
1590 This point was also made here:
1591 http://permalink.gmane.org/gmane.editors.lyx.devel/143798
1599 \begin_layout Itemize
1600 The new layout can be added both to the master and the stable branches,
1601 in accord with the policy discussed in
1602 \begin_inset CommandInset ref
1603 LatexCommand formatted
1604 reference "subsec:New-layouts"
1610 No lyx2lyx conversion is then required when a new major version is released.
1613 \begin_layout Standard
1614 The user can move an existing document to the new version simply by selecting a new document class.
1615 This step is well supported by \SpecialChar LyX
1617 with established methods for handling unsupported styles and other changes.
1619 no lyx2lyx code is required.
1622 \begin_layout Standard
1623 The steps to support a new version of an existing document class are thus:
1626 \begin_layout Itemize
1627 Create a new layout file including the upstream version in the name (avoid special characters like spaces and dots),
1630 \begin_inset Flex Code
1633 \begin_layout Plain Layout
1634 acmsiggraph-v0-92.layout
1642 \begin_layout Itemize
1643 Include the name of the
1644 \begin_inset Flex Code
1647 \begin_layout Plain Layout
1653 file as an optional argument in the
1654 \begin_inset Flex Code
1657 \begin_layout Plain Layout
1665 line and include the version number in the GUI name:
1666 \begin_inset Newline newline
1670 \begin_inset Flex Code
1673 \begin_layout Plain Layout
1676 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1677 \begin_inset space ~
1688 \begin_layout Itemize
1689 Update the GUI name in the old layout file (whose name should not be changed),
1691 \begin_inset Newline newline
1695 \begin_inset Flex Code
1698 \begin_layout Plain Layout
1701 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1702 \begin_inset space ~
1714 \begin_layout Itemize
1715 To avoid duplicate definitions,
1717 \begin_inset Flex Code
1720 \begin_layout Plain Layout
1726 the old layout file and add\SpecialChar breakableslash
1727 remove\SpecialChar breakableslash
1728 obsolete\SpecialChar breakableslash
1729 modify settings and styles (similar to the inclusion of
1730 \begin_inset Flex Code
1733 \begin_layout Plain Layout
1743 \begin_layout Standard
1744 It may be tempting to let the new layout be the
1745 \begin_inset Quotes eld
1749 \begin_inset Quotes erd
1752 and have the old layout import it.
1754 this should not be done because any changes to the new layout would need undo steps in the importing old layout.
1758 \begin_layout Itemize
1759 If the new LaTeX document class obsoletes the old one,
1760 update the example and template files to use the new layout.
1761 Add a note about the changes (preferably with a pointer to the documentation of the changes).
1765 \begin_layout Standard
1767 new documents based on the template or example will use the up-to-date document class version.
1771 \begin_layout Standard
1772 \begin_inset Newpage newpage
1778 \begin_layout Chapter
1782 \begin_layout Standard
1783 Automated tests are an important tool to detect bugs and regressions in software development.
1784 Some projects like gcc even require each bug fix to be accompanied by a test case for the automatic test suite,
1785 that would detect this bug.
1786 Testing interactive features automatically is of course very hard,
1787 but core functionality like document import and export can be tested quite easily,
1788 and some tests of this kind exist.
1791 \begin_layout Section
1795 \begin_layout Standard
1796 There are attempts to set up a suite of unit tests for LyX.
1799 \begin_layout Standard
1801 describe what is done and what is still to do.
1804 \begin_layout Section
1808 \begin_layout Standard
1809 The tex2lyx tests are located in the
1810 \begin_inset Flex Code
1813 \begin_layout Plain Layout
1819 subfolder of the \SpecialChar LyX
1820 source code distribution.
1821 The actual testing is performed by the simple python script
1822 \begin_inset Flex Code
1825 \begin_layout Plain Layout
1826 src/tex2lyx/test/runtests.py
1832 Each test consists of two files:
1834 \begin_inset Flex Code
1837 \begin_layout Plain Layout
1843 contains the \SpecialChar LaTeX
1844 code that should be tested.
1846 \begin_inset Flex Code
1849 \begin_layout Plain Layout
1855 contains the expected output of tex2lyx.
1857 the actual produced output is compared with the stored reference output.
1858 The test passes if both are identical.
1859 The test machinery is also able to generate a file
1860 \begin_inset Flex Code
1863 \begin_layout Plain Layout
1869 by exporting the produced .lyx file with \SpecialChar LyX
1871 This may be useful for roundtrip comparisons.
1874 \begin_layout Subsection
1878 \begin_layout Standard
1879 The tex2lyx tests can be run in several ways.
1881 \begin_inset Flex Code
1884 \begin_layout Plain Layout
1890 subfolder of the build directory,
1892 \begin_inset Flex Code
1895 \begin_layout Plain Layout
1904 \begin_inset Flex Code
1907 \begin_layout Plain Layout
1914 when using a make based build system and not MSVC) or
1915 \begin_inset Flex Code
1918 \begin_layout Plain Layout
1924 (autotools) will run the tex2lyx tests.
1926 in the root of the build directory,
1928 \begin_inset Flex Code
1931 \begin_layout Plain Layout
1937 runs all tests whose names match the regex
1938 \begin_inset Quotes eld
1942 \begin_inset Quotes erd
1946 Another way to run the tex2lyx tests in the root build directory is to instead use the command
1947 \begin_inset Flex Code
1950 \begin_layout Plain Layout
1951 ctest -L '(cmplyx|roundtrip)'
1957 which runs all tests categorized with the label
1958 \begin_inset Quotes eld
1962 \begin_inset Quotes erd
1966 \begin_inset Quotes eld
1970 \begin_inset Quotes erd
1975 the differences between the expected and actual results are output in unified diff format.
1978 \begin_layout Subsection
1979 Updating test references
1980 \begin_inset CommandInset label
1982 name "sec:Updating-test-references"
1989 \begin_layout Standard
1990 In some cases a changed tex2lyx output is not a test failure,
1993 \begin_inset space \thinspace{}
1997 \begin_inset space \space{}
2000 if a tex2lyx bug was fixed,
2001 or a new feature was added.
2002 In these cases the stored references need to be updated.
2003 To do so if using autotools,
2005 \begin_inset Flex Code
2008 \begin_layout Plain Layout
2015 \begin_inset Flex Code
2018 \begin_layout Plain Layout
2024 subdirectory of the build directory.
2025 If instead using CMake,
2027 \begin_inset Flex Code
2030 \begin_layout Plain Layout
2031 make updatetex2lyxtests
2036 in the build directory or in the
2037 \begin_inset Flex Code
2040 \begin_layout Plain Layout
2046 subdirectory of the build directory.
2050 \begin_layout Plain Layout
2051 Note that this is a case where a make target in the build directory can affect the source directory,
2052 which might not be advisable.
2057 On Windows do the following:
2060 \begin_layout Itemize
2061 Assure that the path to the python.exe is in your system PATH variable.
2064 \begin_layout Itemize
2065 Double-click on the file
2066 \begin_inset Flex Code
2069 \begin_layout Plain Layout
2070 updatetex2lyxtests.vcxproj
2075 in the build directory or in the
2076 \begin_inset Flex Code
2079 \begin_layout Plain Layout
2085 subdirectory of your build directory.
2088 \begin_layout Itemize
2089 In the appearing MSVC program assure that you build the
2094 then right-click on the project
2098 in the project explorer and choose then
2101 \begin_inset space ~
2104 Only\SpecialChar menuseparator
2106 \begin_inset space ~
2114 \begin_layout Standard
2116 these commands also produce re-exported roundtrip .lyx.tex files.
2117 Please examine the changed output carefully before committing the changed files to the repository:
2118 Since the test machinery does not do a roundtrip test .tex
2119 \begin_inset Formula $\Rightarrow$
2123 \begin_inset Formula $\Rightarrow$
2127 and does not compare the produced dvi or pdf output,
2128 it assumes that the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2130 There is only one chance to detect wrong output:
2131 before committing a new reference.
2132 Once it is committed,
2133 it is quite difficult to verify whether it is correct.
2136 \begin_layout Standard
2141 update the test references by opening them with \SpecialChar LyX
2142 or directly running lyx2lyx on them.
2143 This would not work,
2144 since lyx2lyx and \SpecialChar LyX
2145 produce slightly different files regarding insignificant whitespace and line breaks.
2148 \begin_layout Subsection
2152 \begin_layout Standard
2153 In many cases tests for new features may be added to one of the existing test files,
2154 but sometimes this is not possible or not wanted.
2155 Then a new test file needs to be added:
2158 \begin_layout Enumerate
2160 \begin_inset Flex Code
2163 \begin_layout Plain Layout
2164 src/tex2lyx/test/<test name>.tex
2169 and run tex2lyx in roundtrip mode to produce the file
2170 \begin_inset Flex Code
2173 \begin_layout Plain Layout
2174 src/tex2lyx/test/<test name>.lyx.lyx
2180 This file will be the new reference.
2183 \begin_layout Enumerate
2184 Once you confirmed that the tex2lyx output is correct,
2185 add the new files to the corresponding lists in
2186 \begin_inset Flex Code
2189 \begin_layout Plain Layout
2190 src/tex2lyx/test/runtests.py
2197 \begin_inset Flex Code
2200 \begin_layout Plain Layout
2201 src/tex2lyx/Makefile.am
2207 \begin_inset Flex Code
2210 \begin_layout Plain Layout
2211 src/tex2lyx/test/CMakeLists.txt
2219 \begin_layout Enumerate
2220 Commit the changes to the repository,
2221 or send a patch to the development list and ask for committing if you do not have commit rights.
2224 \begin_layout Section
2225 ctest automatic tests
2228 \begin_layout Standard
2229 Some tests are located in the
2230 \begin_inset Flex Code
2233 \begin_layout Plain Layout
2234 development/autotests/
2239 subfolder of the \SpecialChar LyX
2240 source code distribution.
2245 \begin_layout Plain Layout
2246 The README document in this folder only describes the
2247 \begin_inset Quotes eld
2251 \begin_inset Quotes erd
2254 subset of autotests!
2262 \begin_layout Standard
2263 These tests can be run by the commands
2264 \begin_inset Flex Code
2267 \begin_layout Plain Layout
2277 (all platforms) or (when using a make based build system and not MSVC)
2278 \begin_inset Flex Code
2281 \begin_layout Plain Layout
2288 \begin_inset Flex Code
2291 \begin_layout Plain Layout
2302 The test logs are written to the
2303 \begin_inset Flex Code
2306 \begin_layout Plain Layout
2320 \begin_layout Subsection
2324 \begin_layout Standard
2325 The export tests are integration tests.
2326 They take longer to run and are more likely to break than the tex2lyx tests.
2328 they have caught many regressions and without a better alternative it is important to keep them up-to-date and understand how they work.
2331 \begin_layout Standard
2333 \begin_inset Quotes eld
2337 \begin_inset Quotes erd
2342 and example documents.
2344 there are a number of dedicated sample documents in the
2345 \begin_inset Flex Code
2348 \begin_layout Plain Layout
2354 subfolder of the \SpecialChar LyX
2355 source code distribution.
2356 All samples are (after copying and eventual processing by scripts) exported to various output formats via the
2357 \begin_inset Flex Code
2360 \begin_layout Plain Layout
2367 command line option.
2368 The tests checks for errors reported by LyX.
2370 error-free export is no guarantee for an error-free output document.)
2373 \begin_layout Subsubsection
2374 \begin_inset CommandInset label
2376 name "par:when-to-run-an-export-test"
2380 Expectations of LyX developers
2383 \begin_layout Standard
2384 Because the export tests are integration tests and take a long time to run,
2385 LyX developers are rarely expected to run all of the tests.
2386 Here are some good practices to follow by developers:
2389 \begin_layout Itemize
2390 When making a non-trivial change to a .layout file,
2391 run the export and layout tests corresponding with that .layout file.
2394 \begin_layout Itemize
2395 When making non-trivial changes to a .lyx file,
2396 run the export tests corresponding to that .lyx file.
2401 \begin_layout Plain Layout
2402 This rule is due to revision.
2406 \begin_layout Plain Layout
2407 There is an objection from the documentation maintainer that working on the documentation must not be complicated by having to consider non-standard exports.
2410 \begin_layout Itemize
2411 successful compiling/testing an edited documentation file with pdflatex suffices to ensure it can be commited,
2412 not tests with other exports are required.
2415 \begin_layout Plain Layout
2416 If sudden failures with other exports due to “half-tested” documentation updates are a problem for the test maintainer,
2417 the test suite should use copies that are
2420 \begin_layout Itemize
2421 copied to a cache dir (autotests/samples/doc/,
2422 say) but not changed,
2425 \begin_layout Itemize
2426 updated regularely (but on a time chosen by the test suite maintainer) from the originals in lib/doc/
2429 \begin_layout Plain Layout
2434 \begin_layout Itemize
2435 no test will fail due to ongoing work on documentation,
2438 \begin_layout Itemize
2439 the documentation is still tested in full (with some delay),
2442 \begin_layout Itemize
2443 failures with non-default export can be examined and handled accordingly in one run with the cache update,
2446 \begin_layout Itemize
2447 “interesting failures” (like the nested-language+polyglossia problem in es/Customization can be separated and moved into dedicated test samples.
2455 \begin_layout Itemize
2456 When making non-trivial changes to LyX's \SpecialChar LaTeX
2458 touching the encoding code or package handling code that you expect will change the exported \SpecialChar LaTeX
2463 \begin_layout Standard
2464 \paragraph_spacing single
2465 Consider running all of the export tests before and after your change.
2466 If there are differences,
2467 please reconcile these (i.e.
2468 fix the bug or fix the tests)
2473 Ask for help if you're not sure what to.
2476 \begin_layout Standard
2477 If you do not want to run the tests,
2480 \begin_layout Itemize
2481 post the patch on the list and others will run the tests and eventually ask for fixes,
2485 \begin_layout Itemize
2487 but be prepared to fix eventually arising problems or to revert the commit if there is no easy fix.
2491 \begin_layout Itemize
2492 Understand how to interpret test failures.
2493 If your commit is found to have broken a test,
2494 you should be able to interpret the test results when made aware of them.
2496 \begin_inset CommandInset ref
2498 reference "subsec:Interpreting-export-tests"
2506 \begin_layout Subsubsection
2507 \begin_inset CommandInset label
2509 name "par:export-test-output-formats"
2516 \begin_layout Standard
2517 The following output formats are currently tested for each sample document (see
2518 \begin_inset CommandInset ref
2520 reference "par:Export-test-filtering"
2528 \begin_layout Labeling
2529 \labelwidthstring 00.00.0000
2534 \begin_layout Labeling
2535 \labelwidthstring 00.00.0000
2536 lyx16 LyX 1.6 file format (lyx2lyx)
2539 \begin_layout Labeling
2540 \labelwidthstring 00.00.0000
2541 lyx21 LyX 2.1 file format (lyx2lyx)
2544 \begin_layout Labeling
2545 \labelwidthstring 00.00.0000
2546 xhtml LyXHTML (native LyX HTML export)
2550 \begin_layout Labeling
2551 \labelwidthstring 00.00.0000
2553 \begin_inset space ~
2557 \begin_inset space ~
2564 \begin_layout Labeling
2565 \labelwidthstring pdf5msystemFM
2566 dvi DVI (8-bit latex)
2569 \begin_layout Labeling
2570 \labelwidthstring pdf5msystemFM
2571 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2574 \begin_layout Labeling
2575 \labelwidthstring pdf5msystemFM
2576 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2579 \begin_layout Labeling
2580 \labelwidthstring pdf5msystemFM
2584 \begin_layout Labeling
2585 \labelwidthstring pdf5msystemFM
2586 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2589 \begin_layout Labeling
2590 \labelwidthstring pdf5msystemFM
2591 pdf4_systemF PDF (XeTeX with Unicode fonts)
2594 \begin_layout Labeling
2595 \labelwidthstring pdf5msystemFM
2596 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2599 \begin_layout Labeling
2600 \labelwidthstring pdf5msystemFM
2601 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2605 \begin_layout Labeling
2606 \labelwidthstring 00.00.0000
2608 \begin_inset space ~
2612 \begin_inset space ~
2616 \begin_inset space ~
2620 \begin_inset space ~
2627 \begin_layout Labeling
2628 \labelwidthstring pdf5msystemFM
2629 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2632 \begin_layout Labeling
2633 \labelwidthstring pdf5msystemFM
2634 pdf3 DVI -> PDF (dvipdfm)
2638 \begin_layout Labeling
2639 \labelwidthstring 00.00.0000
2641 \begin_inset space ~
2645 (or only if set as default output format in the document source)
2649 \begin_layout Labeling
2650 \labelwidthstring pdf5msystemFM
2654 \begin_layout Labeling
2655 \labelwidthstring pdf5msystemFM
2656 luatex LaTeX (LuaTeX)
2659 \begin_layout Labeling
2660 \labelwidthstring pdf5msystemFM
2661 dviluatex LaTeX (dviluatex)
2664 \begin_layout Labeling
2665 \labelwidthstring pdf5msystemFM
2666 pdflatex LaTeX (pdflatex)
2669 \begin_layout Labeling
2670 \labelwidthstring pdf5msystemFM
2671 platex LaTeX (pLaTeX)
2674 \begin_layout Labeling
2675 \labelwidthstring pdf5msystemFM
2679 \begin_layout Labeling
2680 \labelwidthstring pdf5msystemFM
2681 eps3 EPS (encapsulated Postscript) (cropped)
2684 \begin_layout Labeling
2685 \labelwidthstring pdf5msystemFM
2686 ps DVI -> Postscript (dvips)
2689 \begin_layout Labeling
2690 \labelwidthstring pdf5msystemFM
2694 \begin_layout Labeling
2695 \labelwidthstring pdf5msystemFM
2701 \begin_layout Labeling
2702 \labelwidthstring pdf5msystemFM
2706 \begin_layout Labeling
2707 \labelwidthstring pdf5msystemFM
2711 \begin_layout Labeling
2712 \labelwidthstring pdf5msystemFM
2716 \begin_layout Labeling
2717 \labelwidthstring pdf5msystemFM
2722 \begin_layout Subsubsection
2723 \begin_inset CommandInset label
2725 name "par:Configuring-ctests"
2729 Configuring the tests
2732 \begin_layout Standard
2733 To enable the export autotests,
2735 \begin_inset Flex Code
2738 \begin_layout Plain Layout
2739 -DLYX_ENABLE_EXPORT_TESTS=ON
2748 \begin_layout Standard
2749 \begin_inset Flex Code
2752 \begin_layout Plain Layout
2753 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2761 \begin_layout Standard
2763 This flag will increase the time for the cmake command by several seconds,
2764 mainly because of the process of inverting tests (see Section
2765 \begin_inset CommandInset ref
2767 reference "subsec:Interpreting-export-tests"
2775 \begin_layout Subsubsection
2776 \begin_inset CommandInset label
2778 name "par:ctest-options"
2785 \begin_layout Standard
2787 in the build directory simply run the command
2788 \begin_inset Flex Code
2791 \begin_layout Plain Layout
2799 up-to-date TeXLive installation is recommended to run the tests.
2801 some tests will fail.
2802 Tests with additional requirements are labeled
2803 \begin_inset Quotes eld
2806 unreliable:nonstandard
2807 \begin_inset Quotes erd
2814 \begin_layout Standard
2815 To run only some of the tests,
2816 use command line options (see examples below):
2819 \begin_layout Labeling
2820 \labelwidthstring -R
2821 \begin_inset Flex Code
2824 \begin_layout Plain Layout
2830 Run only the tests whose names match the given regular expression.
2833 \begin_layout Labeling
2834 \labelwidthstring -R
2835 \begin_inset Flex Code
2838 \begin_layout Plain Layout
2844 Run only the tests whose labels match the given regular expression.
2845 A test may have more that one label.
2849 \begin_layout Labeling
2850 \labelwidthstring -R
2851 \begin_inset Flex Code
2854 \begin_layout Plain Layout
2860 Exclude the tests whose names match the given regular expression.
2863 \begin_layout Labeling
2864 \labelwidthstring -R
2865 \begin_inset Flex Code
2868 \begin_layout Plain Layout
2874 Exclude the tests whose labels match the given regular expression.
2875 Cannot be combined with
2876 \begin_inset Flex Code
2879 \begin_layout Plain Layout
2888 \begin_layout Standard
2889 The following options help to find good selection patterns:
2892 \begin_layout Labeling
2893 \labelwidthstring -R
2894 \begin_inset Flex Code
2897 \begin_layout Plain Layout
2903 List the tests that would be run but not actually run them.
2908 \begin_layout Standard
2909 Useful in conjunction with the -R,
2913 if you want to know how many tests there are or whether your
2914 \begin_inset Flex Code
2917 \begin_layout Plain Layout
2923 regular expression did what you expected.
2927 \begin_layout Labeling
2928 \labelwidthstring -R
2929 \begin_inset Flex Code
2932 \begin_layout Plain Layout
2933 \SpecialChar nobreakdash
2934 \SpecialChar nobreakdash
2940 print the list of all labels associated with the test set.
2941 Can also be combined with -R,
2948 \begin_layout Standard
2949 Other useful options are:
2952 \begin_layout Labeling
2953 \labelwidthstring -R
2954 \begin_inset Flex Code
2957 \begin_layout Plain Layout
2963 Run the tests in parallel using the given number of jobs.
2967 \begin_layout Standard
2968 We are still working on getting the tests to run in parallel.
2970 when running the tests in parallel,
2971 sometimes tests fail that pass when run sequentially.
2972 A reasonable approach is to first run the tests in parallel and then run the failed tests sequentially.
2975 \begin_layout Standard
2977 to run 8 jobs at a time:
2980 \begin_layout Standard
2981 \begin_inset Flex Code
2984 \begin_layout Plain Layout
2993 \begin_layout Standard
2994 \begin_inset Flex Code
2997 \begin_layout Plain Layout
2998 ctest \SpecialChar nobreakdash
2999 \SpecialChar nobreakdash
3008 \begin_layout Standard
3009 When specifying a subset of the tests (e.g.
3011 \begin_inset Flex Code
3014 \begin_layout Plain Layout
3015 \SpecialChar nobreakdash
3022 the same subset must be specified when using the
3023 \begin_inset Flex Code
3026 \begin_layout Plain Layout
3027 \SpecialChar nobreakdash
3028 \SpecialChar nobreakdash
3034 option because it is the test numbers that are used to index which tests failed on the previous run.
3037 \begin_layout Standard
3039 Note that some tests cannot be run in parallel.
3040 These tests are marked in the code with the
3041 \begin_inset Flex Code
3044 \begin_layout Plain Layout
3054 \begin_layout Labeling
3055 \labelwidthstring -R
3056 \begin_inset Flex Code
3059 \begin_layout Plain Layout
3060 \SpecialChar nobreakdash
3061 \SpecialChar nobreakdash
3067 Set a global timeout on all tests that do not already have a timeout set on them.
3071 \begin_layout Standard
3072 There have been bugs in LyX and in \SpecialChar LaTeX
3073 which cause compilation to hang,
3074 and without a timeout a test might never stop (in one case there was even a memory leak).
3075 If a test times out,
3077 \begin_inset Flex Code
3080 \begin_layout Plain Layout
3086 command exits with error,
3087 but you can distinguish between a timed out test and a failed test in the output reported at the end of the
3088 \begin_inset Flex Code
3091 \begin_layout Plain Layout
3101 \begin_layout Standard
3103 \begin_inset Flex Code
3106 \begin_layout Plain Layout
3112 ) the full list of command line options.
3115 \begin_layout Subsubsection
3119 \begin_layout Itemize
3120 run only the export tests:
3122 \begin_inset Flex Code
3125 \begin_layout Plain Layout
3134 \begin_layout Itemize
3137 \begin_inset Flex Code
3140 \begin_layout Plain Layout
3141 ctest -L "inverted|suspended"
3149 \begin_layout Itemize
3150 list all export tests which match any of the labelling patterns:
3152 \begin_inset Flex Code
3155 \begin_layout Plain Layout
3166 \begin_layout Itemize
3167 exclude rarely used output formats and post-processing tests
3168 \begin_inset Flex Code
3171 \begin_layout Plain Layout
3172 ctest -L export -E "_(texF|dvi3|pdf3?)"
3180 \begin_layout Subsubsection
3181 \begin_inset CommandInset label
3183 name "subsec:Interpreting-export-tests"
3187 Interpreting the export test results
3190 \begin_layout Standard
3191 A test can fail for several reasons,
3192 not all of them bad.
3195 \begin_layout Enumerate
3196 A new or edited sample document may be incompatible with some output formats.
3199 \begin_layout Enumerate
3200 A dependency is not met (e.g.
3201 the \SpecialChar LaTeX
3203 One hint that this is the case is that the corresponding
3204 \begin_inset Flex Code
3207 \begin_layout Plain Layout
3213 test will likely also fail.
3216 \begin_layout Enumerate
3217 An inverted test fails to fail (i.e.
3218 export that previously failed now works).
3221 \begin_layout Enumerate
3222 An external dependency was updated (e.g.
3227 \begin_layout Enumerate
3228 A recent code change introduced a bug.
3231 \begin_layout Enumerate
3232 \begin_inset CommandInset label
3238 A change in a document exposed a previously unknown bug or an incompatibility with an export format (e.g.
3239 Lua\SpecialChar LaTeX
3243 \begin_layout Standard
3244 Because the .lyx files are exported in several formats,
3245 it is not surprising that many of the exports fail.
3246 This expectation of failure is addressed by
3247 \begin_inset Quotes eld
3251 \begin_inset Quotes erd
3256 by marking the test as
3257 \begin_inset Quotes eld
3261 \begin_inset Quotes erd
3264 if the export exits with error and as
3265 \begin_inset Quotes eld
3269 \begin_inset Quotes erd
3272 if the export succeeds
3277 It follows that these expected failures will not show up as failed tests in the test results and thus will not pollute the
3278 \begin_inset Quotes eld
3282 \begin_inset Quotes erd
3286 If the export actually succeeds,
3287 then the test will fail.
3288 The purpose of this failure is to get your attention—
3289 something has changed,
3290 possibly for the better.
3293 \begin_layout Standard
3294 We try to document why a test is inverted or ignored.
3295 See the comment (prefixed with
3296 \begin_inset Flex Code
3299 \begin_layout Plain Layout
3305 ) above the block in which the test is listed as inverted or ignored in the files
3306 \begin_inset Flex Code
3309 \begin_layout Plain Layout
3310 development/autotests/invertedTests
3317 \begin_inset Flex Code
3320 \begin_layout Plain Layout
3321 development/autotests/unreliableTests
3327 \begin_inset Flex Code
3330 \begin_layout Plain Layout
3331 development/autotests/ignoredTests
3340 \begin_layout Standard
3341 A good question is why do we enable the tests for non-default formats?
3342 The answer is that if a non-default route is broken it is often because a bug was introduced in LyX and not because a document-specific change was made that is not supported by the route.
3344 there is a high signal/noise ratio in the export tests for some non-default formats.
3348 \begin_layout Standard
3349 When a test or several tests fail,
3350 consider checking the files in the
3351 \begin_inset Flex Code
3354 \begin_layout Plain Layout
3360 subdirectory of your build directory.
3361 In this subdirectory are three files:
3363 \begin_inset Flex Code
3366 \begin_layout Plain Layout
3372 simply lists the tests that failed on your last
3373 \begin_inset Flex Code
3376 \begin_layout Plain Layout
3384 \begin_inset Flex Code
3387 \begin_layout Plain Layout
3393 file contains the output from the tests (and often has details explaining why a test failed);
3395 \begin_inset Flex Code
3398 \begin_layout Plain Layout
3404 file lists the times that it took to run the tests.
3407 \begin_layout Subsubsection
3408 What action should you take if a test fails?
3411 \begin_layout Standard
3412 \paragraph_spacing single
3413 It is always good to check manually why something fails and if it passes if the PDF output is good.
3416 \begin_layout Itemize
3418 if a change breaks compilation for the target format (for the manuals pdf2) without solving some important other issue,
3421 fix or revert the commit
3423 that led to failure.
3426 \begin_layout Itemize
3427 If it is not possible to (immediately) fix the failure but there are reasons not to revert the commit (e.g.
3428 it fixes another more important issue),
3433 the failing test case (see
3434 \begin_inset CommandInset ref
3436 reference "par:Inverted-tests"
3444 \begin_layout Itemize
3449 test case fails because the export now works,
3450 first confirm that the output of the corresponding export looks good (e.g.,
3457 the test by removing the pattern from the
3458 \begin_inset Quotes eld
3462 \begin_inset Quotes erd
3466 \begin_inset CommandInset ref
3468 reference "par:Inverted-tests"
3476 \begin_layout Itemize
3477 If the export did not fail previously but led to wrong output (PDF,
3482 \begin_layout Plain Layout
3483 Non-failing test with wrong output should be labeled as
3484 \begin_inset Quotes eld
3487 unreliable:wrong_output
3488 \begin_inset Quotes erd
3492 \begin_inset CommandInset ref
3494 reference "par:Unreliable-tests"
3504 it is in fact an improvement when the test now fails.
3509 the failing test case (see
3510 \begin_inset CommandInset ref
3512 reference "par:Inverted-tests"
3520 \begin_layout Itemize
3521 In case of tests failing due to missing requirements (tests labeled
3522 \begin_inset Quotes eld
3525 unreliable:nonstandard
3526 \begin_inset Quotes erd
3529 or testing on a system with only a subset of TeXLive installed),
3531 ask for someone else to run the test,
3532 or install the missing resources and try again.
3535 \begin_layout Itemize
3536 Check the log file Testing/Temporary/LastTest.log.
3537 In case of latex-errors rerun the failing test with environment variable 'LYX_DEBUG_LATEX' set to '1'.
3538 This will include latex messages in LastTest.log,
3539 so it should be easier to interpret the fail-reason.
3542 \begin_layout Subsubsection
3543 \begin_inset CommandInset label
3545 name "par:Inverted-tests"
3552 \begin_layout Standard
3553 Test cases whose name matches a pattern in the file
3554 \begin_inset Flex Code
3557 \begin_layout Plain Layout
3558 development/autotests/invertedTests
3568 They get also the test property
3569 \begin_inset Flex Code
3572 \begin_layout Plain Layout
3580 they are reported as failing if the export works without error
3581 \begin_inset Flex URL
3584 \begin_layout Plain Layout
3586 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3594 \begin_layout Standard
3595 Add failing cases to this file,
3596 if they cannot be solved
3597 \begin_inset Quotes eld
3601 \begin_inset Quotes erd
3604 but it is expected that the export will work in a foreseeable future,
3606 low priority issues like failures to export to a non-target format (for the manuals everything except pdf2).
3609 \begin_layout Standard
3610 The following sublabels are currently present in
3611 \begin_inset Flex Code
3614 \begin_layout Plain Layout
3623 \begin_layout Description
3624 todo test failures that require attention:
3628 \begin_layout Itemize
3629 minor issues to explore and properly sort later,
3633 \begin_layout Itemize
3637 \begin_layout Itemize
3638 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3642 \begin_layout Description
3643 lyxbugs LyX bugs with a Trac number.
3646 \begin_layout Description
3647 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3651 \begin_layout Standard
3652 "Wontfix" if demonstrating correct use and OK in the default output format.
3656 \begin_layout Description
3657 texissues Export fails due to LaTeX limitations like non-ASCII characters in verbatim or listings,
3658 incompatible packages,
3663 \begin_layout Standard
3664 "Wontfix" if documents demonstrate correct use in the default output format:
3667 \begin_layout Itemize
3668 If the source can be made more robust without becoming "hackish",
3672 \begin_layout Itemize
3673 if LyX could be enhanced to care for a permanent TeX limitation,
3674 file a ticket at trac and add a pattern under lyxbugs,
3677 \begin_layout Itemize
3683 \begin_layout Description
3684 attic Documents in the attic (kept for reference and format conversion test).
3686 \begin_inset Quotes eld
3690 \begin_inset Quotes erd
3696 \begin_layout Paragraph
3700 \begin_layout Standard
3701 Test cases whose name additionally matches a pattern in the file
3702 \begin_inset Flex Code
3705 \begin_layout Plain Layout
3706 development/autotests/suspendedTests
3724 This means they are not executed using
3725 \begin_inset Flex Code
3728 \begin_layout Plain Layout
3735 \begin_inset Flex Code
3738 \begin_layout Plain Layout
3746 they also get the test property
3747 \begin_inset Flex Code
3750 \begin_layout Plain Layout
3758 they are reported as failing if the export works without error.
3759 From time to time they still have to be checked using
3760 \begin_inset Flex Code
3763 \begin_layout Plain Layout
3772 \begin_layout Standard
3773 These tests are suspended,
3774 because the export fails for known reasons which cannot ATM be resolved.
3775 But it is expected the reason might disappear in the future.
3776 Be it new TL or better handling in \SpecialChar LyX
3780 \begin_layout Standard
3781 For ctest commands without the
3782 \begin_inset Flex Code
3785 \begin_layout Plain Layout
3791 parameter nothing changes.
3793 tests will be executed depending only on the selecting regular expression given to the ctest command (see
3794 \begin_inset CommandInset ref
3796 reference "par:ctest-options"
3804 \begin_layout Subsubsection
3805 \begin_inset CommandInset label
3807 name "par:Unreliable-tests"
3814 \begin_layout Standard
3815 Test cases whose name matches a pattern in the file
3816 \begin_inset Flex Code
3819 \begin_layout Plain Layout
3820 development/autotests/unreliableTests
3832 \begin_layout Standard
3833 These tests are not executed using
3834 \begin_inset Flex Code
3837 \begin_layout Plain Layout
3844 \begin_inset Flex Code
3847 \begin_layout Plain Layout
3857 \begin_layout Standard
3858 They pass or fail for various reasons not related to LyX (nonstandard,
3859 erratic) or pass but should rather fail (wrong output).
3861 \begin_inset Note Note
3864 \begin_layout Plain Layout
3865 *invalid* tests (wrong output) are not *unreliable*.
3866 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3875 \begin_layout Standard
3876 The following sublabels are currently present in
3877 \begin_inset Flex Code
3880 \begin_layout Plain Layout
3889 \begin_layout Description
3890 nonstandard Documents with additional requirements,
3892 a class or package file not in TeXLive.
3894 \begin_inset Note Note
3897 \begin_layout Plain Layout
3900 \begin_inset Quotes eld
3904 \begin_inset Quotes erd
3908 \begin_inset Quotes eld
3912 \begin_inset Quotes erd
3923 \begin_layout Description
3924 erratic Tests depending on local configuration or the phase of the moon.
3928 \begin_layout Description
3929 varying_versions Tests depending on e.g.
3930 OS or version of a non-TeX-Live dependency.
3932 up-to-date TeX Live installation is required so this sublabel is about versions of other dependencies.
3935 \begin_layout Description
3937 \begin_inset space ~
3940 output Export does not fail but the resulting document has (undetected) errors.
3944 \begin_layout Standard
3945 \paragraph_spacing single
3946 \begin_inset Note Note
3949 \begin_layout Plain Layout
3950 \paragraph_spacing single
3951 These tests are in a strict sense not unreliable but
3955 (not measuring what they should measure).
3964 \begin_layout Subsubsection
3965 \begin_inset CommandInset label
3967 name "par:Export-test-filtering"
3971 Export test filtering
3974 \begin_layout Standard
3975 The assignment of a label to a test is controlled by a set of files with regular expressions that are matched against the test names.
3978 \begin_layout Description
3979 ignoredTests (small file)
3980 \begin_inset Newline newline
3983 Tests selected here are withdrawn in the configuration step (cf.
3985 \begin_inset CommandInset ref
3987 reference "par:Configuring-ctests"
3996 \begin_layout Labeling
3997 \labelwidthstring 00.00.0000
3998 Input Test of any export combination
4001 \begin_layout Labeling
4002 \labelwidthstring 00.00.0000
4003 Output Stop if tests not selected here
4007 \begin_layout Description
4009 Tests selected pass or fail dependent on the system where the test is run.
4010 Selected tests gain the label 'unreliable'.
4014 \begin_layout Labeling
4015 \labelwidthstring 00.00.0000
4016 Input Each test which passed 'ignoredTests'
4019 \begin_layout Labeling
4020 \labelwidthstring 00.00.0000
4021 Output Gain label 'unreliable',
4022 proceed with checking for 'inverted'.
4026 \begin_layout Description
4028 \begin_inset space \space{}
4035 \begin_layout Labeling
4036 \labelwidthstring 00.00.0000
4037 Input Each test which passed 'ignoredTests'
4040 \begin_layout Labeling
4041 \labelwidthstring 00.00.0000
4042 Output Stop if not selected,
4043 gain test-property 'WILL_FAIL' (i.e.
4044 tests are reported as failing if the export works without error.) If no subselection applies,
4045 gain labels 'export' and 'inverted'.
4048 \begin_layout Standard
4049 The following filter perfoms a subselection of 'invertedTests':
4052 \begin_layout Description
4053 suspendedTests Tests selected here gain the label 'suspended' but _not_ 'export' or 'inverted',
4054 although in ctest they remain inverted.
4055 ('ctest' knows only 'inverted' or not,
4056 labels are used only for test selection)
4060 \begin_layout Labeling
4061 \labelwidthstring 00.00.0000
4062 Input Each test selected by 'invertedTests'
4065 \begin_layout Labeling
4066 \labelwidthstring 00.00.0000
4067 Output Selected test gains label 'suspended'.
4073 \begin_layout Standard
4074 The following table may clarify label assignement
4077 \begin_layout Standard
4078 \begin_inset space \hspace{}
4083 \begin_inset Tabular
4084 <lyxtabular version="3" rows="6" columns="8">
4085 <features tabularvalignment="middle">
4086 <column alignment="left" valignment="top" width="2cm">
4087 <column alignment="left" valignment="top" width="2.5cm">
4088 <column alignment="left" valignment="top" width="2cm">
4089 <column alignment="center" valignment="top" width="2.5cm">
4090 <column alignment="center" valignment="top">
4091 <column alignment="center" valignment="top">
4092 <column alignment="center" valignment="top">
4093 <column alignment="center" valignment="top">
4095 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4098 \begin_layout Plain Layout
4099 Test matching pattern in file:
4104 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4107 \begin_layout Plain Layout
4113 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4116 \begin_layout Plain Layout
4122 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4125 \begin_layout Plain Layout
4131 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4134 \begin_layout Plain Layout
4140 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4143 \begin_layout Plain Layout
4149 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4152 \begin_layout Plain Layout
4158 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4161 \begin_layout Plain Layout
4169 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4172 \begin_layout Plain Layout
4173 ignored\SpecialChar softhyphen
4179 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4182 \begin_layout Plain Layout
4183 unreliable\SpecialChar softhyphen
4189 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4192 \begin_layout Plain Layout
4193 inverted\SpecialChar softhyphen
4199 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4202 \begin_layout Plain Layout
4203 suspended\SpecialChar softhyphen
4209 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4212 \begin_layout Plain Layout
4218 <cell alignment="center" valignment="top" topline="true" usebox="none">
4221 \begin_layout Plain Layout
4227 <cell alignment="center" valignment="top" topline="true" usebox="none">
4230 \begin_layout Plain Layout
4236 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4239 \begin_layout Plain Layout
4247 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4250 \begin_layout Plain Layout
4256 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4259 \begin_layout Plain Layout
4265 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4268 \begin_layout Plain Layout
4274 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4277 \begin_layout Plain Layout
4283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4286 \begin_layout Plain Layout
4292 <cell alignment="center" valignment="top" topline="true" usebox="none">
4295 \begin_layout Plain Layout
4301 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4304 \begin_layout Plain Layout
4310 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4313 \begin_layout Plain Layout
4321 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4324 \begin_layout Plain Layout
4330 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4333 \begin_layout Plain Layout
4335 \begin_inset Newline newline
4339 \begin_inset Newline newline
4347 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4350 \begin_layout Plain Layout
4356 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4359 \begin_layout Plain Layout
4365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4368 \begin_layout Plain Layout
4374 <cell alignment="center" valignment="top" topline="true" usebox="none">
4377 \begin_layout Plain Layout
4383 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4386 \begin_layout Plain Layout
4392 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4395 \begin_layout Plain Layout
4403 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4406 \begin_layout Plain Layout
4412 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4415 \begin_layout Plain Layout
4421 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4424 \begin_layout Plain Layout
4430 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4433 \begin_layout Plain Layout
4439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4442 \begin_layout Plain Layout
4448 <cell alignment="center" valignment="top" topline="true" usebox="none">
4451 \begin_layout Plain Layout
4457 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4460 \begin_layout Plain Layout
4466 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4469 \begin_layout Plain Layout
4477 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4480 \begin_layout Plain Layout
4486 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4489 \begin_layout Plain Layout
4495 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4498 \begin_layout Plain Layout
4504 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4507 \begin_layout Plain Layout
4513 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4516 \begin_layout Plain Layout
4522 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4525 \begin_layout Plain Layout
4531 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4534 \begin_layout Plain Layout
4540 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4543 \begin_layout Plain Layout
4557 \begin_layout Standard
4558 \begin_inset Note Note
4561 \begin_layout Plain Layout
4563 \begin_inset Quotes eld
4567 \begin_inset Quotes erd
4571 this would be far less complicated:
4574 \begin_layout Plain Layout
4575 \begin_inset Tabular
4576 <lyxtabular version="3" rows="6" columns="7">
4577 <features tabularvalignment="middle">
4578 <column alignment="left" valignment="top" width="0pt">
4579 <column alignment="left" valignment="top" width="0pt">
4580 <column alignment="left" valignment="top" width="0pt">
4581 <column alignment="center" valignment="top">
4582 <column alignment="center" valignment="top">
4583 <column alignment="center" valignment="top">
4584 <column alignment="center" valignment="top">
4586 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4589 \begin_layout Plain Layout
4590 Test matching pattern in file:
4595 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4598 \begin_layout Plain Layout
4604 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4607 \begin_layout Plain Layout
4613 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4616 \begin_layout Plain Layout
4622 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4625 \begin_layout Plain Layout
4631 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4634 \begin_layout Plain Layout
4640 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4643 \begin_layout Plain Layout
4651 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4654 \begin_layout Plain Layout
4660 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4663 \begin_layout Plain Layout
4669 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4672 \begin_layout Plain Layout
4678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4681 \begin_layout Plain Layout
4687 <cell alignment="center" valignment="top" topline="true" usebox="none">
4690 \begin_layout Plain Layout
4696 <cell alignment="center" valignment="top" topline="true" usebox="none">
4699 \begin_layout Plain Layout
4705 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4708 \begin_layout Plain Layout
4716 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4719 \begin_layout Plain Layout
4725 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4728 \begin_layout Plain Layout
4734 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4737 \begin_layout Plain Layout
4743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4746 \begin_layout Plain Layout
4752 <cell alignment="center" valignment="top" topline="true" usebox="none">
4755 \begin_layout Plain Layout
4761 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4764 \begin_layout Plain Layout
4770 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4773 \begin_layout Plain Layout
4781 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4784 \begin_layout Plain Layout
4790 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4793 \begin_layout Plain Layout
4799 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4802 \begin_layout Plain Layout
4808 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4811 \begin_layout Plain Layout
4817 <cell alignment="center" valignment="top" topline="true" usebox="none">
4820 \begin_layout Plain Layout
4826 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4829 \begin_layout Plain Layout
4835 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4838 \begin_layout Plain Layout
4846 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4849 \begin_layout Plain Layout
4855 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4858 \begin_layout Plain Layout
4864 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4867 \begin_layout Plain Layout
4873 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4876 \begin_layout Plain Layout
4882 <cell alignment="center" valignment="top" topline="true" usebox="none">
4885 \begin_layout Plain Layout
4891 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4894 \begin_layout Plain Layout
4900 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4903 \begin_layout Plain Layout
4911 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4914 \begin_layout Plain Layout
4920 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4923 \begin_layout Plain Layout
4929 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4932 \begin_layout Plain Layout
4938 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4941 \begin_layout Plain Layout
4947 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4950 \begin_layout Plain Layout
4956 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4959 \begin_layout Plain Layout
4965 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4968 \begin_layout Plain Layout
4987 \begin_layout Subsection
4991 \begin_layout Standard
4992 These tests check whether a .lyx file loads without any terminal messages.
4993 They correspond to the manual operations of simply opening a .lyx file on the terminal,
4994 exiting LyX once the file is loaded,
4995 and then checking whether there is any output from the terminal.
4996 These tests are useful for catching malformed .lyx files and parsing bugs.
4997 They can also be used to find a .lyx file in which an instance of something happens.
4999 compile LyX with a local patch that outputs something to the terminal when an instance is found,
5000 and then run the check_load tests to see if any fail,
5001 which would mean that the situation occurs in the LyX documentation files corresponding to the failed tests.
5002 These tests are expectedly fragile:
5003 any LyX diagnostic message,
5004 which is not necessarily an error,
5005 would cause the tests to fail.
5007 any message output by a library (e.g.
5008 Qt) would also cause failure.
5009 There are some messages that the check_load tests are instructed to ignore,
5010 which are stored in the file
5011 \begin_inset Flex Code
5014 \begin_layout Plain Layout
5015 development/autotests/filterCheckWarnings
5023 \begin_layout Standard
5025 the tests are labeled as 'load'.
5028 \begin_layout Subsection
5032 \begin_layout Standard
5033 Automated tests based on the "MonKey Testing" keytest program are enabled if the necessary dependencies are found and if the CMake flag
5034 \begin_inset Flex Code
5037 \begin_layout Plain Layout
5038 -DLYX_ENABLE_KEYTESTS=ON
5044 They are documented in the README document in
5045 \begin_inset Flex Code
5048 \begin_layout Plain Layout
5049 development/autotests
5054 subfolder of the \SpecialChar LyX
5055 source code distribution.
5058 \begin_layout Subsection
5062 \begin_layout Standard
5063 These tests combine lyx2lyx tests with check_load tests.
5064 They fail if either fails.
5067 \begin_layout Subsection
5071 \begin_layout Standard
5072 The URL tests are enabled with the
5073 \begin_inset Flex Code
5076 \begin_layout Plain Layout
5077 -DLYX_ENABLE_URLTESTS=ON
5082 CMake flag and are useful for finding broken links in our documentation files.
5083 If a URL test fails,
5084 to see which link in particular was reported as broken,
5086 \begin_inset Flex Code
5089 \begin_layout Plain Layout
5096 These tests are extremely fragile (e.g.
5097 a test can depend on your Internet connection) and a failed URL test should not be taken too seriously.
5098 URL tests are labeled as
5103 \begin_layout Subsubsection
5107 \begin_layout Standard
5108 cmake is required to run the \SpecialChar LyX
5110 running them is not implemented for autotools.
5113 \begin_layout Standard
5114 The appropriate commands are:
5117 \begin_layout Itemize
5123 \begin_inset Newline newline
5126 runs all tests with label
5131 \begin_layout Itemize
5134 ctest -R 'check_.*urls'
5137 \begin_inset Newline newline
5140 runs the tests 'check_accessible_urls'
5143 \begin_layout Standard
5144 Associated test results can be examined in ctest-log directory in files of the form 'LastFailed.*URLS.log'
5147 \begin_layout Chapter
5148 Development policies
5151 \begin_layout Standard
5152 This chapter lists some guidelines that should be followed.
5153 This list is not complete,
5154 and many guidelines are in separate chapters,
5156 \begin_inset Quotes eld
5159 When is an update of the .lyx file format number needed?
5160 \begin_inset Quotes erd
5164 \begin_inset CommandInset ref
5166 reference "sec:When-is-an"
5174 \begin_layout Section
5175 When to set a fixed milestone?
5178 \begin_layout Standard
5179 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following holds:
5182 \begin_layout Enumerate
5183 Somebody is actively working on a fix.
5186 \begin_layout Enumerate
5187 The bug is so severe that it would block the release if it is not fixed.
5190 \begin_layout Standard
5191 If a bug is important,
5192 but nobody is working on it,
5193 and it is no showstopper,
5194 use a milestone like 2.1.x or 2.2.x.
5196 do not set a milestone at all.
5199 \begin_layout Section
5200 Can we add rc entries in stable branch?
5203 \begin_layout Standard
5205 We are supposed to increase the prefs2prefs version number with such things.
5208 \begin_layout Chapter
5209 \begin_inset CommandInset label
5211 name "sec:Documentation-policies"
5215 Documentation policies
5218 \begin_layout Section
5222 \begin_layout Standard
5224 \begin_inset space ~
5227 rules in editing the docs:
5230 \begin_layout Enumerate
5231 \begin_inset CommandInset label
5233 name "enu:If-you-are"
5237 If you are not the maintainer of a doc file or a chapter/section,
5238 you MUST use change tracking so that the maintainer could review your changes
5241 \begin_layout Enumerate
5242 Respect the formatting of the document.
5243 The different files use different formatting styles.
5244 That is OK and has historic reasons nobody fully knows ;-).
5245 But it is important to be consistent within one file.
5248 \begin_layout Enumerate
5249 All changes you make to a file in one language MUST also go the file in the other actively maintained languages.
5250 Normally the maintainer does this for you,
5251 if you are the maintainer,
5252 you must do this by copying or changing the changed or added text to the other files so that the translators sees the blue underlined text and know what they have to translate and what was changed.
5255 \begin_layout Enumerate
5256 You MUST assure that the document is compilable as
5257 \begin_inset Quotes eld
5261 \begin_inset Quotes erd
5264 or the document's default output format after your changes.
5267 \begin_layout Enumerate
5270 updates info etc.) go at first into the current Git branch because the user should benefit from all fixes with every minor release.
5271 Feel free to commit directly to branch as long as you follow rule
5272 \begin_inset space ~
5276 \begin_inset CommandInset ref
5278 reference "enu:If-you-are"
5284 You can immediately commit to master as well.
5287 \begin_layout Enumerate
5288 \begin_inset CommandInset label
5290 name "enu:The-fileformat-of"
5294 The fileformat of a file must not be changed unless you document a new feature in LyX that requires a new fileformat.
5295 The reason for this rule is to keep it easy for the doc maintainers to port/backport changes to from master/branch.
5298 \begin_layout Standard
5299 The main documentation consists of these files:
5302 \begin_layout Description
5303 Welcome.lyx It is the first file you see after an installation.
5304 We assume that a new user sees this.
5305 It is therefore designed to be as simple as possible.
5306 Therefore please don't add any new formatting,
5310 \begin_layout Description
5311 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5313 It therefore uses a limited set of formatting.
5314 For example a standard document class.
5315 Since new users will first learn about the formatting possibilities of \SpecialChar LyX
5316 please keep this file that simple.
5319 \begin_layout Description
5320 Tutorial.lyx Our tutorial.
5321 It must be always up to date.
5322 Normally there is nothing to add since we don't want to overwhelm new users with too much details.
5323 They will learn these details while using \SpecialChar LyX
5324 and we have special manuals.
5327 \begin_layout Description
5328 UserGuide.lyx Our main user guide.
5329 It covers a mixture of basic and detailed information.
5330 Some information is also in the Math and EmbeddedObjects manual so that the UserGuide refers to these files.
5333 \begin_layout Description
5334 EmbeddedObjects.lyx A special manual to explain things like tables floats boxes etc.
5338 \begin_layout Description
5339 Math.lyx A special manual to explain everything regarding math in all detail.
5342 \begin_layout Description
5343 Additional.lyx This manual covers information that would be too much detail for the UserGuide or would make the UserGuide uncompilable or only compilable when installing a lot of special \SpecialChar LaTeX
5345 What should be in the UserGuide or better in Additional is a matter of taste.
5346 It is up to you to decide that.
5347 Additional.lyx is not completely up to date (only chapter
5348 \begin_inset space ~
5352 It certainly needs a rewrite and update.
5353 For example many info in chapter
5354 \begin_inset space ~
5357 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects manual.
5360 \begin_layout Description
5361 Customization.lyx This manual covers information how to customize \SpecialChar LyX
5362 for certain output formats,
5365 It is currently completely out of date and needs a major rewrite and update.
5366 If you do this please assure that your information are given for all OSes and \SpecialChar LaTeX
5367 distributions (meaning be as objective as possible).
5370 \begin_layout Chapter
5374 \begin_layout Standard
5375 The aim of this chapter is to serve as a guide for the developers,
5376 to aid us to get clean and uniform code.
5378 We really like to have new developers joining the \SpecialChar LyX
5381 we have had problems in the past with developers leaving the project and their contributed code in a far from perfect state.
5382 Most of this happened before we really became aware of these issues,
5384 we don't want it to happen again.
5385 So we have put together some guidelines and rules for the developers.
5388 \begin_layout Section
5392 \begin_layout Standard
5393 These guidelines should save us a lot of work while cleaning up the code and help us to have quality code.
5395 has been haunted by problems coming from unfinished projects by people who have left the team.
5396 Those problems will hopefully disappear if the code is easy to hand over to somebody else.
5398 if you want to contribute to the main source,
5399 we expect at least that you:
5402 \begin_layout Itemize
5403 The most important rule first:
5404 KISS (Keep It Simple Stupid),
5405 always use a simple implementation in favor of a more complicated one.
5406 This eases maintenance a lot.
5409 \begin_layout Itemize
5410 Write good C++ code:
5413 and taking advantage of the OO model.
5414 Follow the formatting guidelines.
5416 \begin_inset space ~
5420 \begin_inset CommandInset ref
5422 reference "sec:Formatting"
5433 \begin_layout Itemize
5435 you can use features of C++11.
5436 Accordingly you have to use C++11 standard conforming compiler,
5438 \begin_inset space \thinspace{}
5442 not too dated version of GCC or Clang.
5445 \begin_layout Itemize
5446 Adapt the code to the structures already existing in \SpecialChar LyX
5448 or in the case that you have better ideas,
5449 discuss them on the developer's list before writing the code.
5452 \begin_layout Itemize
5453 Take advantage of the C++ standard library.
5454 Especially don't use custom containers when a standard container is usable;
5455 learn to use the algorithms and functors in the standard library.
5458 \begin_layout Itemize
5459 Be aware of exceptions and write exception safe code.
5461 \begin_inset space ~
5465 \begin_inset CommandInset ref
5467 reference "sec:Exceptions"
5478 \begin_layout Itemize
5479 Document all variables,
5483 We are using the source documentation program doxygen,
5484 a program that handles javadoc syntax,
5485 to document sources.
5486 You can download doxygen from:
5488 \begin_inset Flex URL
5491 \begin_layout Plain Layout
5493 http://www.stack.nl/~dimitri/doxygen/
5501 \begin_layout Itemize
5502 We have certain code constructs that we try to follow.
5504 \begin_inset space ~
5508 \begin_inset CommandInset ref
5510 reference "sec:Code-constructs"
5521 \begin_layout Section
5525 \begin_layout Standard
5526 It is implicitly understood that all patches contributed to The \SpecialChar LyX
5527 Project is under the Gnu General Public License,
5529 If you have a problem with that,
5530 don't contribute code.
5531 Also please don't just pop up out of the blue with a huge patch (or small) that changes something substantial in \SpecialChar LyX
5533 Always discuss your ideas with the developers on the developer's mailing list.
5534 When you create the patch,
5536 \begin_inset Quotes eld
5544 \begin_inset Quotes erd
5547 since we find that a lot easier to read than the other diff formats.
5548 Also please do not send patches that implements or fixes several different things;
5549 several patches is a much better option.
5550 We also require you to provide a commit message entry with every patch,
5551 this describes in detail what the patch is doing.
5555 \begin_layout Section
5557 \begin_inset CommandInset label
5559 name "sec:Code-constructs"
5566 \begin_layout Standard
5567 We have several guidelines on code constructs,
5568 some of these exist to make the code faster,
5569 others to make the code clearer.
5570 Yet others exist to allow us to take advantage of the strong type checking in C++.
5573 \begin_layout Itemize
5574 Declaration of variables should wait as long as possible.
5577 \begin_inset Quotes eld
5580 Don't declare it until you need it.
5581 \begin_inset Quotes erd
5584 In C++ there are a lot of user defined types,
5585 and these can very often be expensive to initialize.
5586 This rule connects to the next rule too.
5590 \begin_layout Itemize
5591 Declare the variable as
5592 \begin_inset Flex Code
5595 \begin_layout Plain Layout
5601 if you don't need to change it.
5602 This applies to POD types like
5603 \begin_inset Flex Code
5606 \begin_layout Plain Layout
5616 \begin_layout Itemize
5617 Make the scope of a variable as small as possible.
5620 \begin_layout Itemize
5621 Make good use of namespaces.
5622 Prefer anonymous namespaces to declaring
5623 \begin_inset Flex Code
5626 \begin_layout Plain Layout
5635 \begin_layout Itemize
5636 Prefer preincrement to postincrement whenever possible.
5639 \begin_layout Itemize
5640 Preincrement has potential of being faster than postincrement.
5641 Just think about the obvious implementations of pre/post-increment.
5642 This rule applies to decrement too.
5645 \begin_layout Itemize
5647 \begin_inset Separator latexpar
5654 \begin_layout Standard
5655 \begin_inset listings
5656 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5660 \begin_layout Plain Layout
5665 \begin_layout Plain Layout
5675 \begin_layout Standard
5679 \begin_layout Standard
5680 \begin_inset listings
5681 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5685 \begin_layout Plain Layout
5691 \begin_layout Plain Layout
5703 \begin_layout Itemize
5704 Try to minimize evaluation of the same code over and over.
5705 This is aimed especially at loops.
5707 \begin_inset Newline newline
5711 \begin_inset Separator latexpar
5718 \begin_layout Standard
5719 \begin_inset listings
5720 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5724 \begin_layout Plain Layout
5726 Container::iterator end = large.end();
5729 \begin_layout Plain Layout
5731 for (Container::iterator it = large.begin();
5736 \begin_layout Plain Layout
5741 \begin_layout Plain Layout
5751 \begin_layout Standard
5755 \begin_layout Standard
5756 \begin_inset listings
5757 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5761 \begin_layout Plain Layout
5763 for (auto const & it :
5767 \begin_layout Plain Layout
5772 \begin_layout Plain Layout
5782 \begin_layout Standard
5786 \begin_layout Standard
5787 \begin_inset listings
5788 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5792 \begin_layout Plain Layout
5794 for (Container::iterator it = large.begin();
5799 \begin_layout Plain Layout
5804 \begin_layout Plain Layout
5815 \begin_layout Itemize
5816 For functions and methods that return a non-POD type
5820 \begin_layout Plain Layout
5827 \begin_inset Flex Code
5830 \begin_layout Plain Layout
5838 \begin_inset Flex Code
5841 \begin_layout Plain Layout
5848 This gives better type checking,
5849 and will give a compiler warning when temporaries are used wrongly.
5850 \begin_inset Separator latexpar
5857 \begin_layout Standard
5861 \begin_layout Standard
5862 \begin_inset listings
5863 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5867 \begin_layout Plain Layout
5877 \begin_layout Standard
5881 \begin_layout Standard
5882 \begin_inset listings
5883 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5887 \begin_layout Plain Layout
5898 \begin_layout Itemize
5899 Avoid using the default cases in switch statements unless you have too.
5900 Use the correct type for the switch expression and let the compiler ensure that all cases are exhausted.
5903 \begin_layout Itemize
5904 \begin_inset listings
5905 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
5909 \begin_layout Plain Layout
5914 \begin_layout Plain Layout
5919 \begin_layout Plain Layout
5924 \begin_layout Plain Layout
5929 \begin_layout Plain Layout
5933 \begin_layout Plain Layout
5938 \begin_layout Plain Layout
5942 \begin_layout Plain Layout
5947 \begin_layout Plain Layout
5952 \begin_layout Plain Layout
5957 \begin_layout Plain Layout
5962 \begin_layout Plain Layout
5967 \begin_layout Plain Layout
5972 \begin_layout Plain Layout
5977 \begin_layout Plain Layout
5980 // not needed and would shadow a wrong use of Foo
5983 \begin_layout Plain Layout
5988 \begin_layout Plain Layout
5994 \begin_layout Plain Layout
6004 \begin_layout Itemize
6005 Use default initialization such as
6006 \begin_inset listings
6010 \begin_layout Plain Layout
6015 \begin_layout Plain Layout
6017 Class * ptr = nullptr;
6022 rather than brace initialization:
6023 \begin_inset listings
6027 \begin_layout Plain Layout
6032 \begin_layout Plain Layout
6040 Use brace initialization only for more complex data structures.
6044 \begin_layout Section
6046 \begin_inset CommandInset label
6048 name "sec:Exceptions"
6055 \begin_layout Standard
6056 Be aware of the presence of exceptions.
6057 One important thing to realize is that you often do not have to use throw,
6058 try or catch to be exception safe.
6059 Let's look at the different types of exceptions safety (these are taken from Herb Sutter's book
6060 \begin_inset CommandInset citation
6070 \begin_layout Enumerate
6072 Even in the presence of exceptions thrown by T or other exceptions,
6073 Stack objects don't leak resources.
6074 Note that this also implies that the container will be destructible and usable even if an exception is thrown while performing some container operation.
6076 if an exception is thrown,
6077 the container will be in a consistent,
6078 but not necessarily predictable,
6080 Containers that support the basic guarantee can work safely in some settings.
6084 \begin_layout Enumerate
6086 If an operation terminates because of an exception,
6087 program state will remain unchanged.
6088 This always implies commit-or-rollback semantics,
6089 including that no references or iterators into the container be invalidated if an operation fails.
6091 if a Stack client calls Top and then attempts a Push that fails because of an exception,
6092 then the state of the Stack object must be unchanged and the reference returned from the prior call to Top must still be valid.
6093 For more information on these guarantees,
6094 see Dave Abrahams's documentation of the SGI exception-safe standard library adaption at:
6096 \begin_inset Flex URL
6099 \begin_layout Plain Layout
6101 http://www.stlport.org/doc/exception_safety.html
6106 Probably the most interesting point here is that when you implement the basic guarantee,
6107 the strong guarantee often comes for free.
6109 in our Stack implementation,
6110 almost everything we did was needed to satisfy just the basic guarantee – and what's presented above very nearly satisfies the strong guarantee,
6111 with little or no extra work.
6113 considering all the trouble we went to.
6114 In addition to these two guarantees,
6115 there is one more guarantee that certain functions must provide in order to make overall exception safety possible:
6118 \begin_layout Enumerate
6120 The function will not emit an exception under any circumstances.
6121 Overall exception safety isn't possible unless certain functions are guaranteed not to throw.
6123 we've seen that this is true for destructors;
6124 later in this miniseries,
6125 we'll see that it's also needed in certain helper functions,
6133 \begin_layout Standard
6134 For all cases where we might be able to write exception safe functions without using try,
6135 throw or catch we should do so.
6136 In particular we should look over all destructors to ensure that they are as exception safe as possible.
6139 \begin_layout Section
6141 \begin_inset CommandInset label
6143 name "sec:Formatting"
6150 \begin_layout Itemize
6151 Only one declaration on each line.
6152 \begin_inset Separator latexpar
6159 \begin_layout Standard
6163 \begin_layout Standard
6164 \begin_inset listings
6165 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6169 \begin_layout Plain Layout
6174 \begin_layout Plain Layout
6184 \begin_layout Standard
6188 \begin_layout Standard
6189 \begin_inset listings
6190 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6194 \begin_layout Plain Layout
6206 \begin_layout Standard
6207 This is especially important when initialization is done at the same time:
6210 \begin_layout Standard
6214 \begin_layout Standard
6215 \begin_inset listings
6216 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6220 \begin_layout Plain Layout
6225 \begin_layout Plain Layout
6227 string b = "Gullik";
6235 \begin_layout Standard
6239 \begin_layout Standard
6240 \begin_inset listings
6241 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6245 \begin_layout Plain Layout
6257 \begin_layout Standard
6259 \begin_inset Flex Code
6262 \begin_layout Plain Layout
6268 is formally calling a copy constructor on a temporary constructed from a string literal and therefore has the potential of being more expensive then direct construction by
6269 \begin_inset Flex Code
6272 \begin_layout Plain Layout
6279 However the compiler is allowed to elide the copy (even if it had side effects),
6280 and modern compilers typically do so.
6281 Given these equal costs,
6283 code favours the '=' idiom as it is in line with the traditional C-style initialization,
6288 cannot be mistaken as function declaration,
6293 reduces the level of nested parentheses in more initializations.]
6297 \begin_layout Itemize
6298 Pointers and references:
6299 \begin_inset Separator latexpar
6306 \begin_layout Standard
6310 \begin_layout Standard
6311 \begin_inset listings
6312 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6316 \begin_layout Plain Layout
6321 \begin_layout Plain Layout
6331 \begin_layout Standard
6335 \begin_layout Standard
6336 \begin_inset listings
6337 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6341 \begin_layout Plain Layout
6347 \begin_layout Plain Layout
6358 \begin_layout Standard
6359 Some time ago we had a huge discussion on this subject and after convincing argumentation from Asger this is what we decided.
6360 Also note that we will have:
6363 \begin_layout Standard
6364 \begin_inset listings
6365 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6369 \begin_layout Plain Layout
6379 \begin_layout Standard
6383 \begin_layout Standard
6384 \begin_inset listings
6385 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6389 \begin_layout Plain Layout
6401 \begin_layout Itemize
6402 Operator names and parentheses
6403 \begin_inset Separator latexpar
6410 \begin_layout Standard
6411 \begin_inset listings
6412 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6416 \begin_layout Plain Layout
6426 \begin_layout Standard
6430 \begin_layout Standard
6431 \begin_inset listings
6432 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6436 \begin_layout Plain Layout
6438 operator == (type) // not used in LyX
6446 \begin_layout Standard
6447 The == is part of the function name,
6448 separating it makes the declaration look like an expression.
6452 \begin_layout Itemize
6453 Function names and parentheses
6454 \begin_inset Separator latexpar
6461 \begin_layout Standard
6462 \begin_inset listings
6463 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6467 \begin_layout Plain Layout
6477 \begin_layout Standard
6481 \begin_layout Standard
6482 \begin_inset listings
6483 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6487 \begin_layout Plain Layout
6489 void mangle () // not used in LyX
6498 \begin_layout Itemize
6500 \begin_inset Separator latexpar
6507 \begin_layout Standard
6508 \begin_inset listings
6509 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6513 \begin_layout Plain Layout
6518 \begin_layout Plain Layout
6523 \begin_layout Plain Layout
6528 \begin_layout Plain Layout
6533 \begin_layout Plain Layout
6543 \begin_layout Standard
6547 \begin_layout Standard
6548 \begin_inset listings
6549 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6553 \begin_layout Plain Layout
6558 \begin_layout Plain Layout
6563 \begin_layout Plain Layout
6568 \begin_layout Plain Layout
6573 \begin_layout Plain Layout
6583 \begin_layout Standard
6584 \begin_inset listings
6585 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6589 \begin_layout Plain Layout
6602 \begin_layout Standard
6606 \begin_layout Standard
6607 \begin_inset listings
6608 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6612 \begin_layout Plain Layout
6617 \begin_layout Plain Layout
6622 \begin_layout Plain Layout
6627 \begin_layout Plain Layout
6632 \begin_layout Plain Layout
6643 \begin_layout Itemize
6645 \begin_inset Separator latexpar
6652 \begin_layout Standard
6653 Use nullptr (C++11):
6656 \begin_layout Standard
6657 \begin_inset listings
6658 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6662 \begin_layout Plain Layout
6672 \begin_layout Standard
6676 \begin_layout Standard
6677 \begin_inset listings
6678 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6682 \begin_layout Plain Layout
6693 \begin_layout Standard
6697 \begin_layout Standard
6698 \begin_inset listings
6699 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6703 \begin_layout Plain Layout
6716 \begin_layout Standard
6720 \begin_layout Standard
6721 \begin_inset listings
6722 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6726 \begin_layout Plain Layout
6728 void * p = 42 - 7 * 6;
6737 \begin_layout Standard
6740 imported third party code as well as code interfacing the
6741 \begin_inset Quotes eld
6745 \begin_inset Quotes erd
6749 \begin_inset Flex Code
6752 \begin_layout Plain Layout
6762 \begin_layout Itemize
6763 Naming rules for classes
6764 \begin_inset Separator latexpar
6771 \begin_layout Itemize
6772 Use descriptive but simple and short names.
6776 \begin_layout Itemize
6777 Class names are usually capitalized,
6778 and function names lowercased.
6781 \begin_layout Itemize
6782 Enums are named like Classes,
6783 values are usually in lower-case.
6786 \begin_layout Itemize
6787 Public API functions are camel-case (
6788 \begin_inset Flex Code
6791 \begin_layout Plain Layout
6792 void setAFlagToAValue(bool)
6800 \begin_layout Itemize
6801 Member variables are underscored (
6802 \begin_inset Flex Code
6805 \begin_layout Plain Layout
6806 enable_this_feature_flag_
6812 \begin_inset Quotes eld
6816 \begin_inset Quotes erd
6822 \begin_layout Itemize
6823 Private/protected functions are also camel-case.
6826 \begin_layout Itemize
6827 New types are capitalized,
6828 so this goes for typedefs,
6834 \begin_layout Itemize
6836 \begin_inset Separator latexpar
6843 \begin_layout Itemize
6844 Adapt the formatting of your code to the one used in the other parts of \SpecialChar LyX
6846 In case there is different formatting for the same construct,
6847 use the one used more often.
6851 \begin_layout Itemize
6852 Use existing structures
6853 \begin_inset Separator latexpar
6860 \begin_layout Itemize
6861 \begin_inset CommandInset label
6863 name "Use-string-wherever"
6868 \begin_inset Flex Code
6871 \begin_layout Plain Layout
6878 Unicode strings should prefer using
6879 \begin_inset Flex Code
6882 \begin_layout Plain Layout
6888 instead of UTF-8 encoded
6889 \begin_inset Flex Code
6892 \begin_layout Plain Layout
6901 \begin_layout Itemize
6902 Check out the filename and path tools in
6903 \begin_inset Flex Code
6906 \begin_layout Plain Layout
6915 \begin_layout Itemize
6916 Check out the string tools in
6917 \begin_inset Flex Code
6920 \begin_layout Plain Layout
6929 \begin_layout Itemize
6930 Use the \SpecialChar LyX
6931 Err class to report errors and messages using the lyxerr instantiation.
6932 [add description of other existing structures]
6936 \begin_layout Itemize
6938 \begin_inset Separator latexpar
6945 \begin_layout Itemize
6946 Use this order for the access sections of your class:
6950 The public section is interesting for every user of the class.
6951 The private section is only of interest for the implementors of the class (you).
6952 [Obviously not true since this is for developers,
6953 and we do not want one developer only to be able to read and understand the implementation of class internals.
6957 \begin_layout Itemize
6958 Avoid declaring global objects in the declaration file of the class.
6959 If the same variable is used for all objects,
6960 use a static member.
6963 \begin_layout Itemize
6964 Avoid global or static variables.
6968 \begin_layout Itemize
6970 \begin_inset Separator latexpar
6977 \begin_layout Standard
6978 If you create a new file,
6979 the top of the file should look something like this :
6982 \begin_layout Standard
6983 \begin_inset listings
6984 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
6988 \begin_layout Plain Layout
6993 \begin_layout Plain Layout
7000 \begin_layout Plain Layout
7002 * This file is part of LyX,
7003 the document processor.
7006 \begin_layout Plain Layout
7008 * Licence details can be found in the file COPYING.
7011 \begin_layout Plain Layout
7016 \begin_layout Plain Layout
7023 \begin_layout Plain Layout
7028 \begin_layout Plain Layout
7030 * Full author contact details are available
7033 \begin_layout Plain Layout
7038 \begin_layout Plain Layout
7049 \begin_layout Itemize
7051 \begin_inset Separator latexpar
7058 \begin_layout Itemize
7059 The documentation is generated from the header files.
7062 \begin_layout Itemize
7063 You document for the other developers,
7067 \begin_layout Itemize
7068 You should document what the function does,
7069 not the implementation.
7070 \begin_inset Separator latexpar
7077 \begin_layout Itemize
7078 in the .cpp files you document the implementation.
7082 \begin_layout Itemize
7083 Single line description (
7084 \begin_inset Flex Code
7087 \begin_layout Plain Layout
7094 multiple lines description (
7095 \begin_inset Flex Code
7098 \begin_layout Plain Layout
7106 see the doxygen webpage referenced above.
7110 \begin_layout Section
7111 Naming rules for \SpecialChar LyX
7112 User Functions (LFUNs)
7115 \begin_layout Standard
7116 Here is the set of rules to apply when a new command name is introduced:
7119 \begin_layout Enumerate
7120 Use the object.event order.
7122 use `word-forward' instead of `forward-word'.
7125 \begin_layout Enumerate
7126 Don't introduce an alias for an already named object.
7130 \begin_layout Enumerate
7131 Forward movement or focus is called `forward' (not `right').
7134 \begin_layout Enumerate
7135 Backward movement or focus is called `backward' (not `left').
7138 \begin_layout Enumerate
7139 Upward movement of focus is called `up'.
7142 \begin_layout Enumerate
7143 Downward movement is called `down'.
7146 \begin_layout Enumerate
7147 The begin of an object is called `begin' (not `start').
7150 \begin_layout Enumerate
7151 The end of an object is called `end'.
7154 \begin_layout Section
7155 How to create class interfaces
7158 \begin_layout Standard
7159 (a.k.a How Non-Member Functions Improve Encapsulation)
7162 \begin_layout Standard
7163 I recently read an article by Scott Meyers,
7164 where he makes a strong case on how non-member functions makes classes more encapsulated,
7166 Just skipping to the core of this provides us with the following algorithm for deciding what kind of function to add to a class interface:
7169 \begin_layout Itemize
7170 We need to add a function f to the class C's API.
7171 \begin_inset Separator latexpar
7178 \begin_layout Standard
7179 \begin_inset listings
7180 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7184 \begin_layout Plain Layout
7186 if (f needs to be virtual)
7189 \begin_layout Plain Layout
7191 make f a member function of C;
7194 \begin_layout Plain Layout
7196 else if (f is operator>> or operator<<) {
7199 \begin_layout Plain Layout
7201 make f a non-member function;
7204 \begin_layout Plain Layout
7206 if (f needs access to non-public members of C)
7209 \begin_layout Plain Layout
7211 make f a friend of C;
7214 \begin_layout Plain Layout
7216 } else if (f needs type conversions on its left-most argument) {
7219 \begin_layout Plain Layout
7221 make f a non-member function;
7224 \begin_layout Plain Layout
7226 if (f needs access to non-public members of C)
7229 \begin_layout Plain Layout
7231 make f a friend of C;
7234 \begin_layout Plain Layout
7236 } else if (f can be implemented via C's public interface)
7239 \begin_layout Plain Layout
7241 make f a non-member function;
7244 \begin_layout Plain Layout
7249 \begin_layout Plain Layout
7251 make f a member function of C;
7260 \begin_layout Chapter
7261 Coding recommendations
7264 \begin_layout Standard
7265 These are some rules for effective C++ programming.
7266 These are taken from Scott Meyers
7267 \begin_inset CommandInset citation
7275 and are presented in their short form.
7276 These are not all the rules Meyers presents,
7277 only the most important of them.
7279 does not yet follow these rules,
7280 but they should be the goal.
7283 \begin_layout Itemize
7297 \begin_layout Itemize
7298 use the same form in corresponding calls to new and delete,
7301 \begin_inset Flex Code
7304 \begin_layout Plain Layout
7311 \begin_inset Flex Code
7314 \begin_layout Plain Layout
7320 was used to create the object and write
7321 \begin_inset Flex Code
7324 \begin_layout Plain Layout
7331 \begin_inset Flex Code
7334 \begin_layout Plain Layout
7340 Notice strings should be
7341 \begin_inset Flex Code
7344 \begin_layout Plain Layout
7351 \begin_inset Flex Code
7354 \begin_layout Plain Layout
7361 (this contradicts to
7362 \begin_inset CommandInset ref
7364 reference "Use-string-wherever"
7372 \begin_layout Itemize
7373 define a default constructor,
7374 copy constructor and an assignment operator for all classes with dynamically allocated memory that are not made noncopyable
7377 \begin_layout Itemize
7378 do not define default constructor,
7379 copy constructor and an assignment operator if the compiler generated one would do the same
7382 \begin_layout Itemize
7383 make destructors virtual in base classes and only there
7386 \begin_layout Itemize
7387 assign to all data members in operator=()
7390 \begin_layout Itemize
7391 strive for class interfaces that are complete and minimal
7394 \begin_layout Itemize
7395 differentiate among member functions,
7396 global functions and friend functions
7399 \begin_layout Itemize
7400 avoid data members in the public interface
7403 \begin_layout Itemize
7404 use const whenever possible
7407 \begin_layout Itemize
7408 pass and return objects by reference instead of by value
7411 \begin_layout Itemize
7412 choose carefully between function overloading and parameter defaulting
7415 \begin_layout Itemize
7416 never return a reference to a local object or a dereferenced pointer initialized by new within the function
7419 \begin_layout Itemize
7420 use enums for integral constants
7423 \begin_layout Itemize
7424 minimize compilation dependencies between files
7427 \begin_layout Itemize
7428 pay attention to compiler warnings
7431 \begin_layout Itemize
7432 differentiate between inheritance of interface and inheritance of implementation
7435 \begin_layout Itemize
7436 differentiate between inheritance and templates
7439 \begin_layout Itemize
7440 ensure that global objects are initialized before they are used
7443 \begin_layout Itemize
7445 \begin_inset Flex Code
7448 \begin_layout Plain Layout
7455 \begin_inset Flex Code
7458 \begin_layout Plain Layout
7464 that span more than a line
7467 \begin_layout Chapter
7472 \begin_layout Itemize
7475 \begin_inset Separator latexpar
7482 \begin_layout Itemize
7483 when switching on enums,
7484 refrain from using "default:" if possible
7488 \begin_layout Itemize
7491 \begin_inset Separator latexpar
7498 \begin_layout Itemize
7499 try to implement your class in a way that the automatically generated copy constructor and copy assignment work out-of-the box
7502 \begin_layout Itemize
7503 I don't have problems with using boost in the implementation _if and only if_ it provides actual benefits over less intrusive alternatives.
7504 I do have a problem with needlessly sprinkling 'boost::' over interfaces,
7505 especially if it does not add any value.
7506 \begin_inset Separator latexpar
7513 \begin_layout Standard
7514 Given that there seems to be an unconditional "typedef unsigned int quint32;" in qglobal.h I don't think there's any platform supported by current \SpecialChar LyX
7515 that could not use 'unsigned int' (and an static assert in some implementation file for the unlikely case some ILP64 zombie raises its ugly head again.
7516 And if that happens,
7517 using <cstdint> would still be a better choice...)
7520 \begin_layout Standard
7521 The idea is to create something that's not compilable as soon as the condition is violated.
7522 There are lots of possibilities to achieve this,
7523 some examples follow:
7526 \begin_layout Standard
7527 In C++11 there's a "built-in":
7530 \begin_layout Standard
7531 \begin_inset listings
7532 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7536 \begin_layout Plain Layout
7538 static_assert(sizeof(int) == 4,
7547 \begin_layout Standard
7548 until then on namespace scope:
7552 \begin_layout Standard
7553 \begin_inset listings
7554 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7558 \begin_layout Plain Layout
7560 #include <boost/static_assert.hpp>
7563 \begin_layout Plain Layout
7565 BOOST_STATIC_ASSERT(sizeof(int) == 4)
7573 \begin_layout Standard
7577 \begin_layout Standard
7578 \begin_inset listings
7579 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7583 \begin_layout Plain Layout
7585 template<bool Condition>
7588 \begin_layout Plain Layout
7590 struct static_assert_helper;
7593 \begin_layout Plain Layout
7598 \begin_layout Plain Layout
7600 struct static_assert_helper<true> {};
7604 \begin_layout Plain Layout
7609 \begin_layout Plain Layout
7611 dummy = sizeof(static_assert_helper<sizeof(int) == 4>)
7614 \begin_layout Plain Layout
7624 \begin_layout Standard
7625 or somewhat brutish without templates,
7629 \begin_layout Standard
7630 \begin_inset listings
7631 lstparams "basicstyle={\ttfamily},showstringspaces=false,tabsize=4"
7635 \begin_layout Plain Layout
7637 const int d = sizeof(int) - 4;
7640 \begin_layout Plain Layout
7645 \begin_layout Plain Layout
7651 \begin_layout Plain Layout
7657 \begin_layout Plain Layout
7663 \begin_layout Plain Layout
7673 \begin_layout Standard
7674 Any of them in a .cpp file will break compilation as soon as
7675 \begin_inset Flex Code
7678 \begin_layout Plain Layout
7685 Personally I prefer something like the third version (or the first,
7686 if using C++11 is allowed).
7691 \begin_layout Itemize
7694 \begin_inset Separator latexpar
7701 \begin_layout Itemize
7703 \begin_inset Flex URL
7706 \begin_layout Plain Layout
7708 http://www.lyx.org/trac/changeset/35855
7714 \begin_inset Separator latexpar
7721 \begin_layout Standard
7722 A dynamic_cast is necessary when:
7725 \begin_layout Itemize
7726 the object to be casted is from an external library because we can't add Qxxx::asXxxx() to Qt e.g.:
7727 \begin_inset Separator latexpar
7734 \begin_layout Itemize
7735 QAbstractListModel to GuiIdListModel,
7738 \begin_layout Itemize
7739 QValidator to PathValidator,
7742 \begin_layout Itemize
7743 QWidget to TabWorkArea,
7746 \begin_layout Itemize
7747 QWidget to GuiWorkArea;
7751 \begin_layout Itemize
7752 the object is to be casted from an interface to the implementing class,
7753 because the Interface does not know by whom it is implemented:
7754 \begin_inset Separator latexpar
7761 \begin_layout Itemize
7762 ProgressInterface to GuiProgress,
7765 \begin_layout Itemize
7766 Application to GuiApplication.
7770 \begin_layout Standard
7771 A dynamic_cast can be replaced by:
7774 \begin_layout Itemize
7775 already existing as***Inset() functions,
7777 \begin_inset Separator latexpar
7784 \begin_layout Itemize
7788 \begin_layout Itemize
7789 asInsetMath()->asMacro(),
7792 \begin_layout Itemize
7797 \begin_layout Itemize
7798 A static_cast when we are sure this can't go wrong,
7800 \begin_inset Separator latexpar
7807 \begin_layout Itemize
7808 we are sure that CellData::inset->clone() is an InsetTableCell,
7811 \begin_layout Itemize
7812 in cases where we explicitly check it->lyxCode().
7818 \begin_layout Bibliography
7819 \begin_inset CommandInset bibitem
7820 LatexCommand bibitem
7829 50 Specific Ways to Improve Your Programs and Design.
7834 \begin_layout Bibliography
7835 \begin_inset CommandInset bibitem
7836 LatexCommand bibitem
7845 47 engineering puzzles,
7846 programming problems,
7851 \begin_layout Bibliography
7852 \begin_inset CommandInset bibitem
7853 LatexCommand bibitem
7861 C/C++ User's Journal (Vol.18,