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.
208 Whenever there is the danger that a previous version of LyX cannot open
209 a file using the new feature, a file format update is needed.
212 \begin_layout Standard
213 The file format change allows lyx2lyx rules to implement backwards compatibility.
214 Below you can find a list of reasons for file format updates with explanations:
217 \begin_layout Description
226 setting Whenever you introduce a new setting that is stored in the document
227 header, a file format update is needed.
230 \begin_layout Description
239 setting If a certain setting becomes obsolete and gets removed, a file format
243 \begin_layout Description
269 \begin_inset space \thinspace{}
276 \begin_layout Description
277 \paragraph_spacing single
290 package The reason for this is that there is no true ERT inset for math
291 formulas: Each command is parsed, and if a user happens to define a local
292 command with the same name as a command that triggers an automatic load
293 of a package, they need to be able to switch off the automatic loading
295 This switch is stored by the
296 \begin_inset Flex Code
299 \begin_layout Plain Layout
308 \begin_layout Description
313 language that is stored in
314 \begin_inset Flex Code
317 \begin_layout Plain Layout
327 \begin_inset Note Note
330 \begin_layout Plain Layout
331 This requirement is under discussion.
340 \begin_layout Description
345 inset Of course a new inset requires a file format update.
348 \begin_layout Description
353 style If a new style or inset layout is added to any layout file or module
354 shipped with \SpecialChar LyX
355 , then a new file format is needed in the master (development)
357 It is possible to backport new styles to the stable version without a file
360 \begin_inset CommandInset ref
362 reference "subsec:Backporting-new-styles"
366 for more information.
369 \begin_layout Description
374 style If a style or inset layout is removed in any layout file or module
375 shipped with \SpecialChar LyX
376 , a new file format is required.
379 \begin_layout Standard
384 layouts and modules do
388 require a file format update (changed 03/16, see
389 \begin_inset CommandInset ref
391 reference "subsec:New-layouts"
399 \begin_layout Standard
400 If you are still unsure, please ask on the development list.
403 \begin_layout Subsection
404 \begin_inset CommandInset label
406 name "subsec:update_lyx_files"
410 How to update the file format number of .lyx files
413 \begin_layout Standard
414 Once you come to the conclusion that a file format update is needed, you
415 should use the following procedure to perform the update:
418 \begin_layout Enumerate
419 Implement and test the new feature, including the reading and writing of
421 Note that any file produced at this stage does not use a valid format,
422 so do not use this version of \SpecialChar LyX
423 for working on any important documents.
426 \begin_layout Enumerate
427 \begin_inset CommandInset label
429 name "enu:Describe_format"
433 Describe the new format in
434 \begin_inset Flex Code
437 \begin_layout Plain Layout
446 \begin_layout Enumerate
447 Update the \SpecialChar LyX
448 file format number in
449 \begin_inset Flex Code
452 \begin_layout Plain Layout
461 \begin_layout Enumerate
462 Update the range of file formats in the array
463 \begin_inset Flex Code
466 \begin_layout Plain Layout
473 \begin_inset Flex Code
476 \begin_layout Plain Layout
485 \begin_layout Enumerate
486 \begin_inset CommandInset label
488 name "enu:Add-an-entry"
492 Add an entry to both format lists (for conversion and reversion) in
493 \begin_inset Newline newline
497 \begin_inset Flex Code
500 \begin_layout Plain Layout
501 lib/lyx2lyx/lyx_2_3.py
507 Add a conversion routine if needed (e.
508 \begin_inset space \thinspace{}
511 g., a new header setting always needs a conversion that adds the new setting,
512 but a new document language does not need one).
513 Add a reversion routine if needed.
515 \begin_inset Newline newline
518 While the conversion routine is required to produce a document that is equivalen
519 t to the old version, the requirements of the reversion are not that strict.
520 If possible, try to produce a proper reversion, using ERT if needed, but
521 for some features this might be too complicated.
522 In this case, the minimum requirement of the reversion routine is that
523 it produces a valid document which can be read by an older \SpecialChar LyX
525 If absolutely needed, even data loss is allowed for the reversion.
526 (In that case, you might want to add a LyX comment that indicates what
527 you have had to do, so the user is at least warned).
530 \begin_layout Enumerate
531 Since tex2lyx has several implicit file format dependencies caused by sharing
532 code with \SpecialChar LyX
533 , updating the file format of .lyx files produced by tex2lyx at
534 the same time as updating the main .lyx file format is strongly recommended.
535 Therefore, a compiler warning will be issued if the \SpecialChar LyX
536 and tex2lyx .lyx file
537 format numbers differ.
538 In many cases the tex2lyx update requires only the first and last item
543 \begin_layout Enumerate
544 Update the tex2lyx file format number in
545 \begin_inset Flex Code
548 \begin_layout Plain Layout
557 \begin_layout Enumerate
558 If the lyx2lyx conversion from the old to the new format is empty, or if
559 tex2lyx does not yet output the changed feature, you do not need any further
561 Otherwise, search for the changed feature in tex2lyx, and adjust the output
562 according to the lyx2lyx changes.
565 \begin_layout Enumerate
566 Update the tex2lyx test references as described in
567 \begin_inset CommandInset ref
568 LatexCommand formatted
569 reference "sec:Updating-test-references"
577 \begin_layout Enumerate
578 If you did not implement full tex2lyx support for the new feature, add a
580 \begin_inset Flex Code
583 \begin_layout Plain Layout
589 describing the missing bits.
590 Note that it is perfectly fine if you do not add full tex2lyx support for
591 a new feature: The updating recommendation above is only issued for the
592 syntax of the produced .lyx file.
593 It is no problem if some features supported by \SpecialChar LyX
594 are still output as ERT
596 The problems in the past that resulted in the update recommendation were
597 related to mixed version syntax, not ERT.
600 \begin_layout Enumerate
601 It would be nice if you could create a .lyx test file which contains instances
602 of all changed or added features.
603 This could then be used to test lyx2lyx and tex2lyx.
604 Unfortunately, it has not yet been decided how to collect such examples,
605 so please ask on the development list if you want to create one.
608 \begin_layout Enumerate
609 \begin_inset CommandInset label
611 name "enu:updatefiles"
615 Update LyX's .lyx documentation files to the new format.
616 The developer who makes the change knows best what changes to expect when
617 inspecting the resulting diff.
618 Because of this, you might be able to catch a bug in the lyx2lyx code that
619 updates the format just by taking a quick scan through the large diff that
621 \begin_inset Note Note
624 \begin_layout Plain Layout
625 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
626 see which layout update made an unexpected change by looking at the git
627 log of a .lyx file that suffers the problem.
632 To do this, first make sure that there are no changes to the git repository
633 that you will not want to commit (this is needed because it will be convenient
634 to commit with the command
635 \begin_inset Flex Code
638 \begin_layout Plain Layout
645 Then run the following command in the root folder of the source:
646 \begin_inset Flex Code
649 \begin_layout Plain Layout
650 python development/tools/updatedocs.py
656 Look at the resulting changes using the command
657 \begin_inset Flex Code
660 \begin_layout Plain Layout
667 If anything looks surprising, please investigate.
668 Keep in mind that the case of
669 \begin_inset Flex Code
672 \begin_layout Plain Layout
678 is special, because it is first generated with
679 \begin_inset Flex Code
682 \begin_layout Plain Layout
688 before being converted to the latest format.
689 Finally, commit using
690 \begin_inset Flex Code
693 \begin_layout Plain Layout
702 \begin_layout Subsection
703 Updating the file format number of layout files
706 \begin_layout Standard
707 The procedure for updating the layout files is similar to that in step
708 \begin_inset CommandInset ref
710 reference "enu:updatefiles"
715 \begin_inset CommandInset ref
717 reference "subsec:update_lyx_files"
723 \begin_inset Flex Code
726 \begin_layout Plain Layout
727 python development/tools/updatelayouts.py
733 \begin_inset Flex Code
736 \begin_layout Plain Layout
745 \begin_layout Standard
746 Note that we do not automatically any local layout used in the
747 \begin_inset Flex Code
750 \begin_layout Plain Layout
756 files shipped with \SpecialChar LyX
757 because users would then not be able to export to older
759 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
760 to open the file in \SpecialChar LyX
761 2.1.x, there would be an error because the file would
762 contain a local layout whose format is too new.
763 The root reason for this is that we do not support converting layouts to
764 older layout formats, as we do for the
765 \begin_inset Flex Code
768 \begin_layout Plain Layout
777 \begin_layout Subsection
778 Updating the file format number of bind/ui files
781 \begin_layout Standard
782 A change to the functionality of existing LFUNs can require a conversion
784 \begin_inset Flex Code
787 \begin_layout Plain Layout
794 \begin_inset Flex Code
797 \begin_layout Plain Layout
803 files, and therefore an increment of the LFUN format, as well as a conversion
805 \begin_inset Flex Code
808 \begin_layout Plain Layout
815 The latter cannot be done automatically and also requires an update of
819 \begin_inset space \space{}
822 of someone who might have made a set of \SpecialChar LyX
823 teaching manuals for use in their
828 \begin_layout Plain Layout
829 \begin_inset Flex URL
832 \begin_layout Plain Layout
834 http://www.lyx.org/trac/ticket/9794
847 \begin_layout Standard
848 To update the LFUN format:
851 \begin_layout Enumerate
852 Increment the LFUN file format number in
853 \begin_inset Flex Code
856 \begin_layout Plain Layout
865 \begin_layout Enumerate
866 Implement the LFUN conversion in
867 \begin_inset Flex Code
870 \begin_layout Plain Layout
871 lib/scripts/prefs2prefs_lfuns.py
879 \begin_layout Enumerate
881 \begin_inset CommandInset ref
883 reference "enu:updatefiles"
888 \begin_inset CommandInset ref
890 reference "subsec:update_lyx_files"
895 \begin_inset Flex Code
898 \begin_layout Plain Layout
904 command, use this command:
905 \begin_inset Flex Code
908 \begin_layout Plain Layout
909 bash development/tools/updatelfuns.sh
916 \begin_inset Note Note
919 \begin_layout Plain Layout
920 This file should really be converted to python.
928 \begin_layout Enumerate
929 Update Info insets in
930 \begin_inset Flex Code
933 \begin_layout Plain Layout
940 To do so, increment the \SpecialChar LyX
941 format and proceed as in
942 \begin_inset CommandInset ref
944 reference "subsec:update_lyx_files"
949 \begin_inset CommandInset ref
951 reference "enu:Describe_format"
956 \begin_inset CommandInset ref
958 reference "enu:updatefiles"
963 In the lyx2lyx implementation (step
964 \begin_inset CommandInset ref
966 reference "enu:Add-an-entry"
970 ), implement a conversion similar to the one in
971 \begin_inset Flex Code
974 \begin_layout Plain Layout
980 above, as well as a corresponding reversion; for this one can use
981 \begin_inset Flex Code
984 \begin_layout Plain Layout
991 \begin_inset Flex Code
994 \begin_layout Plain Layout
995 lib/lyx2lyx/lyx2lyx_tools.py
1004 \begin_layout Subsection
1005 Backporting new styles to the stable version
1006 \begin_inset CommandInset label
1008 name "subsec:Backporting-new-styles"
1015 \begin_layout Standard
1016 Starting with the stable \SpecialChar LyX
1017 2.1 branch, there is a mechanism in place to backport
1018 new styles to the stable version without the need to update the file format.
1019 The basic idea is that the new style definition is automatically copied
1020 to the document preamble so that it can even be used by older minor versions
1021 that did not yet include the style.
1022 To backport a new style to the stable version, the following steps are
1026 \begin_layout Enumerate
1028 \begin_inset Flex Code
1031 \begin_layout Plain Layout
1037 to the style definition in the development version.
1040 \begin_layout Enumerate
1041 Copy the style definition to the stable version, but use
1042 \begin_inset Flex Code
1045 \begin_layout Plain Layout
1052 If needed adjust the format to the one used by the stable version (see
1053 the customization manual for details of the layout file format).
1056 \begin_layout Enumerate
1057 For each update of the style in a later stable version, increase the argument
1059 \begin_inset Flex Code
1062 \begin_layout Plain Layout
1069 (In the stable version, the development version should not be touched.)
1072 \begin_layout Standard
1073 For details about the
1074 \begin_inset Flex Code
1077 \begin_layout Plain Layout
1083 flag see the customization manual.
1085 \begin_inset Flex Code
1088 \begin_layout Plain Layout
1094 support is needed for backported styles: Since the style of the development
1095 version has an infinite version number, it will always be used.
1096 Furthermore, since its version number is less than one, the style will
1097 not be written anymore to the document header for files saved by the new
1101 \begin_layout Section
1102 New layouts and modules
1105 \begin_layout Standard
1106 \begin_inset Note Greyedout
1109 \begin_layout Description
1110 Note: This section is currently only a proposal under discussion.
1111 Please correct/amend as suited.
1112 Remove this note once a consensus is found.
1115 \begin_layout Plain Layout
1117 \begin_inset Quotes eld
1120 Proposal for a guide on updating layouts
1121 \begin_inset Quotes erd
1124 for details and background
1127 \begin_layout Plain Layout
1128 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1136 \begin_layout Subsection
1137 \begin_inset CommandInset label
1139 name "subsec:New-layouts"
1146 \begin_layout Standard
1147 Adding a new layout file to the \SpecialChar LyX
1149 \begin_inset Quotes eld
1152 officially supported
1153 \begin_inset Quotes erd
1157 You should therefore think carefully about whether you really want to do
1158 this and discuss it on lyx-devel, since you will need to be prepared to
1159 update and fix the layout if necessary.
1160 If the layout is experimental or for a rarely used document class, then
1161 it may be better to add it to the relevant portion of the \SpecialChar LyX
1165 \begin_inset CommandInset href
1167 target "https://wiki.lyx.org/Layouts/Layouts"
1174 \begin_layout Standard
1175 In older versions of this document, it was stated that new layout files
1176 require a file format change.
1177 After some discussion it was decided that this is not needed.
1181 \begin_layout Plain Layout
1183 \begin_inset CommandInset href
1185 name "the thread “Proposal for a guide on updating layouts”"
1186 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1199 For reference, here are the arguments on each side
1203 \begin_layout Description
1205 \begin_inset Quotes eld
1208 New layout files are a file format change
1209 \begin_inset Quotes erd
1215 \begin_layout Itemize
1216 All documents produced by 2.2.
1217 \begin_inset Formula $x$
1220 can always be edited and exported even if
1221 \begin_inset Formula $x$
1225 This is important for people using different machines, or exchanging work
1229 \begin_layout Description
1231 \begin_inset Quotes eld
1234 New layout files are not a file format change
1235 \begin_inset Quotes erd
1241 \begin_layout Itemize
1242 No new LaTeX classes can be supported in a stable version, and stable versions
1243 have a typical lifetime of 2–3 years.
1246 \begin_layout Itemize
1247 We have the same situation already with custom layout files: If a document
1248 using a custom layout file is moved between machines or people, then the
1249 layout file needs to be exchanged as well.
1250 If that is not done, then we have a fallback implemented so that such documents
1251 can still be edited, but not exported, and the user gets a warning.
1255 \begin_layout Itemize
1256 The lyx2lyx script cannot do anything useful in such a case.
1260 \begin_layout Standard
1261 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1263 then, you should do the following:
1266 \begin_layout Enumerate
1267 Put your new layout file in
1268 \begin_inset Flex Code
1271 \begin_layout Plain Layout
1278 \begin_inset Flex Code
1281 \begin_layout Plain Layout
1282 git add lib/layouts/newlayout.layout
1287 ) so that it will be committed.
1290 \begin_layout Enumerate
1292 \begin_inset Flex Code
1295 \begin_layout Plain Layout
1301 , so that the new layout actually gets installed.
1304 \begin_layout Enumerate
1306 \begin_inset Flex Code
1309 \begin_layout Plain Layout
1310 lib/doc/LaTeXConfig.lyx
1315 containing in particular a line like
1323 \begin_layout Standard
1324 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1325 \begin_inset Flex Code
1328 \begin_layout Plain Layout
1329 info-insert textclass <name>
1335 This inset will automatically display a boxed
1336 \begin_inset Quotes eld
1340 \begin_inset Quotes erd
1344 \begin_inset Quotes eld
1348 \begin_inset Quotes erd
1351 depending on the availability of the package.
1355 \begin_layout Enumerate
1356 A template or example is strongly encouraged (but not necessarily required).
1357 It is also possible to provide both.
1359 \begin_inset Flex Code
1362 \begin_layout Plain Layout
1369 \begin_inset Flex Code
1372 \begin_layout Plain Layout
1381 \begin_layout Enumerate
1382 Reconfigure \SpecialChar LyX
1386 \begin_layout Enumerate
1387 Ensure the autotests for the new layout pass (see
1388 \begin_inset CommandInset ref
1390 reference "par:when-to-run-an-export-test"
1397 \begin_layout Subsection
1401 \begin_layout Standard
1402 Adding a new module is very similar to adding a new layout.
1403 Therefore, the previous section applies to new modules as well, with two
1407 \begin_layout Enumerate
1408 You only need to add an entry to
1409 \begin_inset Flex Code
1412 \begin_layout Plain Layout
1413 lib/doc/LaTeXConfig.lyx
1418 if the module requires a LaTeX package.
1419 In that case, the command for entering the InsetInfo is:
1420 \begin_inset Flex Code
1423 \begin_layout Plain Layout
1424 \paragraph_spacing single
1425 info-insert package <name>
1433 \begin_layout Enumerate
1434 Modules do not need a template, only an example, which is strongly encouraged
1435 but not necessarily required.
1438 \begin_layout Subsection
1439 Layouts for document classes with incompatible versions
1442 \begin_layout Standard
1443 Every now and then, there are changes to LaTeX document classes that break
1444 backwards compatibility.
1448 \begin_layout Plain Layout
1449 Uwe has suggested we implement automatic detection of changes in class files.
1450 This could be done by running a script every month that checks if a document
1451 class was changed at CTAN and at the homepages of the scientific journals.
1452 If it reports a change, we can check if our template and layout file are
1453 still usable with the changed document class.
1454 (This is different from the autotests insofar, as this would also catch
1455 changes that do not result in compilation errors.)
1460 Reasons can be a new name for the
1461 \begin_inset Flex Code
1464 \begin_layout Plain Layout
1470 file, removed \SpecialChar LaTeX
1472 How should this best be handled in \SpecialChar LyX
1476 \begin_layout Standard
1477 The idea is to support the new version with a new \SpecialChar LyX
1481 \begin_layout Itemize
1482 Existing documents can still be opened in \SpecialChar LyX
1483 and will continue to work on
1484 systems where the old version is still installed.
1488 \begin_layout Itemize
1489 With differently named
1490 \begin_inset Flex Code
1493 \begin_layout Plain Layout
1499 files, \SpecialChar LyX
1500 can check for the availability of the particular version and reflect
1502 Different document class versions with the same file name are currently
1503 (2.2.x) not detected by the configuration script.
1504 This is planned for 2.3.
1508 \begin_layout Plain Layout
1509 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1512 \begin_layout Plain Layout
1513 However, what we really need is version detection for the configuration,
1514 so that the user can be warned if the required class file has the wrong
1516 (If the class file keeps the name over the version change, only one of
1517 the two layout files generates compilable documents.)
1520 \begin_layout Plain Layout
1521 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1530 \begin_layout Itemize
1531 The new layout can be added both to the master and the stable branches,
1532 in accord with the policy discussed in
1533 \begin_inset CommandInset ref
1534 LatexCommand formatted
1535 reference "subsec:New-layouts"
1540 No lyx2lyx conversion is then required when a new major version is released.
1543 \begin_layout Standard
1544 The user can move an existing document to the new version simply by selecting
1545 a new document class.
1546 This step is well supported by \SpecialChar LyX
1547 , with established methods for handling
1548 unsupported styles and other changes.
1549 This way, no lyx2lyx code is required.
1552 \begin_layout Standard
1553 The steps to support a new version of an existing document class are thus:
1556 \begin_layout Itemize
1557 Create a new layout file including the upstream version in the name (avoid
1558 special characters like spaces and dots), e.g.
1560 \begin_inset Flex Code
1563 \begin_layout Plain Layout
1564 acmsiggraph-v0-92.layout
1572 \begin_layout Itemize
1573 Include the name of the
1574 \begin_inset Flex Code
1577 \begin_layout Plain Layout
1583 file as an optional argument in the
1584 \begin_inset Flex Code
1587 \begin_layout Plain Layout
1595 line and include the version number in the GUI name:
1596 \begin_inset Newline newline
1600 \begin_inset Flex Code
1603 \begin_layout Plain Layout
1606 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1607 \begin_inset space ~
1618 \begin_layout Itemize
1619 Update the GUI name in the old layout file (whose name should not be changed),
1621 \begin_inset Newline newline
1625 \begin_inset Flex Code
1628 \begin_layout Plain Layout
1631 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1632 \begin_inset space ~
1643 \begin_layout Itemize
1644 To avoid duplicate definitions, the new layout can
1645 \begin_inset Flex Code
1648 \begin_layout Plain Layout
1654 the old layout file and add\SpecialChar breakableslash
1655 remove\SpecialChar breakableslash
1656 obsolete\SpecialChar breakableslash
1657 modify settings and styles (similar
1659 \begin_inset Flex Code
1662 \begin_layout Plain Layout
1672 \begin_layout Standard
1673 It may be tempting to let the new layout be the
1674 \begin_inset Quotes eld
1678 \begin_inset Quotes erd
1681 and have the old layout import it.
1682 However, this should not be done because any changes to the new layout
1683 would need undo steps in the importing old layout.
1687 \begin_layout Itemize
1688 If the new LaTeX document class obsoletes the old one, update the example
1689 and template files to use the new layout.
1690 Add a note about the changes (preferably with a pointer to the documentation
1695 \begin_layout Standard
1696 This way, new documents based on the template or example will use the up-to-date
1697 document class version.
1701 \begin_layout Standard
1702 \begin_inset Newpage newpage
1708 \begin_layout Section
1712 \begin_layout Standard
1713 Automated tests are an important tool to detect bugs and regressions in
1714 software development.
1715 Some projects like gcc even require each bug fix to be accompanied by a
1716 test case for the automatic test suite, that would detect this bug.
1717 Testing interactive features automatically is of course very hard, but
1718 core functionality like document import and export can be tested quite
1719 easily, and some tests of this kind exist.
1722 \begin_layout Subsection
1726 \begin_layout Standard
1727 There are attempts to set up a suite of unit tests for LyX.
1730 \begin_layout Standard
1731 TODO: describe what is done and what is still to do.
1734 \begin_layout Subsection
1738 \begin_layout Standard
1739 The tex2lyx tests are located in the
1740 \begin_inset Flex Code
1743 \begin_layout Plain Layout
1749 subfolder of the \SpecialChar LyX
1750 source code distribution.
1751 The actual testing is performed by the simple python script
1752 \begin_inset Flex Code
1755 \begin_layout Plain Layout
1756 src/tex2lyx/test/runtests.py
1762 Each test consists of two files:
1763 \begin_inset Flex Code
1766 \begin_layout Plain Layout
1772 contains the \SpecialChar LaTeX
1773 code that should be tested.
1775 \begin_inset Flex Code
1778 \begin_layout Plain Layout
1784 contains the expected output of tex2lyx.
1785 When a test is run, the actual produced output is compared with the stored
1787 The test passes if both are identical.
1788 The test machinery is also able to generate a file
1789 \begin_inset Flex Code
1792 \begin_layout Plain Layout
1798 by exporting the produced .lyx file with \SpecialChar LyX
1800 This may be useful for roundtrip comparisons.
1803 \begin_layout Subsubsection
1807 \begin_layout Standard
1808 The tex2lyx tests can be run in several ways.
1810 \begin_inset Flex Code
1813 \begin_layout Plain Layout
1819 subfolder of the build directory, the commands
1820 \begin_inset Flex Code
1823 \begin_layout Plain Layout
1829 (cmake, all platforms),
1830 \begin_inset Flex Code
1833 \begin_layout Plain Layout
1839 (cmake, when using a make based build system and not MSVC) or
1840 \begin_inset Flex Code
1843 \begin_layout Plain Layout
1849 (autotools) will run the tex2lyx tests.
1850 Alternatively, in the root of the build directory, the command
1851 \begin_inset Flex Code
1854 \begin_layout Plain Layout
1860 runs all tests whose names match the regex
1861 \begin_inset Quotes eld
1865 \begin_inset Quotes erd
1869 Another way to run the tex2lyx tests in the root build directory is to
1870 instead use the command
1871 \begin_inset Flex Code
1874 \begin_layout Plain Layout
1875 ctest -L '(cmplyx|roundtrip)'
1880 , which runs all tests categorized with the label
1881 \begin_inset Quotes eld
1885 \begin_inset Quotes erd
1889 \begin_inset Quotes eld
1893 \begin_inset Quotes erd
1897 If a test fails, the differences between the expected and actual results
1898 are output in unified diff format.
1901 \begin_layout Subsubsection
1902 Updating test references
1903 \begin_inset CommandInset label
1905 name "sec:Updating-test-references"
1912 \begin_layout Standard
1913 In some cases a changed tex2lyx output is not a test failure, but wanted,
1915 \begin_inset space \thinspace{}
1919 \begin_inset space \space{}
1922 if a tex2lyx bug was fixed, or a new feature was added.
1923 In these cases the stored references need to be updated.
1924 To do so if using autotools, call
1925 \begin_inset Flex Code
1928 \begin_layout Plain Layout
1935 \begin_inset Flex Code
1938 \begin_layout Plain Layout
1944 subdirectory of the build directory.
1945 If instead using CMake, call
1946 \begin_inset Flex Code
1949 \begin_layout Plain Layout
1950 make updatetex2lyxtests
1955 in the build directory or in the
1956 \begin_inset Flex Code
1959 \begin_layout Plain Layout
1965 subdirectory of the build directory.
1969 \begin_layout Plain Layout
1970 Note that this is a case where a make target in the build directory can
1971 affect the source directory, which might not be advisable.
1976 On Windows do the following:
1979 \begin_layout Itemize
1980 Assure that the path to the python.exe is in your system PATH variable.
1983 \begin_layout Itemize
1984 Double-click on the file
1985 \begin_inset Flex Code
1988 \begin_layout Plain Layout
1989 updatetex2lyxtests.vcxproj
1994 in the build directory or in the
1995 \begin_inset Flex Code
1998 \begin_layout Plain Layout
2004 subdirectory of your build directory.
2007 \begin_layout Itemize
2008 In the appearing MSVC program right-click on the project
2012 in the project explorer and chose
2019 \begin_layout Standard
2020 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2022 Please examine the changed output carefully before committing the changed
2023 files to the repository: Since the test machinery does not do a roundtrip
2025 \begin_inset Formula $\Rightarrow$
2029 \begin_inset Formula $\Rightarrow$
2032 .tex, and does not compare the produced dvi or pdf output, it assumes that
2033 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2035 There is only one chance to detect wrong output: before committing a new
2037 Once it is committed, it is quite difficult to verify whether it is correct.
2040 \begin_layout Standard
2045 update the test references by opening them with \SpecialChar LyX
2046 or directly running lyx2lyx
2048 This would not work, since lyx2lyx and \SpecialChar LyX
2049 produce slightly different files
2050 regarding insignificant whitespace and line breaks.
2053 \begin_layout Subsubsection
2057 \begin_layout Standard
2058 In many cases tests for new features may be added to one of the existing
2059 test files, but sometimes this is not possible or not wanted.
2060 Then a new test file needs to be added:
2063 \begin_layout Enumerate
2065 \begin_inset Flex Code
2068 \begin_layout Plain Layout
2069 src/tex2lyx/test/<test name>.tex
2074 and run tex2lyx in roundtrip mode to produce the file
2075 \begin_inset Flex Code
2078 \begin_layout Plain Layout
2079 src/tex2lyx/test/<test name>.lyx.lyx
2085 This file will be the new reference.
2088 \begin_layout Enumerate
2089 Once you confirmed that the tex2lyx output is correct, add the new files
2090 to the corresponding lists in
2091 \begin_inset Flex Code
2094 \begin_layout Plain Layout
2095 src/tex2lyx/test/runtests.py
2101 \begin_inset Flex Code
2104 \begin_layout Plain Layout
2105 src/tex2lyx/Makefile.am
2111 \begin_inset Flex Code
2114 \begin_layout Plain Layout
2115 src/tex2lyx/test/CMakeLists.txt
2123 \begin_layout Enumerate
2124 Commit the changes to the repository, or send a patch to the development
2125 list and ask for committing if you do not have commit rights.
2128 \begin_layout Subsection
2129 ctest automatic tests
2132 \begin_layout Standard
2133 Some tests are located in the
2134 \begin_inset Flex Code
2137 \begin_layout Plain Layout
2138 development/autotests/
2143 subfolder of the \SpecialChar LyX
2144 source code distribution.
2149 \begin_layout Plain Layout
2150 The README document in this folder only describes the
2151 \begin_inset Quotes eld
2155 \begin_inset Quotes erd
2158 subset of autotests!
2166 \begin_layout Standard
2167 These tests can be run by the commands
2168 \begin_inset Flex Code
2171 \begin_layout Plain Layout
2181 (all platforms) or (when using a make based build system and not MSVC)
2183 \begin_inset Flex Code
2186 \begin_layout Plain Layout
2193 \begin_inset Flex Code
2196 \begin_layout Plain Layout
2207 The test logs are written to the
2208 \begin_inset Flex Code
2211 \begin_layout Plain Layout
2225 \begin_layout Subsubsection
2229 \begin_layout Standard
2230 The export tests are integration tests.
2231 They take longer to run and are more likely to break than the tex2lyx tests.
2232 Nevertheless, they have caught many regressions and without a better alternativ
2233 e it is important to keep them up-to-date and understand how they work.
2236 \begin_layout Standard
2238 \begin_inset Quotes eld
2242 \begin_inset Quotes erd
2245 documentation, template, and example documents.
2246 In addition, there are a number of dedicated sample documents in the
2247 \begin_inset Flex Code
2250 \begin_layout Plain Layout
2256 subfolder of the \SpecialChar LyX
2257 source code distribution.
2258 All samples are (after copying and eventual processing by scripts) exported
2259 to various output formats via the
2260 \begin_inset Flex Code
2263 \begin_layout Plain Layout
2269 command line option.
2270 The tests checks for errors reported by LyX.
2271 (However, error-free export is no guarantee for an error-free output document.)
2274 \begin_layout Paragraph
2275 \begin_inset CommandInset label
2277 name "par:when-to-run-an-export-test"
2281 Expectations of LyX developers
2284 \begin_layout Standard
2285 Because the export tests are integration tests and take a long time to run,
2286 LyX developers are rarely expected to run all of the tests.
2287 Here are some good practices to follow by developers:
2290 \begin_layout Itemize
2291 When making a non-trivial change to a .layout file, run the export and layout
2292 tests corresponding with that .layout file.
2295 \begin_layout Itemize
2296 When making non-trivial changes to a .lyx file, run the export tests correspondin
2297 g to that .lyx file.
2302 \begin_layout Plain Layout
2303 This rule is due to revision.
2307 \begin_layout Plain Layout
2308 There is an objection from the documentation maintainer that working on
2309 the documentation must not be complicated by having to consider non-standard
2313 \begin_layout Itemize
2314 successful compiling/testing an edited documentation file with pdflatex
2315 suffices to ensure it can be commited, not tests with other exports are
2319 \begin_layout Plain Layout
2320 If sudden failures with other exports due to “half-tested” documentation
2321 updates are a problem for the test maintainer, the test suite should use
2325 \begin_layout Itemize
2326 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2329 \begin_layout Itemize
2330 updated regularely (but on a time chosen by the test suite maintainer) from
2331 the originals in lib/doc/
2334 \begin_layout Plain Layout
2338 \begin_layout Itemize
2339 no test will fail due to ongoing work on documentation,
2342 \begin_layout Itemize
2343 the documentation is still tested in full (with some delay),
2346 \begin_layout Itemize
2347 failures with non-default export can be examined and handled accordingly
2348 in one run with the cache update,
2351 \begin_layout Itemize
2352 “interesting failures” (like the nested-language+polyglossia problem in
2353 es/Customization can be separated and moved into dedicated test samples.
2361 \begin_layout Itemize
2362 When making non-trivial changes to LyX's \SpecialChar LaTeX
2364 touching the encoding code or package handling code that you expect will
2365 change the exported \SpecialChar LaTeX
2370 \begin_layout Standard
2371 \paragraph_spacing single
2372 Consider running all of the export tests before and after your change.
2373 If there are differences, please reconcile these (i.e.
2374 fix the bug or fix the tests)
2379 Ask for help if you're not sure what to.
2382 \begin_layout Standard
2383 If you do not want to run the tests,
2386 \begin_layout Itemize
2387 post the patch on the list and others will run the tests and eventually
2391 \begin_layout Itemize
2392 commit, but be prepared to fix eventually arising problems or to revert
2393 the commit if there is no easy fix.
2397 \begin_layout Itemize
2398 Understand how to interpret test failures.
2399 If your commit is found to have broken a test, you should be able to interpret
2400 the test results when made aware of them.
2402 \begin_inset CommandInset ref
2404 reference "subsec:Interpreting-export-tests"
2411 \begin_layout Paragraph
2412 \begin_inset CommandInset label
2414 name "par:export-test-output-formats"
2421 \begin_layout Standard
2422 The following output formats are currently tested for each sample document
2424 \begin_inset CommandInset ref
2426 reference "par:Export-test-filtering"
2433 \begin_layout Labeling
2434 \labelwidthstring 00.00.0000
2439 \begin_layout Labeling
2440 \labelwidthstring 00.00.0000
2441 lyx16 LyX 1.6 file format (lyx2lyx)
2444 \begin_layout Labeling
2445 \labelwidthstring 00.00.0000
2446 lyx21 LyX 2.1 file format (lyx2lyx)
2449 \begin_layout Labeling
2450 \labelwidthstring 00.00.0000
2451 xhtml LyXHTML (native LyX HTML export)
2455 \begin_layout Labeling
2456 \labelwidthstring 00.00.0000
2458 \begin_inset space ~
2462 \begin_inset space ~
2469 \begin_layout Labeling
2470 \labelwidthstring pdf5msystemFM
2471 dvi DVI (8-bit latex)
2474 \begin_layout Labeling
2475 \labelwidthstring pdf5msystemFM
2476 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2479 \begin_layout Labeling
2480 \labelwidthstring pdf5msystemFM
2481 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2484 \begin_layout Labeling
2485 \labelwidthstring pdf5msystemFM
2489 \begin_layout Labeling
2490 \labelwidthstring pdf5msystemFM
2491 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2494 \begin_layout Labeling
2495 \labelwidthstring pdf5msystemFM
2496 pdf4_systemF PDF (XeTeX with Unicode fonts)
2499 \begin_layout Labeling
2500 \labelwidthstring pdf5msystemFM
2501 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2504 \begin_layout Labeling
2505 \labelwidthstring pdf5msystemFM
2506 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2510 \begin_layout Labeling
2511 \labelwidthstring 00.00.0000
2513 \begin_inset space ~
2517 \begin_inset space ~
2521 \begin_inset space ~
2525 \begin_inset space ~
2532 \begin_layout Labeling
2533 \labelwidthstring pdf5msystemFM
2534 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2537 \begin_layout Labeling
2538 \labelwidthstring pdf5msystemFM
2539 pdf3 DVI -> PDF (dvipdfm)
2543 \begin_layout Labeling
2544 \labelwidthstring 00.00.0000
2546 \begin_inset space ~
2549 tested: (or only if set as default output format in the document source)
2553 \begin_layout Labeling
2554 \labelwidthstring pdf5msystemFM
2558 \begin_layout Labeling
2559 \labelwidthstring pdf5msystemFM
2560 luatex LaTeX (LuaTeX)
2563 \begin_layout Labeling
2564 \labelwidthstring pdf5msystemFM
2565 dviluatex LaTeX (dviluatex)
2568 \begin_layout Labeling
2569 \labelwidthstring pdf5msystemFM
2570 pdflatex LaTeX (pdflatex)
2573 \begin_layout Labeling
2574 \labelwidthstring pdf5msystemFM
2575 platex LaTeX (pLaTeX)
2578 \begin_layout Labeling
2579 \labelwidthstring pdf5msystemFM
2583 \begin_layout Labeling
2584 \labelwidthstring pdf5msystemFM
2585 eps3 EPS (encapsulated Postscript) (cropped)
2588 \begin_layout Labeling
2589 \labelwidthstring pdf5msystemFM
2590 ps DVI -> Postscript (dvips)
2593 \begin_layout Labeling
2594 \labelwidthstring pdf5msystemFM
2598 \begin_layout Labeling
2599 \labelwidthstring pdf5msystemFM
2600 text (nor text2, ..., text4)
2603 \begin_layout Labeling
2604 \labelwidthstring pdf5msystemFM
2608 \begin_layout Labeling
2609 \labelwidthstring pdf5msystemFM
2613 \begin_layout Labeling
2614 \labelwidthstring pdf5msystemFM
2618 \begin_layout Labeling
2619 \labelwidthstring pdf5msystemFM
2624 \begin_layout Paragraph
2625 \begin_inset CommandInset label
2627 name "par:Configuring-ctests"
2631 Configuring the tests
2634 \begin_layout Standard
2635 To enable the export autotests, add the
2636 \begin_inset Flex Code
2639 \begin_layout Plain Layout
2640 -DLYX_ENABLE_EXPORT_TESTS=ON
2649 \begin_layout Standard
2650 \begin_inset Flex Code
2653 \begin_layout Plain Layout
2654 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2662 \begin_layout Standard
2664 This flag will increase the time for the cmake command by several seconds,
2665 mainly because of the process of inverting tests (see Section
2666 \begin_inset CommandInset ref
2668 reference "subsec:Interpreting-export-tests"
2675 \begin_layout Paragraph
2676 \begin_inset CommandInset label
2678 name "par:ctest-options"
2685 \begin_layout Standard
2686 To run all tests, in the build directory simply run the command
2687 \begin_inset Flex Code
2690 \begin_layout Plain Layout
2697 A full, up-to-date TeXLive installation is recommended to run the tests.
2698 Otherwise, some tests will fail.
2699 Tests with additional requirements are labeled
2700 \begin_inset Quotes eld
2703 unreliable:nonstandard
2704 \begin_inset Quotes erd
2711 \begin_layout Standard
2712 To run only some of the tests, use command line options (see examples below):
2715 \begin_layout Labeling
2716 \labelwidthstring -R
2717 \begin_inset Flex Code
2720 \begin_layout Plain Layout
2726 Run only the tests whose names match the given regular expression.
2729 \begin_layout Labeling
2730 \labelwidthstring -R
2731 \begin_inset Flex Code
2734 \begin_layout Plain Layout
2740 Run only the tests whose labels match the given regular expression.
2741 A test may have more that one label.
2745 \begin_layout Labeling
2746 \labelwidthstring -R
2747 \begin_inset Flex Code
2750 \begin_layout Plain Layout
2756 Exclude the tests whose names match the given regular expression.
2759 \begin_layout Labeling
2760 \labelwidthstring -R
2761 \begin_inset Flex Code
2764 \begin_layout Plain Layout
2770 Exclude the tests whose labels match the given regular expression.
2771 Cannot be combined with
2772 \begin_inset Flex Code
2775 \begin_layout Plain Layout
2784 \begin_layout Standard
2785 The following options help to find good selection patterns:
2788 \begin_layout Labeling
2789 \labelwidthstring -R
2790 \begin_inset Flex Code
2793 \begin_layout Plain Layout
2799 List the tests that would be run but not actually run them.
2804 \begin_layout Standard
2805 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2806 to know how many tests there are or whether your
2807 \begin_inset Flex Code
2810 \begin_layout Plain Layout
2816 regular expression did what you expected.
2820 \begin_layout Labeling
2821 \labelwidthstring -R
2822 \begin_inset Flex Code
2825 \begin_layout Plain Layout
2826 \SpecialChar nobreakdash
2827 \SpecialChar nobreakdash
2833 print the list of all labels associated with the test set.
2834 Can also be combined with -R, -L, -E, ...
2838 \begin_layout Standard
2839 Other useful options are:
2842 \begin_layout Labeling
2843 \labelwidthstring -R
2844 \begin_inset Flex Code
2847 \begin_layout Plain Layout
2853 Run the tests in parallel using the given number of jobs.
2857 \begin_layout Standard
2858 We are still working on getting the tests to run in parallel.
2859 However, when running the tests in parallel, sometimes tests fail that
2860 pass when run sequentially.
2861 A reasonable approach is to first run the tests in parallel and then run
2862 the failed tests sequentially.
2865 \begin_layout Standard
2866 For example, to run 8 jobs at a time:
2869 \begin_layout Standard
2870 \begin_inset Flex Code
2873 \begin_layout Plain Layout
2882 \begin_layout Standard
2883 \begin_inset Flex Code
2886 \begin_layout Plain Layout
2887 ctest \SpecialChar nobreakdash
2888 \SpecialChar nobreakdash
2897 \begin_layout Standard
2898 When specifying a subset of the tests (e.g.
2900 \begin_inset Flex Code
2903 \begin_layout Plain Layout
2904 \SpecialChar nobreakdash
2910 ), the same subset must be specified when using the
2911 \begin_inset Flex Code
2914 \begin_layout Plain Layout
2915 \SpecialChar nobreakdash
2916 \SpecialChar nobreakdash
2922 option because it is the test numbers that are used to index which tests
2923 failed on the previous run.
2926 \begin_layout Standard
2928 Note that some tests cannot be run in parallel.
2929 These tests are marked in the code with the
2930 \begin_inset Flex Code
2933 \begin_layout Plain Layout
2944 \begin_layout Labeling
2945 \labelwidthstring -R
2946 \begin_inset Flex Code
2949 \begin_layout Plain Layout
2950 \SpecialChar nobreakdash
2951 \SpecialChar nobreakdash
2957 Set a global timeout on all tests that do not already have a timeout set
2962 \begin_layout Standard
2963 There have been bugs in LyX and in \SpecialChar LaTeX
2964 which cause compilation to hang, and
2965 without a timeout a test might never stop (in one case there was even a
2967 If a test times out, the
2968 \begin_inset Flex Code
2971 \begin_layout Plain Layout
2977 command exits with error, but you can distinguish between a timed out test
2978 and a failed test in the output reported at the end of the
2979 \begin_inset Flex Code
2982 \begin_layout Plain Layout
2992 \begin_layout Standard
2994 \begin_inset Flex Code
2997 \begin_layout Plain Layout
3003 ) the full list of command line options.
3006 \begin_layout Paragraph
3010 \begin_layout Itemize
3011 run only the export tests:
3012 \begin_inset Flex Code
3015 \begin_layout Plain Layout
3024 \begin_layout Itemize
3026 \begin_inset Flex Code
3029 \begin_layout Plain Layout
3030 ctest -L "inverted|suspended"
3038 \begin_layout Itemize
3039 list all export tests which match any of the labelling patterns:
3040 \begin_inset Flex Code
3043 \begin_layout Plain Layout
3054 \begin_layout Itemize
3055 exclude rarely used output formats and post-processing tests
3056 \begin_inset Flex Code
3059 \begin_layout Plain Layout
3060 ctest -L export -E "_(texF|dvi3|pdf3?)"
3068 \begin_layout Paragraph
3069 \begin_inset CommandInset label
3071 name "subsec:Interpreting-export-tests"
3075 Interpreting the export test results
3078 \begin_layout Standard
3079 A test can fail for several reasons, not all of them bad.
3082 \begin_layout Enumerate
3083 A new or edited sample document may be incompatible with some output formats.
3086 \begin_layout Enumerate
3087 A dependency is not met (e.g.
3088 the \SpecialChar LaTeX
3090 One hint that this is the case is that the corresponding
3091 \begin_inset Flex Code
3094 \begin_layout Plain Layout
3100 test will likely also fail.
3103 \begin_layout Enumerate
3104 An inverted test fails to fail (i.e.
3105 export that previously failed now works).
3108 \begin_layout Enumerate
3109 An external dependency was updated (e.g.
3114 \begin_layout Enumerate
3115 A recent code change introduced a bug.
3118 \begin_layout Enumerate
3119 \begin_inset CommandInset label
3125 A change in a document exposed a previously unknown bug or an incompatibility
3126 with an export format (e.g.
3127 Lua\SpecialChar LaTeX
3131 \begin_layout Standard
3132 Because the .lyx files are exported in several formats, it is not surprising
3133 that many of the exports fail.
3134 This expectation of failure is addressed by
3135 \begin_inset Quotes eld
3139 \begin_inset Quotes erd
3142 the tests, that is, by marking the test as
3143 \begin_inset Quotes eld
3147 \begin_inset Quotes erd
3150 if the export exits with error and as
3151 \begin_inset Quotes eld
3155 \begin_inset Quotes erd
3158 if the export succeeds
3163 It follows that these expected failures will not show up as failed tests
3164 in the test results and thus will not pollute the
3165 \begin_inset Quotes eld
3169 \begin_inset Quotes erd
3173 If the export actually succeeds, then the test will fail.
3174 The purpose of this failure is to get your attention—something has changed,
3175 possibly for the better.
3178 \begin_layout Standard
3179 We try to document why a test is inverted or ignored.
3180 See the comment (prefixed with
3181 \begin_inset Flex Code
3184 \begin_layout Plain Layout
3190 ) above the block in which the test is listed as inverted or ignored in
3192 \begin_inset Flex Code
3195 \begin_layout Plain Layout
3196 development/autotests/suspiciousTests
3202 \begin_inset Flex Code
3205 \begin_layout Plain Layout
3206 development/autotests/unreliableTests
3212 \begin_inset Flex Code
3215 \begin_layout Plain Layout
3216 development/autotests/ignoredTests
3225 \begin_layout Standard
3226 A good question is why do we enable the tests for non-default formats? The
3227 answer is that if a non-default route is broken it is often because a bug
3228 was introduced in LyX and not because a document-specific change was made
3229 that is not supported by the route.
3230 In other words, there is a high signal/noise ratio in the export tests
3231 for some non-default formats.
3235 \begin_layout Standard
3236 When a test or several tests fail, consider checking the files in the
3237 \begin_inset Flex Code
3240 \begin_layout Plain Layout
3246 subdirectory of your build directory.
3247 In this subdirectory are three files: the file
3248 \begin_inset Flex Code
3251 \begin_layout Plain Layout
3257 simply lists the tests that failed on your last
3258 \begin_inset Flex Code
3261 \begin_layout Plain Layout
3268 \begin_inset Flex Code
3271 \begin_layout Plain Layout
3277 file contains the output from the tests (and often has details explaining
3278 why a test failed); and the
3279 \begin_inset Flex Code
3282 \begin_layout Plain Layout
3288 file lists the times that it took to run the tests.
3291 \begin_layout Paragraph
3292 What action should you take if a test fails?
3295 \begin_layout Standard
3296 \paragraph_spacing single
3297 It is always good to check manually why something fails and if it passes
3298 if the PDF output is good.
3301 \begin_layout Itemize
3302 Generally, if a change breaks compilation for the target format (for the
3303 manuals pdf2) without solving some important other issue,
3305 fix or revert the commit
3307 that led to failure.
3310 \begin_layout Itemize
3311 If it is not possible to (immediately) fix the failure but there are reasons
3312 not to revert the commit (e.g.
3313 it fixes another more important issue),
3317 the failing test case (see
3318 \begin_inset CommandInset ref
3320 reference "par:Inverted-tests"
3327 \begin_layout Itemize
3332 test case fails because the export now works,
3336 the test by removing the labeling pattern from
3337 \begin_inset Quotes eld
3341 \begin_inset Quotes erd
3345 \begin_inset CommandInset ref
3347 reference "par:Inverted-tests"
3354 \begin_layout Itemize
3355 If the export did not fail previously but led to wrong output (PDF, say),
3356 it is in fact an improvement when the test now fails, label it as
3357 \begin_inset Quotes eld
3360 unreliable:wrong:output
3361 \begin_inset Quotes erd
3365 \begin_inset CommandInset ref
3367 reference "par:Unreliable-tests"
3374 \begin_layout Itemize
3375 In case of tests failing due to missing requirements (when only a subset
3376 of TeXLive is installed or a test labeled
3377 \begin_inset Quotes eld
3380 unreliable:nonstandard
3381 \begin_inset Quotes erd
3384 fails), ignore the failure, ask for someone else to run the test, or install
3385 the missing ressources and try again.
3388 \begin_layout Paragraph
3389 \begin_inset CommandInset label
3391 name "par:Inverted-tests"
3398 \begin_layout Standard
3399 Test cases whose name matches a pattern in the file
3400 \begin_inset Flex Code
3403 \begin_layout Plain Layout
3404 development/autotests/suspiciousTests
3414 They get also the test property
3415 \begin_inset Flex Code
3418 \begin_layout Plain Layout
3425 they are reported as failing if the export works without error
3426 \begin_inset Flex URL
3429 \begin_layout Plain Layout
3431 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3439 \begin_layout Standard
3440 Add failing cases to this file, if they cannot be solved
3441 \begin_inset Quotes eld
3445 \begin_inset Quotes erd
3448 but it is expected that the export will work in a foreseeable future, e.g.
3449 low priority issues like failures to export to a non-target format (for
3450 the manuals everything except pdf2).
3453 \begin_layout Standard
3454 The following sublabels are currently present in
3455 \begin_inset Flex Code
3458 \begin_layout Plain Layout
3467 \begin_layout Description
3468 todo test failures that require attention:
3472 \begin_layout Itemize
3473 minor issues to explore and properly sort later,
3476 \begin_layout Itemize
3480 \begin_layout Itemize
3481 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3485 \begin_layout Description
3486 lyxbugs LyX bugs with a Trac number.
3489 \begin_layout Description
3490 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3494 \begin_layout Standard
3495 "Wontfix" if demonstrating correct use and OK in the default output format.
3499 \begin_layout Description
3500 texissues Export fails due to LaTeX limitations like non-ASCII characters
3501 in verbatim or listings, incompatible packages, ...
3505 \begin_layout Standard
3506 "Wontfix" if documents demonstrate correct use in the default output format:
3509 \begin_layout Itemize
3510 If the source can be made more robust without becoming "hackish", fix the
3514 \begin_layout Itemize
3515 if LyX could be enhanced to care for a permanent TeX limitation, file a
3516 ticket at trac and add a pattern under lyxbugs,
3519 \begin_layout Itemize
3520 otherwise, add a pattern here.
3524 \begin_layout Description
3525 attic Documents in the attic.
3526 (Kept for reference and format conversion test.)
3529 \begin_layout Subparagraph
3533 \begin_layout Standard
3534 Test cases whose name additionally matches a pattern in the file
3535 \begin_inset Flex Code
3538 \begin_layout Plain Layout
3539 development/autotests/suspendedTests
3557 This means they are not executed using
3558 \begin_inset Flex Code
3561 \begin_layout Plain Layout
3568 \begin_inset Flex Code
3571 \begin_layout Plain Layout
3578 However, they also get the test property
3579 \begin_inset Flex Code
3582 \begin_layout Plain Layout
3589 they are reported as failing if the export works without error.
3590 From time to time they still have to be checked using
3591 \begin_inset Flex Code
3594 \begin_layout Plain Layout
3603 \begin_layout Standard
3604 These tests are suspended, because the export fails for known reasons which
3605 cannot ATM be resolved.
3606 But it is expected the reason might disappear in the future.
3607 Be it new TL or better handling in \SpecialChar LyX
3611 \begin_layout Standard
3612 For ctest commands without the
3613 \begin_inset Flex Code
3616 \begin_layout Plain Layout
3622 parameter nothing changes.
3623 Suspended or not, tests will be executed depending only on the selecting
3624 regular expression given to the ctest command (see
3625 \begin_inset CommandInset ref
3627 reference "par:ctest-options"
3634 \begin_layout Paragraph
3635 \begin_inset CommandInset label
3637 name "par:Unreliable-tests"
3644 \begin_layout Standard
3645 Test cases whose name matches a pattern in the file
3646 \begin_inset Flex Code
3649 \begin_layout Plain Layout
3650 development/autotests/unreliableTests
3662 \begin_layout Standard
3663 These tests are not executed using
3664 \begin_inset Flex Code
3667 \begin_layout Plain Layout
3674 \begin_inset Flex Code
3677 \begin_layout Plain Layout
3687 \begin_layout Standard
3688 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3689 or pass but should rather fail (wrong output).
3691 \begin_inset Note Note
3694 \begin_layout Plain Layout
3695 *invalid* tests (wrong output) are not *unreliable*.
3696 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3705 \begin_layout Description
3706 nonstandard Documents with additional requirements, e.g.
3707 a class or package file not in TeXLive.
3709 \begin_inset Note Note
3712 \begin_layout Plain Layout
3713 TODO: rename to "extra"?
3722 \begin_layout Standard
3723 These tests are labeled as
3729 \begin_layout Description
3730 erratic Tests depending on local configuration, OS, TeX distribution, package
3731 versions, or the phase of the moon.
3733 \begin_inset Note Note
3736 \begin_layout Plain Layout
3741 only for the phase-of-moon dependency?
3750 \begin_layout Standard
3751 These tests are labeled as
3757 \begin_layout Description
3759 \begin_inset space ~
3762 output Export does not fail but the resulting document has errors.
3766 \begin_layout Standard
3767 \paragraph_spacing single
3768 \begin_inset Note Note
3771 \begin_layout Plain Layout
3772 \paragraph_spacing single
3773 These tests are actually not
3781 (not measuring what they should measure).
3790 \begin_layout Paragraph
3791 \begin_inset CommandInset label
3793 name "par:Export-test-filtering"
3797 Export test filtering
3800 \begin_layout Standard
3801 The assignment of a label to a test is controlled by a set of files with
3802 regular expressions that are matched against the test names.
3805 \begin_layout Description
3806 ignoredTests (small file)
3807 \begin_inset Newline newline
3810 Tests selected here are withdrawn in the configuration step (cf.
3812 \begin_inset CommandInset ref
3814 reference "par:Configuring-ctests"
3822 \begin_layout Labeling
3823 \labelwidthstring 00.00.0000
3824 Input Test of any export combination
3827 \begin_layout Labeling
3828 \labelwidthstring 00.00.0000
3829 Output Stop if tests not selected here
3833 \begin_layout Description
3834 unreliableTests: Tests selected either pass or fail, but that is dependent
3835 on the system where the test is run.
3836 Selected tests gain the label 'unreliable'.
3840 \begin_layout Labeling
3841 \labelwidthstring 00.00.0000
3842 Input Each test which passed 'ignoredTests'
3845 \begin_layout Labeling
3846 \labelwidthstring 00.00.0000
3847 Output Stop if test selected, gain label 'unreliable'.
3851 \begin_layout Description
3853 \begin_inset space \space{}
3860 \begin_layout Labeling
3861 \labelwidthstring 00.00.0000
3862 Input Each test which passed 'unreliableTests'
3865 \begin_layout Labeling
3866 \labelwidthstring 00.00.0000
3867 Output Stop if not selected.
3870 \begin_layout Standard
3871 The following file is meant as subselections of 'suspiciousTests'.
3872 If neither subselection applies, test gains labels 'export' and 'inverted'
3875 \begin_layout Description
3876 suspendedTests Tests selected here gain the label 'suspended' but _not_
3877 'export' or 'inverted', although in ctest they remain inverted.
3878 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3882 \begin_layout Labeling
3883 \labelwidthstring 00.00.0000
3884 Input Each test selected by 'suspiciousTests'
3887 \begin_layout Labeling
3888 \labelwidthstring 00.00.0000
3889 Output Selected test gains label 'suspended'.
3895 \begin_layout Standard
3896 The following table may clarify label assignement
3899 \begin_layout Standard
3900 \begin_inset Tabular
3901 <lyxtabular version="3" rows="7" columns="12">
3902 <features tabularvalignment="middle">
3903 <column alignment="left" valignment="top" width="0pt">
3904 <column alignment="left" valignment="top" width="0pt">
3905 <column alignment="left" valignment="top" width="0pt">
3906 <column alignment="left" valignment="top" width="0pt">
3907 <column alignment="center" valignment="top">
3908 <column alignment="center" valignment="top">
3909 <column alignment="center" valignment="top">
3910 <column alignment="center" valignment="top">
3911 <column alignment="center" valignment="top">
3912 <column alignment="center" valignment="top">
3913 <column alignment="center" valignment="top">
3914 <column alignment="center" valignment="top">
3916 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3919 \begin_layout Plain Layout
3925 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3928 \begin_layout Plain Layout
3934 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3937 \begin_layout Plain Layout
3943 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3946 \begin_layout Plain Layout
3952 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3955 \begin_layout Plain Layout
3956 Marked in ctest, Assigned label
3961 <cell multicolumn="2" alignment="center" valignment="top" usebox="none">
3964 \begin_layout Plain Layout
3970 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3973 \begin_layout Plain Layout
3979 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3982 \begin_layout Plain Layout
3988 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3991 \begin_layout Plain Layout
3997 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4000 \begin_layout Plain Layout
4006 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4009 \begin_layout Plain Layout
4015 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4018 \begin_layout Plain Layout
4026 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4029 \begin_layout Plain Layout
4035 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4038 \begin_layout Plain Layout
4044 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4047 \begin_layout Plain Layout
4053 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4056 \begin_layout Plain Layout
4062 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4065 \begin_layout Plain Layout
4071 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
4074 \begin_layout Plain Layout
4080 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4083 \begin_layout Plain Layout
4089 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
4092 \begin_layout Plain Layout
4098 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4101 \begin_layout Plain Layout
4107 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
4110 \begin_layout Plain Layout
4116 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4119 \begin_layout Plain Layout
4125 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4128 \begin_layout Plain Layout
4136 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4139 \begin_layout Plain Layout
4145 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4148 \begin_layout Plain Layout
4154 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4157 \begin_layout Plain Layout
4163 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4166 \begin_layout Plain Layout
4172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4175 \begin_layout Plain Layout
4181 <cell alignment="center" valignment="top" topline="true" usebox="none">
4184 \begin_layout Plain Layout
4190 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4193 \begin_layout Plain Layout
4199 <cell alignment="center" valignment="top" topline="true" usebox="none">
4202 \begin_layout Plain Layout
4208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4211 \begin_layout Plain Layout
4217 <cell alignment="center" valignment="top" topline="true" usebox="none">
4220 \begin_layout Plain Layout
4226 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4229 \begin_layout Plain Layout
4235 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4238 \begin_layout Plain Layout
4246 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4249 \begin_layout Plain Layout
4255 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4258 \begin_layout Plain Layout
4264 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4267 \begin_layout Plain Layout
4273 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4276 \begin_layout Plain Layout
4282 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4285 \begin_layout Plain Layout
4291 <cell alignment="center" valignment="top" topline="true" usebox="none">
4294 \begin_layout Plain Layout
4300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4303 \begin_layout Plain Layout
4309 <cell alignment="center" valignment="top" topline="true" usebox="none">
4312 \begin_layout Plain Layout
4318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4321 \begin_layout Plain Layout
4327 <cell alignment="center" valignment="top" topline="true" usebox="none">
4330 \begin_layout Plain Layout
4336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4339 \begin_layout Plain Layout
4345 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4348 \begin_layout Plain Layout
4356 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4359 \begin_layout Plain Layout
4365 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4368 \begin_layout Plain Layout
4374 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4377 \begin_layout Plain Layout
4383 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4386 \begin_layout Plain Layout
4392 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4395 \begin_layout Plain Layout
4401 <cell alignment="center" valignment="top" topline="true" usebox="none">
4404 \begin_layout Plain Layout
4410 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4413 \begin_layout Plain Layout
4419 <cell alignment="center" valignment="top" topline="true" usebox="none">
4422 \begin_layout Plain Layout
4428 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4431 \begin_layout Plain Layout
4437 <cell alignment="center" valignment="top" topline="true" usebox="none">
4440 \begin_layout Plain Layout
4446 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4449 \begin_layout Plain Layout
4455 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4458 \begin_layout Plain Layout
4466 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4469 \begin_layout Plain Layout
4475 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4478 \begin_layout Plain Layout
4484 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4487 \begin_layout Plain Layout
4493 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4496 \begin_layout Plain Layout
4502 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4505 \begin_layout Plain Layout
4511 <cell alignment="center" valignment="top" topline="true" usebox="none">
4514 \begin_layout Plain Layout
4520 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4523 \begin_layout Plain Layout
4529 <cell alignment="center" valignment="top" topline="true" usebox="none">
4532 \begin_layout Plain Layout
4538 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4541 \begin_layout Plain Layout
4547 <cell alignment="center" valignment="top" topline="true" usebox="none">
4550 \begin_layout Plain Layout
4556 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4559 \begin_layout Plain Layout
4565 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4568 \begin_layout Plain Layout
4576 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4579 \begin_layout Plain Layout
4585 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4588 \begin_layout Plain Layout
4594 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4597 \begin_layout Plain Layout
4603 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4606 \begin_layout Plain Layout
4612 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4615 \begin_layout Plain Layout
4621 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4624 \begin_layout Plain Layout
4630 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4633 \begin_layout Plain Layout
4639 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4642 \begin_layout Plain Layout
4648 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4651 \begin_layout Plain Layout
4657 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4660 \begin_layout Plain Layout
4666 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4669 \begin_layout Plain Layout
4675 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4678 \begin_layout Plain Layout
4692 \begin_layout Subsubsection
4696 \begin_layout Standard
4697 These tests check whether a .lyx file loads without any terminal messages.
4698 They correspond to the manual operations of simply opening a .lyx file on
4699 the terminal, exiting LyX once the file is loaded, and then checking whether
4700 there is any output from the terminal.
4701 These tests are useful for catching malformed .lyx files and parsing bugs.
4702 They can also be used to find a .lyx file in which an instance of something
4704 To do this, compile LyX with a local patch that outputs something to the
4705 terminal when an instance is found, and then run the check_load tests to
4706 see if any fail, which would mean that the situation occurs in the LyX
4707 documentation files corresponding to the failed tests.
4708 These tests are expectedly fragile: any LyX diagnostic message, which is
4709 not necessarily an error, would cause the tests to fail.
4710 Similarly, any message output by a library (e.g.
4711 Qt) would also cause failure.
4712 There are some messages that the check_load tests are instructed to ignore,
4713 which are stored in the file
4714 \begin_inset Flex Code
4717 \begin_layout Plain Layout
4718 development/autotests/filterCheckWarnings
4726 \begin_layout Standard
4727 Under cmake, the tests are labeled as 'load'.
4730 \begin_layout Subsubsection
4734 \begin_layout Standard
4735 Automated tests based on the "MonKey Testing" keytest program.
4736 They are documented in the README document in
4737 \begin_inset Flex Code
4740 \begin_layout Plain Layout
4741 development/autotests
4746 subfolder of the \SpecialChar LyX
4747 source code distribution.
4750 \begin_layout Subsubsection
4754 \begin_layout Standard
4755 These tests combine lyx2lyx tests with check_load tests.
4756 They fail if either fails.
4759 \begin_layout Subsubsection
4763 \begin_layout Standard
4764 The URL tests are enabled with the
4765 \begin_inset Flex Code
4768 \begin_layout Plain Layout
4769 -DLYX_ENABLE_URLTESTS=ON
4774 CMake flag and are useful for finding broken links in our documentation
4776 If a URL test fails, to see which link in particular was reported as broken,
4778 \begin_inset Flex Code
4781 \begin_layout Plain Layout
4788 These tests are extremely fragile (e.g.
4789 a test can depend on your Internet connection) and a failed URL test should
4790 not be taken too seriously.
4791 URL tests are labeled as
4796 \begin_layout Paragraph
4800 \begin_layout Standard
4801 cmake is required to run the \SpecialChar LyX
4802 tests, running them is not implemented for
4806 \begin_layout Standard
4807 The appropriate commands are:
4810 \begin_layout Itemize
4816 \begin_inset Newline newline
4819 runs all tests with label
4824 \begin_layout Itemize
4827 ctest -R 'check_.*urls'
4830 \begin_inset Newline newline
4833 runs the tests 'check_accessible_urls'
4836 \begin_layout Standard
4837 Associated test results can be examined in ctest-log directory in files
4838 of the form 'LastFailed.*URLS.log'
4841 \begin_layout Section
4842 Development policies
4845 \begin_layout Standard
4846 This chapter lists some guidelines that should be followed.
4847 This list is not complete, and many guidelines are in separate chapters,
4849 \begin_inset Quotes eld
4852 When is an update of the .lyx file format number needed?
4853 \begin_inset Quotes erd
4857 \begin_inset CommandInset ref
4859 reference "sec:When-is-an"
4866 \begin_layout Subsection
4867 When to set a fixed milestone?
4870 \begin_layout Standard
4871 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
4875 \begin_layout Enumerate
4876 Somebody is actively working on a fix.
4879 \begin_layout Enumerate
4880 The bug is so severe that it would block the release if it is not fixed.
4883 \begin_layout Standard
4884 If a bug is important, but nobody is working on it, and it is no showstopper,
4885 use a milestone like 2.1.x or 2.2.x.
4886 For all other bugs, do not set a milestone at all.
4889 \begin_layout Subsection
4890 Can we add rc entries in stable branch?
4893 \begin_layout Standard
4895 We are supposed to increase the prefs2prefs version number with such things.
4898 \begin_layout Section
4899 Documentation policies
4902 \begin_layout Standard
4903 The main documentation consists of these files:
4906 \begin_layout Description
4907 splash.lyx it is the first file you see after an installation.
4908 We assume that a new user sees this.
4909 It is therefore designed to be as simple as possible.
4910 Therefore please don't add any new formatting, only fix typos etc.
4911 Splash.lyx is up to date for \SpecialChar LyX
4912 2.1.x, currently maintained by Uwe Stöhr.
4915 \begin_layout Description
4916 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
4918 It therefore uses a limited set of formatting.
4919 For example a standard document class.
4920 Since new users will first learn about the formatting possibilities of
4922 please keep this file that simple.
4923 Intro.lyx is up to date for \SpecialChar LyX
4924 2.1.x, currently maintained by Uwe Stöhr.
4927 \begin_layout Description
4928 Tutorial.lyx our tutorial.
4929 It must be always up to date.
4930 Normally there is nothing to add since we don't want to overwhelm new users
4931 with too much details.
4932 The will learn these details while using \SpecialChar LyX
4933 and we have special manuals.
4934 Tutorial.lyx is up to date for \SpecialChar LyX
4935 2.1.x, currently maintained by Uwe Stöhr.
4938 \begin_layout Description
4939 UserGuide.lyx our main user guide.
4940 It covers a mixture of basic and detailed information.
4941 Some information is also in the Math and EmbeddedObjects manual so that
4942 the UserGuide refers to these files.
4943 UserGuide.lyx is up to date for \SpecialChar LyX
4944 2.1.x, currently maintained by Uwe Stöhr.
4947 \begin_layout Description
4948 EmbeddedObjects.lyx a special manual to explain things like tables floats
4951 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
4952 2.1.x, currently maintained by Uwe
4956 \begin_layout Description
4957 Math.lyx a special manual to explain everything regarding math in all detail.
4958 Math.lyx is up to date for \SpecialChar LyX
4959 2.1.x, currently maintained by Uwe Stöhr.
4962 \begin_layout Description
4963 Additional.lyx this manual covers information that would be too much detail
4964 for the UserGuide or would make the UserGuide uncompilable or only compilable
4965 when installing a lot of special \SpecialChar LaTeX
4967 What should be in the UserGuide or better in Additional is a matter of
4969 it is up to you to decide that.
4970 Additional.lyx is not completely up to date for \SpecialChar LyX
4973 \begin_inset space ~
4976 8 is up to date and currently maintained by Uwe Stöhr.
4977 It certainly needs a rewrite and update.
4978 For example many info in chapter
4979 \begin_inset space ~
4982 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
4986 \begin_layout Description
4987 Customization.lyx this manual covers information how to customize \SpecialChar LyX
4989 output formats, operating systems, languages etc.
4990 It is currently completely out of date and needs a major rewrite and update.
4991 If you do this please assure that your information are given for all OSes
4992 and \SpecialChar LaTeX
4993 distributions (meaning be as objective as possible).
4996 \begin_layout Standard
4998 \begin_inset space ~
5001 rules in editing the docs:
5004 \begin_layout Enumerate
5005 If you are not the maintainer of a doc file or a chapter/section, you MUST
5006 use change tracking so that the maintainer could review your changes
5009 \begin_layout Enumerate
5010 Respect the formatting of the document.
5011 The different files use different formatting styles.
5012 That is OK and has historic reasons nobody fully know ;-).
5013 But it is important to be consistent within one file.
5016 \begin_layout Enumerate
5017 All changes you make to a file in one language MUST also go the file in
5018 the other actively maintained languages.
5019 Normally the maintainer does this for you, if you are the maintainer, you
5020 must do this by copying or changing the changed or added text to the other
5021 files so that the translators sees the blue underlined text and know what
5022 they have to translate and what was changed.
5025 \begin_layout Enumerate
5026 You MUST assure that the document is compilable as
5027 \begin_inset Quotes eld
5031 \begin_inset Quotes erd