1 #LyX 2.2 created this file. For more info see http://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 false
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
26 \font_sf_scale 100 100
27 \font_tt_scale 100 100
29 \default_output_format pdf2
31 \bibtex_command default
32 \index_command default
36 \pdf_title "LyX's Development manual"
37 \pdf_author "LyX Team"
38 \pdf_subject "LyX's development documentation"
39 \pdf_keywords "LyX, Documentation, Development"
41 \pdf_bookmarksnumbered true
42 \pdf_bookmarksopen true
43 \pdf_bookmarksopenlevel 1
48 \pdf_pdfusetitle false
49 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
52 \use_package amsmath 1
53 \use_package amssymb 1
56 \use_package mathdots 1
57 \use_package mathtools 0
59 \use_package stackrel 0
60 \use_package stmaryrd 0
61 \use_package undertilde 0
63 \cite_engine_type default
67 \paperorientation portrait
71 \notefontcolor #0000ff
78 \paragraph_separation indent
79 \paragraph_indentation default
80 \quotes_language english
83 \paperpagestyle headings
84 \tracking_changes false
94 Developing \SpecialChar LyX
98 \begin_layout Subtitle
103 by the \SpecialChar LyX
108 \begin_layout Plain Layout
110 If you have comments or error corrections, please send them to the \SpecialChar LyX
113 \begin_inset Flex Code
116 \begin_layout Plain Layout
118 <lyx-docs@lists.lyx.org>
131 \begin_layout Standard
132 \begin_inset CommandInset toc
133 LatexCommand tableofcontents
140 \begin_layout Section
144 \begin_layout Standard
145 This manual documents some aspects of \SpecialChar LyX
147 It is currently rather incomplete, but will hopefully be extended in the
149 Meanwhile, additional information can be found in the
150 \begin_inset Flex Code
153 \begin_layout Plain Layout
159 subfolder of the \SpecialChar LyX
160 source code distribution.
161 This document is not translated, since the development language of \SpecialChar LyX
164 If you just want to use \SpecialChar LyX
165 , then you don't need to read this manual.
166 However, if you want to learn more about how \SpecialChar LyX
167 is developed, or even want
168 to participate in \SpecialChar LyX
169 development, you may find some interesting information
173 \begin_layout Section
177 \begin_layout Standard
179 uses several custom file formats for configuration files and documents.
180 This chapter contains some background concerning these file formats.
181 Several file formats are also described in detail in the regular user documenta
185 \begin_layout Subsection
189 \begin_layout Subsection
190 When is an update of the .lyx file format number needed?
191 \begin_inset CommandInset label
193 name "sec:When-is-an"
200 \begin_layout Standard
201 When you are working on a new feature you may ask yourself whether it needs
202 an update of the .lyx file format number.
203 Whether an update is needed or not is not always obvious.
206 \begin_layout Description
219 \begin_layout Standard
220 Whenever there is the danger that a previous version of LyX cannot open
221 a file using the new feature, a file format update is needed.
224 \begin_layout Standard
225 The file format change allows lyx2lyx rules to implement backwards compatibility.
229 \begin_layout Standard
230 Below you can find a list of reasons for file format updates with explanations:
233 \begin_layout Description
242 setting Whenever you introduce a new setting that is stored in the document
243 header, a file format update is needed.
246 \begin_layout Description
255 setting If a certain setting becomes obsolete and gets removed, a file format
259 \begin_layout Description
285 \begin_inset space \thinspace{}
292 \begin_layout Description
293 \paragraph_spacing single
306 package The reason for this is that there is no true ERT inset for math
307 formulas: Each command is parsed, and if a user happens to define a local
308 command with the same name as a command that triggers an automatic load
309 of a package, they need to be able to switch off the automatic loading
311 This switch is stored by the
312 \begin_inset Flex Code
315 \begin_layout Plain Layout
324 \begin_layout Description
329 language that is stored in
330 \begin_inset Flex Code
333 \begin_layout Plain Layout
346 \begin_layout Plain Layout
347 TODO: Discuss if this is really required or whether new languages can be
348 treated similar to new layouts (cf.
350 \begin_inset CommandInset ref
352 reference "subsec:New-layouts"
365 \begin_layout Description
370 inset Of course a new inset requires a file format update.
373 \begin_layout Description
390 \begin_layout Description
395 style If a new style or inset layout is added to any layout file or module
396 shipped with \SpecialChar LyX
397 , then a new file format is needed in the master (development)
399 It is possible to backport new styles to the stable version without a file
402 \begin_inset CommandInset ref
404 reference "subsec:Backporting-new-styles"
408 for more information.
411 \begin_layout Description
416 style If a style or inset layout is removed in any layout file or module
417 shipped with \SpecialChar LyX
418 , a new file format is required.
421 \begin_layout Standard
426 layouts and modules do
430 require a file format update.
434 \begin_layout Plain Layout
436 \begin_inset CommandInset ref
438 reference "subsec:New-layouts"
451 \begin_layout Standard
452 If you are still unsure, please ask on the development list.
455 \begin_layout Subsection
456 \begin_inset CommandInset label
458 name "subsec:update_lyx_files"
462 How to update the file format number of .lyx files
465 \begin_layout Standard
466 Once you come to the conclusion that a file format update is needed, you
467 should use the following procedure to perform the update:
470 \begin_layout Enumerate
471 Implement and test the new feature, including the reading and writing of
473 Note that any file produced at this stage does not use a valid format,
474 so do not use this version of \SpecialChar LyX
475 for working on any important documents.
478 \begin_layout Enumerate
479 \begin_inset CommandInset label
481 name "enu:Describe_format"
485 Describe the new format in
486 \begin_inset Flex Code
489 \begin_layout Plain Layout
498 \begin_layout Enumerate
499 Update the \SpecialChar LyX
500 file format number in
501 \begin_inset Flex Code
504 \begin_layout Plain Layout
513 \begin_layout Enumerate
514 Update the range of file formats in the array
515 \begin_inset Flex Code
518 \begin_layout Plain Layout
525 \begin_inset Flex Code
528 \begin_layout Plain Layout
537 \begin_layout Enumerate
538 \begin_inset CommandInset label
540 name "enu:Add-an-entry"
544 Add an entry to both format lists (for conversion and reversion) in
545 \begin_inset Newline newline
549 \begin_inset Flex Code
552 \begin_layout Plain Layout
553 lib/lyx2lyx/lyx_2_3.py
559 Add a conversion routine if needed (e.
560 \begin_inset space \thinspace{}
563 g., a new header setting always needs a conversion that adds the new setting,
564 but a new document language does not need one).
565 Add a reversion routine if needed.
567 \begin_inset Newline newline
570 While the conversion routine is required to produce a document that is equivalen
571 t to the old version, the requirements of the reversion are not that strict.
572 If possible, try to produce a proper reversion, using ERT if needed, but
573 for some features this might be too complicated.
574 In this case, the minimum requirement of the reversion routine is that
575 it produces a valid document which can be read by an older \SpecialChar LyX
577 If absolutely needed, even data loss is allowed for the reversion.
578 (In that case, you might want to add a LyX comment that indicates what
579 you have had to do, so the user is at least warned).
582 \begin_layout Enumerate
583 Since tex2lyx has several implicit file format dependencies caused by sharing
584 code with \SpecialChar LyX
585 , updating the file format of .lyx files produced by tex2lyx at
586 the same time as updating the main .lyx file format is strongly recommended.
587 Therefore, a compiler warning will be issued if the \SpecialChar LyX
588 and tex2lyx .lyx file
589 format numbers differ.
590 In many cases the tex2lyx update requires only the first and last item
595 \begin_layout Enumerate
596 Update the tex2lyx file format number in
597 \begin_inset Flex Code
600 \begin_layout Plain Layout
609 \begin_layout Enumerate
610 If the lyx2lyx conversion from the old to the new format is empty, or if
611 tex2lyx does not yet output the changed feature, you do not need any further
613 Otherwise, search for the changed feature in tex2lyx, and adjust the output
614 according to the lyx2lyx changes.
617 \begin_layout Enumerate
618 Update the tex2lyx test references as described in
619 \begin_inset CommandInset ref
620 LatexCommand formatted
621 reference "sec:Updating-test-references"
629 \begin_layout Enumerate
630 If you did not implement full tex2lyx support for the new feature, add a
632 \begin_inset Flex Code
635 \begin_layout Plain Layout
641 describing the missing bits.
642 Note that it is perfectly fine if you do not add full tex2lyx support for
643 a new feature: The updating recommendation above is only issued for the
644 syntax of the produced .lyx file.
645 It is no problem if some features supported by \SpecialChar LyX
646 are still output as ERT
648 The problems in the past that resulted in the update recommendation were
649 related to mixed version syntax, not ERT.
652 \begin_layout Enumerate
653 It would be nice if you could create a .lyx test file which contains instances
654 of all changed or added features.
655 This could then be used to test lyx2lyx and tex2lyx.
656 Unfortunately, it has not yet been decided how to collect such examples,
657 so please ask on the development list if you want to create one.
660 \begin_layout Enumerate
661 \begin_inset CommandInset label
663 name "enu:updatefiles"
667 Update LyX's .lyx documentation files to the new format.
668 The developer who makes the change knows best what changes to expect when
669 inspecting the resulting diff.
670 Because of this, you might be able to catch a bug in the lyx2lyx code that
671 updates the format just by taking a quick scan through the large diff that
673 \begin_inset Note Note
676 \begin_layout Plain Layout
677 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
678 see which layout update made an unexpected change by looking at the git
679 log of a .lyx file that suffers the problem.
684 To do this, first make sure that there are no changes to the git repository
685 that you will not want to commit (this is needed because it will be convenient
686 to commit with the command
687 \begin_inset Flex Code
690 \begin_layout Plain Layout
697 Then run the following command in the root folder of the source:
698 \begin_inset Flex Code
701 \begin_layout Plain Layout
702 python development/tools/updatedocs.py
708 Look at the resulting changes using the command
709 \begin_inset Flex Code
712 \begin_layout Plain Layout
719 If anything looks surprising, please investigate.
720 Keep in mind that the case of
721 \begin_inset Flex Code
724 \begin_layout Plain Layout
730 is special, because it is first generated with
731 \begin_inset Flex Code
734 \begin_layout Plain Layout
740 before being converted to the latest format.
741 Finally, commit using
742 \begin_inset Flex Code
745 \begin_layout Plain Layout
754 \begin_layout Subsection
755 Updating the file format number of layout files
758 \begin_layout Standard
759 The procedure for updating the layout files is similar to that in step
760 \begin_inset CommandInset ref
762 reference "enu:updatefiles"
767 \begin_inset CommandInset ref
769 reference "subsec:update_lyx_files"
775 \begin_inset Flex Code
778 \begin_layout Plain Layout
779 python development/tools/updatelayouts.py
785 \begin_inset Flex Code
788 \begin_layout Plain Layout
797 \begin_layout Standard
798 Note that we do not automatically any local layout used in the
799 \begin_inset Flex Code
802 \begin_layout Plain Layout
808 files shipped with \SpecialChar LyX
809 because users would then not be able to export to older
811 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
812 to open the file in \SpecialChar LyX
813 2.1.x, there would be an error because the file would
814 contain a local layout whose format is too new.
815 The root reason for this is that we do not support converting layouts to
816 older layout formats, as we do for the
817 \begin_inset Flex Code
820 \begin_layout Plain Layout
829 \begin_layout Subsection
830 Updating the file format number of bind/ui files
833 \begin_layout Standard
834 A change to the functionality of existing LFUNs can require a conversion
836 \begin_inset Flex Code
839 \begin_layout Plain Layout
846 \begin_inset Flex Code
849 \begin_layout Plain Layout
855 files, and therefore an increment of the LFUN format, as well as a conversion
857 \begin_inset Flex Code
860 \begin_layout Plain Layout
867 The latter cannot be done automatically and also requires an update of
871 \begin_inset space \space{}
874 of someone who might have made a set of \SpecialChar LyX
875 teaching manuals for use in their
880 \begin_layout Plain Layout
881 \begin_inset Flex URL
884 \begin_layout Plain Layout
886 http://www.lyx.org/trac/ticket/9794
899 \begin_layout Standard
900 To update the LFUN format:
903 \begin_layout Enumerate
904 Increment the LFUN file format number in
905 \begin_inset Flex Code
908 \begin_layout Plain Layout
917 \begin_layout Enumerate
918 Implement the LFUN conversion in
919 \begin_inset Flex Code
922 \begin_layout Plain Layout
923 lib/scripts/prefs2prefs_lfuns.py
931 \begin_layout Enumerate
933 \begin_inset CommandInset ref
935 reference "enu:updatefiles"
940 \begin_inset CommandInset ref
942 reference "subsec:update_lyx_files"
947 \begin_inset Flex Code
950 \begin_layout Plain Layout
956 command, use this command:
957 \begin_inset Flex Code
960 \begin_layout Plain Layout
961 bash development/tools/updatelfuns.sh
968 \begin_inset Note Note
971 \begin_layout Plain Layout
972 This file should really be converted to python.
980 \begin_layout Enumerate
981 Update Info insets in
982 \begin_inset Flex Code
985 \begin_layout Plain Layout
992 To do so, increment the \SpecialChar LyX
993 format and proceed as in
994 \begin_inset CommandInset ref
996 reference "subsec:update_lyx_files"
1001 \begin_inset CommandInset ref
1003 reference "enu:Describe_format"
1008 \begin_inset CommandInset ref
1010 reference "enu:updatefiles"
1015 In the lyx2lyx implementation (step
1016 \begin_inset CommandInset ref
1018 reference "enu:Add-an-entry"
1022 ), implement a conversion similar to the one in
1023 \begin_inset Flex Code
1026 \begin_layout Plain Layout
1027 prefs2prefs_lfuns.py
1032 above, as well as a corresponding reversion; for this one can use
1033 \begin_inset Flex Code
1036 \begin_layout Plain Layout
1043 \begin_inset Flex Code
1046 \begin_layout Plain Layout
1047 lib/lyx2lyx/lyx2lyx_tools.py
1056 \begin_layout Subsection
1057 Backporting new styles to the stable version
1058 \begin_inset CommandInset label
1060 name "subsec:Backporting-new-styles"
1067 \begin_layout Standard
1068 Starting with the stable \SpecialChar LyX
1069 2.1 branch, there is a mechanism in place to backport
1070 new styles to the stable version without the need to update the file format.
1071 The basic idea is that the new style definition is automatically copied
1072 to the document preamble so that it can even be used by older minor versions
1073 that did not yet include the style.
1074 To backport a new style to the stable version, the following steps are
1078 \begin_layout Enumerate
1080 \begin_inset Flex Code
1083 \begin_layout Plain Layout
1089 to the style definition in the development version.
1092 \begin_layout Enumerate
1093 Copy the style definition to the stable version, but use
1094 \begin_inset Flex Code
1097 \begin_layout Plain Layout
1104 If needed adjust the format to the one used by the stable version (see
1105 the customization manual for details of the layout file format).
1108 \begin_layout Enumerate
1109 For each update of the style in a later stable version, increase the argument
1111 \begin_inset Flex Code
1114 \begin_layout Plain Layout
1121 (In the stable version, the development version should not be touched.)
1124 \begin_layout Standard
1125 For details about the
1126 \begin_inset Flex Code
1129 \begin_layout Plain Layout
1135 flag see the customization manual.
1137 \begin_inset Flex Code
1140 \begin_layout Plain Layout
1146 support is needed for backported styles: Since the style of the development
1147 version has an infinite version number, it will always be used.
1148 Furthermore, since its version number is less than one, the style will
1149 not be written anymore to the document header for files saved by the new
1153 \begin_layout Section
1154 New layouts and modules
1157 \begin_layout Standard
1158 \begin_inset Note Greyedout
1161 \begin_layout Description
1162 Note: This section is currently only a proposal under discussion.
1163 Please correct/amend as suited.
1164 Remove this note once a consensus is found.
1167 \begin_layout Plain Layout
1169 \begin_inset Quotes eld
1172 Proposal for a guide on updating layouts
1173 \begin_inset Quotes erd
1176 for details and background
1179 \begin_layout Plain Layout
1180 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1188 \begin_layout Subsection
1189 \begin_inset CommandInset label
1191 name "subsec:New-layouts"
1198 \begin_layout Standard
1199 Adding a new layout file to the \SpecialChar LyX
1201 \begin_inset Quotes eld
1204 officially supported
1205 \begin_inset Quotes erd
1209 You should therefore think carefully about whether you really want to do
1210 this and discuss it on lyx-devel, since you will need to be prepared to
1211 update and fix the layout if necessary.
1212 If the layout is experimental or for a rarely used document class, then
1213 it may be better to add it to the relevant portion of the \SpecialChar LyX
1217 \begin_inset CommandInset href
1219 target "https://wiki.lyx.org/Layouts/Layouts"
1226 \begin_layout Standard
1227 In older versions of this document, it was stated that new layout files
1228 require a file format change.
1229 After some discussion it was decided that this is not needed.
1233 \begin_layout Plain Layout
1235 \begin_inset CommandInset href
1237 name "the thread “Proposal for a guide on updating layouts”"
1238 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1251 For reference, here are the arguments on each side
1255 \begin_layout Description
1257 \begin_inset Quotes eld
1260 New layout files are a file format change
1261 \begin_inset Quotes erd
1267 \begin_layout Itemize
1268 All documents produced by 2.2.
1269 \begin_inset Formula $x$
1272 can always be edited and exported even if
1273 \begin_inset Formula $x$
1277 This is important for people using different machines, or exchanging work
1281 \begin_layout Description
1283 \begin_inset Quotes eld
1286 New layout files are not a file format change
1287 \begin_inset Quotes erd
1293 \begin_layout Itemize
1294 No new LaTeX classes can be supported in a stable version, and stable versions
1295 have a typical lifetime of 2–3 years.
1298 \begin_layout Itemize
1299 We have the same situation already with custom layout files: If a document
1300 using a custom layout file is moved between machines or people, then the
1301 layout file needs to be exchanged as well.
1302 If that is not done, then we have a fallback implemented so that such documents
1303 can still be edited, but not exported, and the user gets a warning.
1307 \begin_layout Itemize
1308 The lyx2lyx script cannot do anything useful in such a case.
1312 \begin_layout Standard
1313 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1315 then, you should do the following:
1318 \begin_layout Enumerate
1319 Put your new layout file in
1320 \begin_inset Flex Code
1323 \begin_layout Plain Layout
1330 \begin_inset Flex Code
1333 \begin_layout Plain Layout
1334 git add lib/layouts/newlayout.layout
1339 ) so that it will be committed.
1342 \begin_layout Enumerate
1344 \begin_inset Flex Code
1347 \begin_layout Plain Layout
1353 , so that the new layout actually gets installed.
1356 \begin_layout Enumerate
1358 \begin_inset Flex Code
1361 \begin_layout Plain Layout
1362 lib/doc/LaTeXConfig.lyx
1367 containing in particular a line like
1375 \begin_layout Standard
1376 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1377 \begin_inset Flex Code
1380 \begin_layout Plain Layout
1381 info-insert textclass <name>
1387 This inset will automatically display a boxed
1388 \begin_inset Quotes eld
1392 \begin_inset Quotes erd
1396 \begin_inset Quotes eld
1400 \begin_inset Quotes erd
1403 depending on the availability of the package.
1407 \begin_layout Enumerate
1408 A template or example is strongly encouraged (but not necessarily required).
1409 It is also possible to provide both.
1411 \begin_inset Flex Code
1414 \begin_layout Plain Layout
1421 \begin_inset Flex Code
1424 \begin_layout Plain Layout
1433 \begin_layout Enumerate
1434 Reconfigure \SpecialChar LyX
1438 \begin_layout Enumerate
1439 Ensure the autotests for the new layout pass (see
1440 \begin_inset CommandInset ref
1442 reference "par:when-to-run-an-export-test"
1449 \begin_layout Subsection
1453 \begin_layout Standard
1454 Adding a new module is very similar to adding a new layout.
1455 Therefore, the previous section applies to new modules as well, with two
1459 \begin_layout Enumerate
1460 You only need to add an entry to
1461 \begin_inset Flex Code
1464 \begin_layout Plain Layout
1465 lib/doc/LaTeXConfig.lyx
1470 if the module requires a LaTeX package.
1471 In that case, the command for entering the InsetInfo is:
1472 \begin_inset Flex Code
1475 \begin_layout Plain Layout
1476 \paragraph_spacing single
1477 info-insert package <name>
1485 \begin_layout Enumerate
1486 Modules do not need a template, only an example, which is strongly encouraged
1487 but not necessarily required.
1490 \begin_layout Subsection
1491 Layouts for document classes with incompatible versions
1494 \begin_layout Standard
1495 Every now and then, there are changes to LaTeX document classes that break
1496 backwards compatibility.
1500 \begin_layout Plain Layout
1501 Uwe has suggested we implement automatic detection of changes in class files.
1502 This could be done by running a script every month that checks if a document
1503 class was changed at CTAN and at the homepages of the scientific journals.
1504 If it reports a change, we can check if our template and layout file are
1505 still usable with the changed document class.
1506 (This is different from the autotests insofar, as this would also catch
1507 changes that do not result in compilation errors.)
1512 Reasons can be a new name for the
1513 \begin_inset Flex Code
1516 \begin_layout Plain Layout
1522 file, removed \SpecialChar LaTeX
1524 How should this best be handled in \SpecialChar LyX
1528 \begin_layout Standard
1529 The idea is to support the new version with a new \SpecialChar LyX
1533 \begin_layout Itemize
1534 Existing documents can still be opened in \SpecialChar LyX
1535 and will continue to work on
1536 systems where the old version is still installed.
1540 \begin_layout Itemize
1541 With differently named
1542 \begin_inset Flex Code
1545 \begin_layout Plain Layout
1551 files, \SpecialChar LyX
1552 can check for the availability of the particular version and reflect
1554 Different document class versions with the same file name are currently
1555 (2.2.x) not detected by the configuration script.
1556 This is planned for 2.3.
1560 \begin_layout Plain Layout
1561 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1564 \begin_layout Plain Layout
1565 However, what we really need is version detection for the configuration,
1566 so that the user can be warned if the required class file has the wrong
1568 (If the class file keeps the name over the version change, only one of
1569 the two layout files generates compilable documents.)
1572 \begin_layout Plain Layout
1573 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1582 \begin_layout Itemize
1583 The new layout can be added both to the master and the stable branches,
1584 in accord with the policy discussed in
1585 \begin_inset CommandInset ref
1586 LatexCommand formatted
1587 reference "subsec:New-layouts"
1592 No lyx2lyx conversion is then required when a new major version is released.
1595 \begin_layout Standard
1596 The user can move an existing document to the new version simply by selecting
1597 a new document class.
1598 This step is well supported by \SpecialChar LyX
1599 , with established methods for handling
1600 unsupported styles and other changes.
1601 This way, no lyx2lyx code is required.
1604 \begin_layout Standard
1605 The steps to support a new version of an existing document class are thus:
1608 \begin_layout Itemize
1609 Create a new layout file including the upstream version in the name (avoid
1610 special characters like spaces and dots), e.g.
1612 \begin_inset Flex Code
1615 \begin_layout Plain Layout
1616 acmsiggraph-v0-92.layout
1624 \begin_layout Itemize
1625 Include the name of the
1626 \begin_inset Flex Code
1629 \begin_layout Plain Layout
1635 file as an optional argument in the
1636 \begin_inset Flex Code
1639 \begin_layout Plain Layout
1647 line and include the version number in the GUI name:
1648 \begin_inset Newline newline
1652 \begin_inset Flex Code
1655 \begin_layout Plain Layout
1658 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1659 \begin_inset space ~
1670 \begin_layout Itemize
1671 Update the GUI name in the old layout file (whose name should not be changed),
1673 \begin_inset Newline newline
1677 \begin_inset Flex Code
1680 \begin_layout Plain Layout
1683 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1684 \begin_inset space ~
1695 \begin_layout Itemize
1696 To avoid duplicate definitions, the new layout can
1697 \begin_inset Flex Code
1700 \begin_layout Plain Layout
1706 the old layout file and add\SpecialChar breakableslash
1707 remove\SpecialChar breakableslash
1708 obsolete\SpecialChar breakableslash
1709 modify settings and styles (similar
1711 \begin_inset Flex Code
1714 \begin_layout Plain Layout
1724 \begin_layout Standard
1725 It may be tempting to let the new layout be the
1726 \begin_inset Quotes eld
1730 \begin_inset Quotes erd
1733 and have the old layout import it.
1734 However, this should not be done because any changes to the new layout
1735 would need undo steps in the importing old layout.
1739 \begin_layout Itemize
1740 If the new LaTeX document class obsoletes the old one, update the example
1741 and template files to use the new layout.
1742 Add a note about the changes (preferably with a pointer to the documentation
1747 \begin_layout Standard
1748 This way, new documents based on the template or example will use the up-to-date
1749 document class version.
1753 \begin_layout Standard
1754 \begin_inset Newpage newpage
1760 \begin_layout Section
1764 \begin_layout Standard
1765 Automated tests are an important tool to detect bugs and regressions in
1766 software development.
1767 Some projects like gcc even require each bug fix to be accompanied by a
1768 test case for the automatic test suite, that would detect this bug.
1769 Testing interactive features automatically is of course very hard, but
1770 core functionality like document import and export can be tested quite
1771 easily, and some tests of this kind exist.
1774 \begin_layout Subsection
1778 \begin_layout Standard
1779 There are attempts to set up a suite of unit tests for LyX.
1782 \begin_layout Standard
1783 TODO: describe what is done and what is still to do.
1786 \begin_layout Subsection
1790 \begin_layout Standard
1791 The tex2lyx tests are located in the
1792 \begin_inset Flex Code
1795 \begin_layout Plain Layout
1801 subfolder of the \SpecialChar LyX
1802 source code distribution.
1803 The actual testing is performed by the simple python script
1804 \begin_inset Flex Code
1807 \begin_layout Plain Layout
1808 src/tex2lyx/test/runtests.py
1814 Each test consists of two files:
1815 \begin_inset Flex Code
1818 \begin_layout Plain Layout
1824 contains the \SpecialChar LaTeX
1825 code that should be tested.
1827 \begin_inset Flex Code
1830 \begin_layout Plain Layout
1836 contains the expected output of tex2lyx.
1837 When a test is run, the actual produced output is compared with the stored
1839 The test passes if both are identical.
1840 The test machinery is also able to generate a file
1841 \begin_inset Flex Code
1844 \begin_layout Plain Layout
1850 by exporting the produced .lyx file with \SpecialChar LyX
1852 This may be useful for roundtrip comparisons.
1855 \begin_layout Subsubsection
1859 \begin_layout Standard
1860 The tex2lyx tests can be run in several ways.
1862 \begin_inset Flex Code
1865 \begin_layout Plain Layout
1871 subfolder of the build directory, the commands
1872 \begin_inset Flex Code
1875 \begin_layout Plain Layout
1881 (cmake, all platforms),
1882 \begin_inset Flex Code
1885 \begin_layout Plain Layout
1891 (cmake, when using a make based build system and not MSVC) or
1892 \begin_inset Flex Code
1895 \begin_layout Plain Layout
1901 (autotools) will run the tex2lyx tests.
1902 Alternatively, in the root of the build directory, the command
1903 \begin_inset Flex Code
1906 \begin_layout Plain Layout
1912 runs all tests whose names match the regex
1913 \begin_inset Quotes eld
1917 \begin_inset Quotes erd
1921 Another way to run the tex2lyx tests in the root build directory is to
1922 instead use the command
1923 \begin_inset Flex Code
1926 \begin_layout Plain Layout
1927 ctest -L '(cmplyx|roundtrip)'
1932 , which runs all tests categorized with the label
1933 \begin_inset Quotes eld
1937 \begin_inset Quotes erd
1941 \begin_inset Quotes eld
1945 \begin_inset Quotes erd
1949 If a test fails, the differences between the expected and actual results
1950 are output in unified diff format.
1953 \begin_layout Subsubsection
1954 Updating test references
1955 \begin_inset CommandInset label
1957 name "sec:Updating-test-references"
1964 \begin_layout Standard
1965 In some cases a changed tex2lyx output is not a test failure, but wanted,
1967 \begin_inset space \thinspace{}
1971 \begin_inset space \space{}
1974 if a tex2lyx bug was fixed, or a new feature was added.
1975 In these cases the stored references need to be updated.
1976 To do so if using autotools, call
1977 \begin_inset Flex Code
1980 \begin_layout Plain Layout
1987 \begin_inset Flex Code
1990 \begin_layout Plain Layout
1996 subdirectory of the build directory.
1997 If instead using CMake, call
1998 \begin_inset Flex Code
2001 \begin_layout Plain Layout
2002 make updatetex2lyxtests
2007 in the build directory or in the
2008 \begin_inset Flex Code
2011 \begin_layout Plain Layout
2017 subdirectory of the build directory.
2021 \begin_layout Plain Layout
2022 Note that this is a case where a make target in the build directory can
2023 affect the source directory, which might not be advisable.
2028 On Windows do the following:
2031 \begin_layout Itemize
2032 Assure that the path to the python.exe is in your system PATH variable.
2035 \begin_layout Itemize
2036 Double-click on the file
2037 \begin_inset Flex Code
2040 \begin_layout Plain Layout
2041 updatetex2lyxtests.vcxproj
2046 in the build directory or in the
2047 \begin_inset Flex Code
2050 \begin_layout Plain Layout
2056 subdirectory of your build directory.
2059 \begin_layout Itemize
2060 In the appearing MSVC program right-click on the project
2064 in the project explorer and chose
2071 \begin_layout Standard
2072 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2074 Please examine the changed output carefully before committing the changed
2075 files to the repository: Since the test machinery does not do a roundtrip
2077 \begin_inset Formula $\Rightarrow$
2081 \begin_inset Formula $\Rightarrow$
2084 .tex, and does not compare the produced dvi or pdf output, it assumes that
2085 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2087 There is only one chance to detect wrong output: before committing a new
2089 Once it is committed, it is quite difficult to verify whether it is correct.
2092 \begin_layout Standard
2097 update the test references by opening them with \SpecialChar LyX
2098 or directly running lyx2lyx
2100 This would not work, since lyx2lyx and \SpecialChar LyX
2101 produce slightly different files
2102 regarding insignificant whitespace and line breaks.
2105 \begin_layout Subsubsection
2109 \begin_layout Standard
2110 In many cases tests for new features may be added to one of the existing
2111 test files, but sometimes this is not possible or not wanted.
2112 Then a new test file needs to be added:
2115 \begin_layout Enumerate
2117 \begin_inset Flex Code
2120 \begin_layout Plain Layout
2121 src/tex2lyx/test/<test name>.tex
2126 and run tex2lyx in roundtrip mode to produce the file
2127 \begin_inset Flex Code
2130 \begin_layout Plain Layout
2131 src/tex2lyx/test/<test name>.lyx.lyx
2137 This file will be the new reference.
2140 \begin_layout Enumerate
2141 Once you confirmed that the tex2lyx output is correct, add the new files
2142 to the corresponding lists in
2143 \begin_inset Flex Code
2146 \begin_layout Plain Layout
2147 src/tex2lyx/test/runtests.py
2153 \begin_inset Flex Code
2156 \begin_layout Plain Layout
2157 src/tex2lyx/Makefile.am
2163 \begin_inset Flex Code
2166 \begin_layout Plain Layout
2167 src/tex2lyx/test/CMakeLists.txt
2175 \begin_layout Enumerate
2176 Commit the changes to the repository, or send a patch to the development
2177 list and ask for committing if you do not have commit rights.
2180 \begin_layout Subsection
2181 ctest automatic tests
2184 \begin_layout Standard
2185 Some tests are located in the
2186 \begin_inset Flex Code
2189 \begin_layout Plain Layout
2190 development/autotests/
2195 subfolder of the \SpecialChar LyX
2196 source code distribution.
2201 \begin_layout Plain Layout
2202 The README document in this folder only describes the
2203 \begin_inset Quotes eld
2207 \begin_inset Quotes erd
2210 subset of autotests!
2218 \begin_layout Standard
2219 These tests can be run by the commands
2220 \begin_inset Flex Code
2223 \begin_layout Plain Layout
2233 (all platforms) or (when using a make based build system and not MSVC)
2235 \begin_inset Flex Code
2238 \begin_layout Plain Layout
2245 \begin_inset Flex Code
2248 \begin_layout Plain Layout
2259 The test logs are written to the
2260 \begin_inset Flex Code
2263 \begin_layout Plain Layout
2277 \begin_layout Subsubsection
2281 \begin_layout Standard
2282 The export tests are integration tests.
2283 They take longer to run and are more likely to break than the tex2lyx tests.
2284 Nevertheless, they have caught many regressions and without a better alternativ
2285 e it is important to keep them up-to-date and understand how they work.
2288 \begin_layout Standard
2290 \begin_inset Quotes eld
2294 \begin_inset Quotes erd
2297 documentation, template, and example documents.
2298 In addition, there are a number of dedicated sample documents in the
2299 \begin_inset Flex Code
2302 \begin_layout Plain Layout
2308 subfolder of the \SpecialChar LyX
2309 source code distribution.
2310 All samples are (after copying and eventual processing by scripts) exported
2311 to various output formats via the
2312 \begin_inset Flex Code
2315 \begin_layout Plain Layout
2321 command line option.
2322 The tests checks for errors reported by LyX.
2323 (However, error-free export is no guarantee for an error-free output document.)
2326 \begin_layout Paragraph
2327 \begin_inset CommandInset label
2329 name "par:when-to-run-an-export-test"
2333 Expectations of LyX developers
2336 \begin_layout Standard
2337 Because the export tests are integration tests and take a long time to run,
2338 LyX developers are rarely expected to run all of the tests.
2339 Here are some good practices to follow by developers:
2342 \begin_layout Itemize
2343 When making a non-trivial change to a .layout file, run the export and layout
2344 tests corresponding with that .layout file.
2347 \begin_layout Itemize
2348 When making non-trivial changes to a .lyx file, run the export tests correspondin
2349 g to that .lyx file.
2354 \begin_layout Plain Layout
2355 This rule is due to revision.
2359 \begin_layout Plain Layout
2360 There is an objection from the documentation maintainer that working on
2361 the documentation must not be complicated by having to consider non-standard
2365 \begin_layout Itemize
2366 successful compiling/testing an edited documentation file with pdflatex
2367 suffices to ensure it can be commited, not tests with other exports are
2371 \begin_layout Plain Layout
2372 If sudden failures with other exports due to “half-tested” documentation
2373 updates are a problem for the test maintainer, the test suite should use
2377 \begin_layout Itemize
2378 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2381 \begin_layout Itemize
2382 updated regularely (but on a time chosen by the test suite maintainer) from
2383 the originals in lib/doc/
2386 \begin_layout Plain Layout
2390 \begin_layout Itemize
2391 no test will fail due to ongoing work on documentation,
2394 \begin_layout Itemize
2395 the documentation is still tested in full (with some delay),
2398 \begin_layout Itemize
2399 failures with non-default export can be examined and handled accordingly
2400 in one run with the cache update,
2403 \begin_layout Itemize
2404 “interesting failures” (like the nested-language+polyglossia problem in
2405 es/Customization can be separated and moved into dedicated test samples.
2413 \begin_layout Itemize
2414 When making non-trivial changes to LyX's \SpecialChar LaTeX
2416 touching the encoding code or package handling code that you expect will
2417 change the exported \SpecialChar LaTeX
2422 \begin_layout Standard
2423 \paragraph_spacing single
2424 Consider running all of the export tests before and after your change.
2425 If there are differences, please reconcile these (i.e.
2426 fix the bug or fix the tests)
2431 Ask for help if you're not sure what to.
2434 \begin_layout Standard
2435 If you do not want to run the tests,
2438 \begin_layout Itemize
2439 post the patch on the list and others will run the tests and eventually
2443 \begin_layout Itemize
2444 commit, but be prepared to fix eventually arising problems or to revert
2445 the commit if there is no easy fix.
2449 \begin_layout Itemize
2450 Understand how to interpret test failures.
2451 If your commit is found to have broken a test, you should be able to interpret
2452 the test results when made aware of them.
2454 \begin_inset CommandInset ref
2456 reference "subsec:Interpreting-export-tests"
2463 \begin_layout Paragraph
2464 \begin_inset CommandInset label
2466 name "par:export-test-output-formats"
2473 \begin_layout Standard
2474 The following output formats are currently tested for each sample document
2476 \begin_inset CommandInset ref
2478 reference "par:Export-test-filtering"
2485 \begin_layout Labeling
2486 \labelwidthstring 00.00.0000
2491 \begin_layout Labeling
2492 \labelwidthstring 00.00.0000
2493 lyx16 LyX 1.6 file format (lyx2lyx)
2496 \begin_layout Labeling
2497 \labelwidthstring 00.00.0000
2498 lyx21 LyX 2.1 file format (lyx2lyx)
2501 \begin_layout Labeling
2502 \labelwidthstring 00.00.0000
2503 xhtml LyXHTML (native LyX HTML export)
2507 \begin_layout Labeling
2508 \labelwidthstring 00.00.0000
2510 \begin_inset space ~
2514 \begin_inset space ~
2521 \begin_layout Labeling
2522 \labelwidthstring pdf5msystemFM
2523 dvi DVI (8-bit latex)
2526 \begin_layout Labeling
2527 \labelwidthstring pdf5msystemFM
2528 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2531 \begin_layout Labeling
2532 \labelwidthstring pdf5msystemFM
2533 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2536 \begin_layout Labeling
2537 \labelwidthstring pdf5msystemFM
2541 \begin_layout Labeling
2542 \labelwidthstring pdf5msystemFM
2543 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2546 \begin_layout Labeling
2547 \labelwidthstring pdf5msystemFM
2548 pdf4_systemF PDF (XeTeX with Unicode fonts)
2551 \begin_layout Labeling
2552 \labelwidthstring pdf5msystemFM
2553 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2556 \begin_layout Labeling
2557 \labelwidthstring pdf5msystemFM
2558 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2562 \begin_layout Labeling
2563 \labelwidthstring 00.00.0000
2565 \begin_inset space ~
2569 \begin_inset space ~
2573 \begin_inset space ~
2577 \begin_inset space ~
2584 \begin_layout Labeling
2585 \labelwidthstring pdf5msystemFM
2586 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2589 \begin_layout Labeling
2590 \labelwidthstring pdf5msystemFM
2591 pdf3 DVI -> PDF (dvipdfm)
2595 \begin_layout Labeling
2596 \labelwidthstring 00.00.0000
2598 \begin_inset space ~
2601 tested: (or only if set as default output format in the document source)
2605 \begin_layout Labeling
2606 \labelwidthstring pdf5msystemFM
2610 \begin_layout Labeling
2611 \labelwidthstring pdf5msystemFM
2612 luatex LaTeX (LuaTeX)
2615 \begin_layout Labeling
2616 \labelwidthstring pdf5msystemFM
2617 dviluatex LaTeX (dviluatex)
2620 \begin_layout Labeling
2621 \labelwidthstring pdf5msystemFM
2622 pdflatex LaTeX (pdflatex)
2625 \begin_layout Labeling
2626 \labelwidthstring pdf5msystemFM
2627 platex LaTeX (pLaTeX)
2630 \begin_layout Labeling
2631 \labelwidthstring pdf5msystemFM
2635 \begin_layout Labeling
2636 \labelwidthstring pdf5msystemFM
2637 eps3 EPS (encapsulated Postscript) (cropped)
2640 \begin_layout Labeling
2641 \labelwidthstring pdf5msystemFM
2642 ps DVI -> Postscript (dvips)
2645 \begin_layout Labeling
2646 \labelwidthstring pdf5msystemFM
2650 \begin_layout Labeling
2651 \labelwidthstring pdf5msystemFM
2652 text (nor text2, ..., text4)
2655 \begin_layout Labeling
2656 \labelwidthstring pdf5msystemFM
2660 \begin_layout Labeling
2661 \labelwidthstring pdf5msystemFM
2665 \begin_layout Labeling
2666 \labelwidthstring pdf5msystemFM
2670 \begin_layout Labeling
2671 \labelwidthstring pdf5msystemFM
2676 \begin_layout Paragraph
2677 \begin_inset CommandInset label
2679 name "par:Configuring-ctests"
2683 Configuring the tests
2686 \begin_layout Standard
2687 To enable the export autotests, add the
2688 \begin_inset Flex Code
2691 \begin_layout Plain Layout
2692 -DLYX_ENABLE_EXPORT_TESTS=ON
2701 \begin_layout Standard
2702 \begin_inset Flex Code
2705 \begin_layout Plain Layout
2706 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2714 \begin_layout Standard
2716 This flag will increase the time for the cmake command by several seconds,
2717 mainly because of the process of inverting tests (see Section
2718 \begin_inset CommandInset ref
2720 reference "subsec:Interpreting-export-tests"
2727 \begin_layout Paragraph
2728 \begin_inset CommandInset label
2730 name "par:ctest-options"
2737 \begin_layout Standard
2738 To run all tests, in the build directory simply run the command
2739 \begin_inset Flex Code
2742 \begin_layout Plain Layout
2749 A full, up-to-date TeXLive installation is recommended to run the tests.
2750 Otherwise, some tests will fail.
2751 Tests with additional requirements are labeled
2752 \begin_inset Quotes eld
2755 unreliable:nonstandard
2756 \begin_inset Quotes erd
2763 \begin_layout Standard
2764 To run only some of the tests, use command line options (see examples below):
2767 \begin_layout Labeling
2768 \labelwidthstring -R
2769 \begin_inset Flex Code
2772 \begin_layout Plain Layout
2778 Run only the tests whose names match the given regular expression.
2781 \begin_layout Labeling
2782 \labelwidthstring -R
2783 \begin_inset Flex Code
2786 \begin_layout Plain Layout
2792 Run only the tests whose labels match the given regular expression.
2793 A test may have more that one label.
2797 \begin_layout Labeling
2798 \labelwidthstring -R
2799 \begin_inset Flex Code
2802 \begin_layout Plain Layout
2808 Exclude the tests whose names match the given regular expression.
2811 \begin_layout Labeling
2812 \labelwidthstring -R
2813 \begin_inset Flex Code
2816 \begin_layout Plain Layout
2822 Exclude the tests whose labels match the given regular expression.
2823 Cannot be combined with
2824 \begin_inset Flex Code
2827 \begin_layout Plain Layout
2836 \begin_layout Standard
2837 The following options help to find good selection patterns:
2840 \begin_layout Labeling
2841 \labelwidthstring -R
2842 \begin_inset Flex Code
2845 \begin_layout Plain Layout
2851 List the tests that would be run but not actually run them.
2856 \begin_layout Standard
2857 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2858 to know how many tests there are or whether your
2859 \begin_inset Flex Code
2862 \begin_layout Plain Layout
2868 regular expression did what you expected.
2872 \begin_layout Labeling
2873 \labelwidthstring -R
2874 \begin_inset Flex Code
2877 \begin_layout Plain Layout
2878 \SpecialChar nobreakdash
2879 \SpecialChar nobreakdash
2885 print the list of all labels associated with the test set.
2886 Can also be combined with -R, -L, -E, ...
2890 \begin_layout Standard
2891 Other useful options are:
2894 \begin_layout Labeling
2895 \labelwidthstring -R
2896 \begin_inset Flex Code
2899 \begin_layout Plain Layout
2905 Run the tests in parallel using the given number of jobs.
2909 \begin_layout Standard
2910 We are still working on getting the tests to run in parallel.
2911 However, when running the tests in parallel, sometimes tests fail that
2912 pass when run sequentially.
2913 A reasonable approach is to first run the tests in parallel and then run
2914 the failed tests sequentially.
2917 \begin_layout Standard
2918 For example, to run 8 jobs at a time:
2921 \begin_layout Standard
2922 \begin_inset Flex Code
2925 \begin_layout Plain Layout
2934 \begin_layout Standard
2935 \begin_inset Flex Code
2938 \begin_layout Plain Layout
2939 ctest \SpecialChar nobreakdash
2940 \SpecialChar nobreakdash
2949 \begin_layout Standard
2950 When specifying a subset of the tests (e.g.
2952 \begin_inset Flex Code
2955 \begin_layout Plain Layout
2956 \SpecialChar nobreakdash
2962 ), the same subset must be specified when using the
2963 \begin_inset Flex Code
2966 \begin_layout Plain Layout
2967 \SpecialChar nobreakdash
2968 \SpecialChar nobreakdash
2974 option because it is the test numbers that are used to index which tests
2975 failed on the previous run.
2978 \begin_layout Standard
2980 Note that some tests cannot be run in parallel.
2981 These tests are marked in the code with the
2982 \begin_inset Flex Code
2985 \begin_layout Plain Layout
2996 \begin_layout Labeling
2997 \labelwidthstring -R
2998 \begin_inset Flex Code
3001 \begin_layout Plain Layout
3002 \SpecialChar nobreakdash
3003 \SpecialChar nobreakdash
3009 Set a global timeout on all tests that do not already have a timeout set
3014 \begin_layout Standard
3015 There have been bugs in LyX and in \SpecialChar LaTeX
3016 which cause compilation to hang, and
3017 without a timeout a test might never stop (in one case there was even a
3019 If a test times out, the
3020 \begin_inset Flex Code
3023 \begin_layout Plain Layout
3029 command exits with error, but you can distinguish between a timed out test
3030 and a failed test in the output reported at the end of the
3031 \begin_inset Flex Code
3034 \begin_layout Plain Layout
3044 \begin_layout Standard
3046 \begin_inset Flex Code
3049 \begin_layout Plain Layout
3055 ) the full list of command line options.
3058 \begin_layout Paragraph
3062 \begin_layout Itemize
3063 run only the export tests:
3064 \begin_inset Flex Code
3067 \begin_layout Plain Layout
3076 \begin_layout Itemize
3078 \begin_inset Flex Code
3081 \begin_layout Plain Layout
3082 ctest -L "inverted|suspended"
3090 \begin_layout Itemize
3091 list all export tests which match any of the labelling patterns:
3092 \begin_inset Flex Code
3095 \begin_layout Plain Layout
3106 \begin_layout Itemize
3107 exclude rarely used output formats and post-processing tests
3108 \begin_inset Flex Code
3111 \begin_layout Plain Layout
3112 ctest -L export -E "_(texF|dvi3|pdf3?)"
3120 \begin_layout Paragraph
3121 \begin_inset CommandInset label
3123 name "subsec:Interpreting-export-tests"
3127 Interpreting the export test results
3130 \begin_layout Standard
3131 A test can fail for several reasons, not all of them bad.
3134 \begin_layout Enumerate
3135 A new or edited sample document may be incompatible with some output formats.
3138 \begin_layout Enumerate
3139 A dependency is not met (e.g.
3140 the \SpecialChar LaTeX
3142 One hint that this is the case is that the corresponding
3143 \begin_inset Flex Code
3146 \begin_layout Plain Layout
3152 test will likely also fail.
3155 \begin_layout Enumerate
3156 An inverted test fails to fail (i.e.
3157 export that previously failed now works).
3160 \begin_layout Enumerate
3161 An external dependency was updated (e.g.
3166 \begin_layout Enumerate
3167 A recent code change introduced a bug.
3170 \begin_layout Enumerate
3171 \begin_inset CommandInset label
3177 A change in a document exposed a previously unknown bug or an incompatibility
3178 with an export format (e.g.
3179 Lua\SpecialChar LaTeX
3183 \begin_layout Standard
3184 Because the .lyx files are exported in several formats, it is not surprising
3185 that many of the exports fail.
3186 This expectation of failure is addressed by
3187 \begin_inset Quotes eld
3191 \begin_inset Quotes erd
3194 the tests, that is, by marking the test as
3195 \begin_inset Quotes eld
3199 \begin_inset Quotes erd
3202 if the export exits with error and as
3203 \begin_inset Quotes eld
3207 \begin_inset Quotes erd
3210 if the export succeeds
3215 It follows that these expected failures will not show up as failed tests
3216 in the test results and thus will not pollute the
3217 \begin_inset Quotes eld
3221 \begin_inset Quotes erd
3225 If the export actually succeeds, then the test will fail.
3226 The purpose of this failure is to get your attention—something has changed,
3227 possibly for the better.
3230 \begin_layout Standard
3231 We try to document why a test is inverted or ignored.
3232 See the comment (prefixed with
3233 \begin_inset Flex Code
3236 \begin_layout Plain Layout
3242 ) above the block in which the test is listed as inverted or ignored in
3244 \begin_inset Flex Code
3247 \begin_layout Plain Layout
3248 development/autotests/suspiciousTests
3254 \begin_inset Flex Code
3257 \begin_layout Plain Layout
3258 development/autotests/unreliableTests
3264 \begin_inset Flex Code
3267 \begin_layout Plain Layout
3268 development/autotests/ignoredTests
3277 \begin_layout Standard
3278 A good question is why do we enable the tests for non-default formats? The
3279 answer is that if a non-default route is broken it is often because a bug
3280 was introduced in LyX and not because a document-specific change was made
3281 that is not supported by the route.
3282 In other words, there is a high signal/noise ratio in the export tests
3283 for some non-default formats.
3287 \begin_layout Standard
3288 When a test or several tests fail, consider checking the files in the
3289 \begin_inset Flex Code
3292 \begin_layout Plain Layout
3298 subdirectory of your build directory.
3299 In this subdirectory are three files: the file
3300 \begin_inset Flex Code
3303 \begin_layout Plain Layout
3309 simply lists the tests that failed on your last
3310 \begin_inset Flex Code
3313 \begin_layout Plain Layout
3320 \begin_inset Flex Code
3323 \begin_layout Plain Layout
3329 file contains the output from the tests (and often has details explaining
3330 why a test failed); and the
3331 \begin_inset Flex Code
3334 \begin_layout Plain Layout
3340 file lists the times that it took to run the tests.
3343 \begin_layout Paragraph
3344 What action should you take if a test fails?
3347 \begin_layout Standard
3348 \paragraph_spacing single
3349 It is always good to check manually why something fails and if it passes
3350 if the PDF output is good.
3353 \begin_layout Itemize
3354 Generally, if a change breaks compilation for the target format (for the
3355 manuals pdf2) without solving some important other issue,
3357 fix or revert the commit
3359 that led to failure.
3362 \begin_layout Itemize
3363 If it is not possible to (immediately) fix the failure but there are reasons
3364 not to revert the commit (e.g.
3365 it fixes another more important issue),
3369 the failing test case (see
3370 \begin_inset CommandInset ref
3372 reference "par:Inverted-tests"
3379 \begin_layout Itemize
3384 test case fails because the export now works,
3388 the test by removing the labeling pattern from
3389 \begin_inset Quotes eld
3393 \begin_inset Quotes erd
3397 \begin_inset CommandInset ref
3399 reference "par:Inverted-tests"
3406 \begin_layout Itemize
3407 If the export did not fail previously but led to wrong output (PDF, say),
3408 it is in fact an improvement when the test now fails, label it as
3409 \begin_inset Quotes eld
3412 unreliable:wrong:output
3413 \begin_inset Quotes erd
3417 \begin_inset CommandInset ref
3419 reference "par:Unreliable-tests"
3426 \begin_layout Itemize
3427 In case of tests failing due to missing requirements (when only a subset
3428 of TeXLive is installed or a test labeled
3429 \begin_inset Quotes eld
3432 unreliable:nonstandard
3433 \begin_inset Quotes erd
3436 fails), ignore the failure, ask for someone else to run the test, or install
3437 the missing ressources and try again.
3440 \begin_layout Paragraph
3441 \begin_inset CommandInset label
3443 name "par:Inverted-tests"
3450 \begin_layout Standard
3451 Test cases whose name matches a pattern in the file
3452 \begin_inset Flex Code
3455 \begin_layout Plain Layout
3456 development/autotests/suspiciousTests
3466 They get also the test property
3467 \begin_inset Flex Code
3470 \begin_layout Plain Layout
3477 they are reported as failing if the export works without error
3478 \begin_inset Flex URL
3481 \begin_layout Plain Layout
3483 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3491 \begin_layout Standard
3492 Add failing cases to this file, if they cannot be solved
3493 \begin_inset Quotes eld
3497 \begin_inset Quotes erd
3500 but it is expected that the export will work in a foreseeable future, e.g.
3501 low priority issues like failures to export to a non-target format (for
3502 the manuals everything except pdf2).
3505 \begin_layout Standard
3506 The following sublabels are currently present in
3507 \begin_inset Flex Code
3510 \begin_layout Plain Layout
3519 \begin_layout Description
3520 todo test failures that require attention:
3524 \begin_layout Itemize
3525 minor issues to explore and properly sort later,
3528 \begin_layout Itemize
3532 \begin_layout Itemize
3533 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3537 \begin_layout Description
3538 lyxbugs LyX bugs with a Trac number.
3541 \begin_layout Description
3542 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3546 \begin_layout Standard
3547 "Wontfix" if demonstrating correct use and OK in the default output format.
3551 \begin_layout Description
3552 texissues Export fails due to LaTeX limitations like non-ASCII characters
3553 in verbatim or listings, incompatible packages, ...
3557 \begin_layout Standard
3558 "Wontfix" if documents demonstrate correct use in the default output format:
3561 \begin_layout Itemize
3562 If the source can be made more robust without becoming "hackish", fix the
3566 \begin_layout Itemize
3567 if LyX could be enhanced to care for a permanent TeX limitation, file a
3568 ticket at trac and add a pattern under lyxbugs,
3571 \begin_layout Itemize
3572 otherwise, add a pattern here.
3576 \begin_layout Description
3577 attic Documents in the attic.
3578 (Kept for reference and format conversion test.)
3581 \begin_layout Subparagraph
3585 \begin_layout Standard
3586 Test cases whose name additionally matches a pattern in the file
3587 \begin_inset Flex Code
3590 \begin_layout Plain Layout
3591 development/autotests/suspendedTests
3609 This means they are not executed using
3610 \begin_inset Flex Code
3613 \begin_layout Plain Layout
3620 \begin_inset Flex Code
3623 \begin_layout Plain Layout
3630 However, they also get the test property
3631 \begin_inset Flex Code
3634 \begin_layout Plain Layout
3641 they are reported as failing if the export works without error.
3642 From time to time they still have to be checked using
3643 \begin_inset Flex Code
3646 \begin_layout Plain Layout
3655 \begin_layout Standard
3656 These tests are suspended, because the export fails for known reasons which
3657 cannot ATM be resolved.
3658 But it is expected the reason might disappear in the future.
3659 Be it new TL or better handling in \SpecialChar LyX
3663 \begin_layout Standard
3664 For ctest commands without the
3665 \begin_inset Flex Code
3668 \begin_layout Plain Layout
3674 parameter nothing changes.
3675 Suspended or not, tests will be executed depending only on the selecting
3676 regular expression given to the ctest command (see
3677 \begin_inset CommandInset ref
3679 reference "par:ctest-options"
3686 \begin_layout Paragraph
3687 \begin_inset CommandInset label
3689 name "par:Unreliable-tests"
3696 \begin_layout Standard
3697 Test cases whose name matches a pattern in the file
3698 \begin_inset Flex Code
3701 \begin_layout Plain Layout
3702 development/autotests/unreliableTests
3714 \begin_layout Standard
3715 These tests are not executed using
3716 \begin_inset Flex Code
3719 \begin_layout Plain Layout
3726 \begin_inset Flex Code
3729 \begin_layout Plain Layout
3739 \begin_layout Standard
3740 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3741 or pass but should rather fail (wrong output).
3743 \begin_inset Note Note
3746 \begin_layout Plain Layout
3747 *invalid* tests (wrong output) are not *unreliable*.
3748 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3757 \begin_layout Description
3758 nonstandard Documents with additional requirements, e.g.
3759 a class or package file not in TeXLive.
3761 \begin_inset Note Note
3764 \begin_layout Plain Layout
3765 TODO: rename to "extra"?
3774 \begin_layout Standard
3775 These tests are labeled as
3781 \begin_layout Description
3782 erratic Tests depending on local configuration, OS, TeX distribution, package
3783 versions, or the phase of the moon.
3785 \begin_inset Note Note
3788 \begin_layout Plain Layout
3793 only for the phase-of-moon dependency?
3802 \begin_layout Standard
3803 These tests are labeled as
3809 \begin_layout Description
3811 \begin_inset space ~
3814 output Export does not fail but the resulting document has errors.
3818 \begin_layout Standard
3819 \paragraph_spacing single
3820 \begin_inset Note Note
3823 \begin_layout Plain Layout
3824 \paragraph_spacing single
3825 These tests are actually not
3833 (not measuring what they should measure).
3842 \begin_layout Paragraph
3843 \begin_inset CommandInset label
3845 name "par:Export-test-filtering"
3849 Export test filtering
3852 \begin_layout Standard
3853 The assignment of a label to a test is controlled by a set of files with
3854 regular expressions that are matched against the test names.
3857 \begin_layout Description
3858 ignoredTests (small file)
3859 \begin_inset Newline newline
3862 Tests selected here are withdrawn in the configuration step (cf.
3864 \begin_inset CommandInset ref
3866 reference "par:Configuring-ctests"
3874 \begin_layout Labeling
3875 \labelwidthstring 00.00.0000
3876 Input Test of any export combination
3879 \begin_layout Labeling
3880 \labelwidthstring 00.00.0000
3881 Output Stop if tests not selected here
3885 \begin_layout Description
3886 unreliableTests: Tests selected either pass or fail, but that is dependent
3887 on the system where the test is run.
3888 Selected tests gain the label 'unreliable'.
3892 \begin_layout Labeling
3893 \labelwidthstring 00.00.0000
3894 Input Each test which passed 'ignoredTests'
3897 \begin_layout Labeling
3898 \labelwidthstring 00.00.0000
3899 Output Stop if test selected, gain label 'unreliable'.
3903 \begin_layout Description
3905 \begin_inset space \space{}
3912 \begin_layout Labeling
3913 \labelwidthstring 00.00.0000
3914 Input Each test which passed 'unreliableTests'
3917 \begin_layout Labeling
3918 \labelwidthstring 00.00.0000
3919 Output Stop if not selected.
3922 \begin_layout Standard
3923 The following file is meant as subselections of 'suspiciousTests'.
3924 If neither subselection applies, test gains labels 'export' and 'inverted'
3927 \begin_layout Description
3928 suspendedTests Tests selected here gain the label 'suspended' but _not_
3929 'export' or 'inverted', although in ctest they remain inverted.
3930 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3934 \begin_layout Labeling
3935 \labelwidthstring 00.00.0000
3936 Input Each test selected by 'suspiciousTests'
3939 \begin_layout Labeling
3940 \labelwidthstring 00.00.0000
3941 Output Selected test gains label 'suspended'.
3947 \begin_layout Standard
3948 The following table may clarify label assignement
3951 \begin_layout Standard
3952 \begin_inset Tabular
3953 <lyxtabular version="3" rows="7" columns="12">
3954 <features tabularvalignment="middle">
3955 <column alignment="left" valignment="top" width="0pt">
3956 <column alignment="left" valignment="top" width="0pt">
3957 <column alignment="left" valignment="top" width="0pt">
3958 <column alignment="left" valignment="top" width="0pt">
3959 <column alignment="center" valignment="top">
3960 <column alignment="center" valignment="top">
3961 <column alignment="center" valignment="top">
3962 <column alignment="center" valignment="top">
3963 <column alignment="center" valignment="top">
3964 <column alignment="center" valignment="top">
3965 <column alignment="center" valignment="top">
3966 <column alignment="center" valignment="top">
3968 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3971 \begin_layout Plain Layout
3977 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3980 \begin_layout Plain Layout
3986 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3989 \begin_layout Plain Layout
3995 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3998 \begin_layout Plain Layout
4004 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4007 \begin_layout Plain Layout
4008 Marked in ctest, Assigned label
4013 <cell multicolumn="2" alignment="center" valignment="top" usebox="none">
4016 \begin_layout Plain Layout
4022 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4025 \begin_layout Plain Layout
4031 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4034 \begin_layout Plain Layout
4040 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4043 \begin_layout Plain Layout
4049 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4052 \begin_layout Plain Layout
4058 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4061 \begin_layout Plain Layout
4067 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4070 \begin_layout Plain Layout
4078 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4081 \begin_layout Plain Layout
4087 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4090 \begin_layout Plain Layout
4096 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4099 \begin_layout Plain Layout
4105 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4108 \begin_layout Plain Layout
4114 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4117 \begin_layout Plain Layout
4123 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
4126 \begin_layout Plain Layout
4132 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4135 \begin_layout Plain Layout
4141 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
4144 \begin_layout Plain Layout
4150 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4153 \begin_layout Plain Layout
4159 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
4162 \begin_layout Plain Layout
4168 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4171 \begin_layout Plain Layout
4177 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4180 \begin_layout Plain Layout
4188 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4191 \begin_layout Plain Layout
4197 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4200 \begin_layout Plain Layout
4206 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4209 \begin_layout Plain Layout
4215 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4218 \begin_layout Plain Layout
4224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4227 \begin_layout Plain Layout
4233 <cell alignment="center" valignment="top" topline="true" usebox="none">
4236 \begin_layout Plain Layout
4242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4245 \begin_layout Plain Layout
4251 <cell alignment="center" valignment="top" topline="true" usebox="none">
4254 \begin_layout Plain Layout
4260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4263 \begin_layout Plain Layout
4269 <cell alignment="center" valignment="top" topline="true" usebox="none">
4272 \begin_layout Plain Layout
4278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4281 \begin_layout Plain Layout
4287 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4290 \begin_layout Plain Layout
4298 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4301 \begin_layout Plain Layout
4307 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4310 \begin_layout Plain Layout
4316 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4319 \begin_layout Plain Layout
4325 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4328 \begin_layout Plain Layout
4334 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4337 \begin_layout Plain Layout
4343 <cell alignment="center" valignment="top" topline="true" usebox="none">
4346 \begin_layout Plain Layout
4352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4355 \begin_layout Plain Layout
4361 <cell alignment="center" valignment="top" topline="true" usebox="none">
4364 \begin_layout Plain Layout
4370 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4373 \begin_layout Plain Layout
4379 <cell alignment="center" valignment="top" topline="true" usebox="none">
4382 \begin_layout Plain Layout
4388 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4391 \begin_layout Plain Layout
4397 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4400 \begin_layout Plain Layout
4408 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4411 \begin_layout Plain Layout
4417 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4420 \begin_layout Plain Layout
4426 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4429 \begin_layout Plain Layout
4435 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4438 \begin_layout Plain Layout
4444 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4447 \begin_layout Plain Layout
4453 <cell alignment="center" valignment="top" topline="true" usebox="none">
4456 \begin_layout Plain Layout
4462 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4465 \begin_layout Plain Layout
4471 <cell alignment="center" valignment="top" topline="true" usebox="none">
4474 \begin_layout Plain Layout
4480 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4483 \begin_layout Plain Layout
4489 <cell alignment="center" valignment="top" topline="true" usebox="none">
4492 \begin_layout Plain Layout
4498 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4501 \begin_layout Plain Layout
4507 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4510 \begin_layout Plain Layout
4518 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4521 \begin_layout Plain Layout
4527 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4530 \begin_layout Plain Layout
4536 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4539 \begin_layout Plain Layout
4545 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4548 \begin_layout Plain Layout
4554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4557 \begin_layout Plain Layout
4563 <cell alignment="center" valignment="top" topline="true" usebox="none">
4566 \begin_layout Plain Layout
4572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4575 \begin_layout Plain Layout
4581 <cell alignment="center" valignment="top" topline="true" usebox="none">
4584 \begin_layout Plain Layout
4590 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4593 \begin_layout Plain Layout
4599 <cell alignment="center" valignment="top" topline="true" usebox="none">
4602 \begin_layout Plain Layout
4608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4611 \begin_layout Plain Layout
4617 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4620 \begin_layout Plain Layout
4628 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4631 \begin_layout Plain Layout
4637 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4640 \begin_layout Plain Layout
4646 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4649 \begin_layout Plain Layout
4655 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4658 \begin_layout Plain Layout
4664 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4667 \begin_layout Plain Layout
4673 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4676 \begin_layout Plain Layout
4682 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4685 \begin_layout Plain Layout
4691 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4694 \begin_layout Plain Layout
4700 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4703 \begin_layout Plain Layout
4709 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4712 \begin_layout Plain Layout
4718 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4721 \begin_layout Plain Layout
4727 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4730 \begin_layout Plain Layout
4744 \begin_layout Subsubsection
4748 \begin_layout Standard
4749 These tests check whether a .lyx file loads without any terminal messages.
4750 They correspond to the manual operations of simply opening a .lyx file on
4751 the terminal, exiting LyX once the file is loaded, and then checking whether
4752 there is any output from the terminal.
4753 These tests are useful for catching malformed .lyx files and parsing bugs.
4754 They can also be used to find a .lyx file in which an instance of something
4756 To do this, compile LyX with a local patch that outputs something to the
4757 terminal when an instance is found, and then run the check_load tests to
4758 see if any fail, which would mean that the situation occurs in the LyX
4759 documentation files corresponding to the failed tests.
4760 These tests are expectedly fragile: any LyX diagnostic message, which is
4761 not necessarily an error, would cause the tests to fail.
4762 Similarly, any message output by a library (e.g.
4763 Qt) would also cause failure.
4764 There are some messages that the check_load tests are instructed to ignore,
4765 which are stored in the file
4766 \begin_inset Flex Code
4769 \begin_layout Plain Layout
4770 development/autotests/filterCheckWarnings
4778 \begin_layout Standard
4779 Under cmake, the tests are labeled as 'load'.
4782 \begin_layout Subsubsection
4786 \begin_layout Standard
4787 Automated tests based on the "MonKey Testing" keytest program.
4788 They are documented in the README document in
4789 \begin_inset Flex Code
4792 \begin_layout Plain Layout
4793 development/autotests
4798 subfolder of the \SpecialChar LyX
4799 source code distribution.
4803 \begin_layout Subsubsection
4807 \begin_layout Standard
4808 These tests combine lyx2lyx tests with check_load tests.
4809 They fail if either fails.
4812 \begin_layout Subsubsection
4816 \begin_layout Standard
4817 The URL tests are enabled with the
4818 \begin_inset Flex Code
4821 \begin_layout Plain Layout
4822 -DLYX_ENABLE_URLTESTS=ON
4827 CMake flag and are useful for finding broken links in our documentation
4829 If a URL test fails, to see which link in particular was reported as broken,
4831 \begin_inset Flex Code
4834 \begin_layout Plain Layout
4841 These tests are extremely fragile (e.g.
4842 a test can depend on your Internet connection) and a failed URL test should
4843 not be taken too seriously.
4844 URL tests are labeled as
4849 \begin_layout Paragraph
4853 \begin_layout Standard
4854 cmake is required to run the \SpecialChar LyX
4855 tests, running them is not implemented for
4859 \begin_layout Standard
4860 The appropriate commands are:
4863 \begin_layout Itemize
4869 \begin_inset Newline newline
4872 runs all tests with label
4877 \begin_layout Itemize
4880 ctest -R 'check_.*urls'
4883 \begin_inset Newline newline
4886 runs the tests 'check_accessible_urls'
4889 \begin_layout Standard
4890 Associated test results can be examined in ctest-log directory in files
4891 of the form 'LastFailed.*URLS.log'
4894 \begin_layout Section
4895 Development policies
4898 \begin_layout Standard
4899 This chapter lists some guidelines that should be followed.
4900 This list is not complete, and many guidelines are in separate chapters,
4902 \begin_inset Quotes eld
4905 When is an update of the .lyx file format number needed?
4906 \begin_inset Quotes erd
4910 \begin_inset CommandInset ref
4912 reference "sec:When-is-an"
4919 \begin_layout Subsection
4920 When to set a fixed milestone?
4923 \begin_layout Standard
4924 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
4928 \begin_layout Enumerate
4929 Somebody is actively working on a fix.
4932 \begin_layout Enumerate
4933 The bug is so severe that it would block the release if it is not fixed.
4936 \begin_layout Standard
4937 If a bug is important, but nobody is working on it, and it is no showstopper,
4938 use a milestone like 2.1.x or 2.2.x.
4939 For all other bugs, do not set a milestone at all.
4942 \begin_layout Subsection
4943 Can we add rc entries in stable branch?
4946 \begin_layout Standard
4948 We are supposed to increase the prefs2prefs version number with such things.
4951 \begin_layout Section
4952 Documentation policies
4955 \begin_layout Standard
4956 The main documentation consists of these files:
4959 \begin_layout Description
4960 splash.lyx it is the first file you see after an installation.
4961 We assume that a new user sees this.
4962 It is therefore designed to be as simple as possible.
4963 Therefore please don't add any new formatting, only fix typos etc.
4964 Splash.lyx is up to date for \SpecialChar LyX
4965 2.1.x, currently maintained by Uwe Stöhr.
4968 \begin_layout Description
4969 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
4971 It therefore uses a limited set of formatting.
4972 For example a standard document class.
4973 Since new users will first learn about the formatting possibilities of
4975 please keep this file that simple.
4976 Intro.lyx is up to date for \SpecialChar LyX
4977 2.1.x, currently maintained by Uwe Stöhr.
4980 \begin_layout Description
4981 Tutorial.lyx our tutorial.
4982 It must be always up to date.
4983 Normally there is nothing to add since we don't want to overwhelm new users
4984 with too much details.
4985 The will learn these details while using \SpecialChar LyX
4986 and we have special manuals.
4987 Tutorial.lyx is up to date for \SpecialChar LyX
4988 2.1.x, currently maintained by Uwe Stöhr.
4991 \begin_layout Description
4992 UserGuide.lyx our main user guide.
4993 It covers a mixture of basic and detailed information.
4994 Some information is also in the Math and EmbeddedObjects manual so that
4995 the UserGuide refers to these files.
4996 UserGuide.lyx is up to date for \SpecialChar LyX
4997 2.1.x, currently maintained by Uwe Stöhr.
5000 \begin_layout Description
5001 EmbeddedObjects.lyx a special manual to explain things like tables floats
5004 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5005 2.1.x, currently maintained by Uwe
5009 \begin_layout Description
5010 Math.lyx a special manual to explain everything regarding math in all detail.
5011 Math.lyx is up to date for \SpecialChar LyX
5012 2.1.x, currently maintained by Uwe Stöhr.
5015 \begin_layout Description
5016 Additional.lyx this manual covers information that would be too much detail
5017 for the UserGuide or would make the UserGuide uncompilable or only compilable
5018 when installing a lot of special \SpecialChar LaTeX
5020 What should be in the UserGuide or better in Additional is a matter of
5022 it is up to you to decide that.
5023 Additional.lyx is not completely up to date for \SpecialChar LyX
5026 \begin_inset space ~
5029 8 is up to date and currently maintained by Uwe Stöhr.
5030 It certainly needs a rewrite and update.
5031 For example many info in chapter
5032 \begin_inset space ~
5035 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5039 \begin_layout Description
5040 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5042 output formats, operating systems, languages etc.
5043 It is currently completely out of date and needs a major rewrite and update.
5044 If you do this please assure that your information are given for all OSes
5045 and \SpecialChar LaTeX
5046 distributions (meaning be as objective as possible).
5049 \begin_layout Standard
5051 \begin_inset space ~
5054 rules in editing the docs:
5057 \begin_layout Enumerate
5058 If you are not the maintainer of a doc file or a chapter/section, you MUST
5059 use change tracking so that the maintainer could review your changes
5062 \begin_layout Enumerate
5063 Respect the formatting of the document.
5064 The different files use different formatting styles.
5065 That is OK and has historic reasons nobody fully know ;-).
5066 But it is important to be consistent within one file.
5069 \begin_layout Enumerate
5070 All changes you make to a file in one language MUST also go the file in
5071 the other actively maintained languages.
5072 Normally the maintainer does this for you, if you are the maintainer, you
5073 must do this by copying or changing the changed or added text to the other
5074 files so that the translators sees the blue underlined text and know what
5075 they have to translate and what was changed.
5078 \begin_layout Enumerate
5079 You MUST assure that the document is compilable as
5080 \begin_inset Quotes eld
5084 \begin_inset Quotes erd