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.
204 Below you can find a list of reasons for file format updates with explanations:
207 \begin_layout Description
216 setting Whenever you introduce a new setting that is stored in the document
217 header, a file format update is needed.
218 This is also true if you add a new valid value to an existing setting,
220 \begin_inset space \thinspace{}
224 \begin_inset space \space{}
227 a new language that is stored in
228 \begin_inset Flex Code
231 \begin_layout Plain Layout
242 \begin_layout Description
251 setting If a certain setting becomes obsolete and gets removed, a file format
255 \begin_layout Description
260 inset Of course a new inset requires a file format update.
263 \begin_layout Description
268 style If a new style or inset layout is added to any layout file or module
269 shipped with \SpecialChar LyX
270 , then a new file format is needed in the master (development)
272 It is possible to backport new styles to the stable version without a file
275 \begin_inset CommandInset ref
277 reference "subsec:Backporting-new-styles"
281 for more information.
284 \begin_layout Description
289 style If a style or inset layout is removed in any layout file or module
290 shipped with \SpecialChar LyX
291 , then a new file format is required.
294 \begin_layout Description
307 package Any new math package that is automatically loaded needs a file format
309 The reason for this is that there is no true ERT inset for math formulas:
310 Each command is parsed, and if a user happens to define a local command
311 with the same name as a command that triggers an automatic load of a package,
312 they need to be able to switch off the automatic loading of that package.
313 This switch is stored by the
314 \begin_inset Flex Code
317 \begin_layout Plain Layout
326 \begin_layout Standard
327 If you are still unsure, please ask on the development list.
330 \begin_layout Subsection
331 \begin_inset CommandInset label
333 name "subsec:update_lyx_files"
337 How to update the file format number of .lyx files
340 \begin_layout Standard
341 Once you come to the conclusion that a file format update is needed, you
342 should use the following procedure to perform the update:
345 \begin_layout Enumerate
346 Implement and test the new feature, including the reading and writing of
348 Note that any file produced at this stage does not use a valid format,
349 so do not use this version of \SpecialChar LyX
350 for working on any important documents.
353 \begin_layout Enumerate
354 \begin_inset CommandInset label
356 name "enu:Describe_format"
360 Describe the new format in
361 \begin_inset Flex Code
364 \begin_layout Plain Layout
373 \begin_layout Enumerate
374 Update the \SpecialChar LyX
375 file format number in
376 \begin_inset Flex Code
379 \begin_layout Plain Layout
388 \begin_layout Enumerate
389 Update the range of file formats in the array
390 \begin_inset Flex Code
393 \begin_layout Plain Layout
400 \begin_inset Flex Code
403 \begin_layout Plain Layout
412 \begin_layout Enumerate
413 \begin_inset CommandInset label
415 name "enu:Add-an-entry"
419 Add an entry to both format lists (for conversion and reversion) in
420 \begin_inset Newline newline
424 \begin_inset Flex Code
427 \begin_layout Plain Layout
428 lib/lyx2lyx/lyx_2_3.py
434 Add a conversion routine if needed (e.
435 \begin_inset space \thinspace{}
438 g., a new header setting always needs a conversion that adds the new setting,
439 but a new document language does not need one).
440 Add a reversion routine if needed.
442 \begin_inset Newline newline
445 While the conversion routine is required to produce a document that is equivalen
446 t to the old version, the requirements of the reversion are not that strict.
447 If possible, try to produce a proper reversion, using ERT if needed, but
448 for some features this might be too complicated.
449 In this case, the minimum requirement of the reversion routine is that
450 it produces a valid document which can be read by an older \SpecialChar LyX
452 If absolutely needed, even data loss is allowed for the reversion.
453 (In that case, you might want to add a LyX comment that indicates what
454 you have had to do, so the user is at least warned).
457 \begin_layout Enumerate
458 Since tex2lyx has several implicit file format dependencies caused by sharing
459 code with \SpecialChar LyX
460 , updating the file format of .lyx files produced by tex2lyx at
461 the same time as updating the main .lyx file format is strongly recommended.
462 Therefore, a compiler warning will be issued if the \SpecialChar LyX
463 and tex2lyx .lyx file
464 format numbers differ.
465 In many cases the tex2lyx update requires only the first and last item
470 \begin_layout Enumerate
471 Update the tex2lyx file format number in
472 \begin_inset Flex Code
475 \begin_layout Plain Layout
484 \begin_layout Enumerate
485 If the lyx2lyx conversion from the old to the new format is empty, or if
486 tex2lyx does not yet output the changed feature, you do not need any further
488 Otherwise, search for the changed feature in tex2lyx, and adjust the output
489 according to the lyx2lyx changes.
492 \begin_layout Enumerate
493 Update the tex2lyx test references as described in
494 \begin_inset CommandInset ref
495 LatexCommand formatted
496 reference "sec:Updating-test-references"
504 \begin_layout Enumerate
505 If you did not implement full tex2lyx support for the new feature, add a
507 \begin_inset Flex Code
510 \begin_layout Plain Layout
516 describing the missing bits.
517 Note that it is perfectly fine if you do not add full tex2lyx support for
518 a new feature: The updating recommendation above is only issued for the
519 syntax of the produced .lyx file.
520 It is no problem if some features supported by \SpecialChar LyX
521 are still output as ERT
523 The problems in the past that resulted in the update recommendation were
524 related to mixed version syntax, not ERT.
527 \begin_layout Enumerate
528 It would be nice if you could create a .lyx test file which contains instances
529 of all changed or added features.
530 This could then be used to test lyx2lyx and tex2lyx.
531 Unfortunately, it has not yet been decided how to collect such examples,
532 so please ask on the development list if you want to create one.
535 \begin_layout Enumerate
536 \begin_inset CommandInset label
538 name "enu:updatefiles"
542 Update LyX's .lyx documentation files to the new format.
543 The developer who makes the change knows best what changes to expect when
544 inspecting the resulting diff.
545 Because of this, you might be able to catch a bug in the lyx2lyx code that
546 updates the format just by taking a quick scan through the large diff that
548 \begin_inset Note Note
551 \begin_layout Plain Layout
552 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
553 see which layout update made an unexpected change by looking at the git
554 log of a .lyx file that suffers the problem.
559 To do this, first make sure that there are no changes to the git repository
560 that you will not want to commit (this is needed because it will be convenient
561 to commit with the command
562 \begin_inset Flex Code
565 \begin_layout Plain Layout
572 Then run the following command in the root folder of the source:
573 \begin_inset Flex Code
576 \begin_layout Plain Layout
577 python development/tools/updatedocs.py
583 Look at the resulting changes using the command
584 \begin_inset Flex Code
587 \begin_layout Plain Layout
594 If anything looks surprising, please investigate.
595 Keep in mind that the case of
596 \begin_inset Flex Code
599 \begin_layout Plain Layout
605 is special, because it is first generated with
606 \begin_inset Flex Code
609 \begin_layout Plain Layout
615 before being converted to the latest format.
616 Finally, commit using
617 \begin_inset Flex Code
620 \begin_layout Plain Layout
629 \begin_layout Subsection
630 Updating the file format number of layout files
633 \begin_layout Standard
634 The procedure for updating the layout files is similar to that in step
635 \begin_inset CommandInset ref
637 reference "enu:updatefiles"
642 \begin_inset CommandInset ref
644 reference "subsec:update_lyx_files"
650 \begin_inset Flex Code
653 \begin_layout Plain Layout
654 python development/tools/updatelayouts.py
660 \begin_inset Flex Code
663 \begin_layout Plain Layout
672 \begin_layout Standard
673 Note that we do not automatically any local layout used in the
674 \begin_inset Flex Code
677 \begin_layout Plain Layout
683 files shipped with \SpecialChar LyX
684 because users would then not be able to export to older
686 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
687 to open the file in \SpecialChar LyX
688 2.1.x, there would be an error because the file would
689 contain a local layout whose format is too new.
690 The root reason for this is that we do not support converting layouts to
691 older layout formats, as we do for the
692 \begin_inset Flex Code
695 \begin_layout Plain Layout
704 \begin_layout Subsection
705 Updating the file format number of bind/ui files
708 \begin_layout Standard
709 A change to the functionality of existing LFUNs can require a conversion
711 \begin_inset Flex Code
714 \begin_layout Plain Layout
721 \begin_inset Flex Code
724 \begin_layout Plain Layout
730 files, and therefore an increment of the LFUN format, as well as a conversion
732 \begin_inset Flex Code
735 \begin_layout Plain Layout
742 The latter cannot be done automatically and also requires an update of
746 \begin_inset space \space{}
749 of someone who might have made a set of \SpecialChar LyX
750 teaching manuals for use in their
755 \begin_layout Plain Layout
756 \begin_inset Flex URL
759 \begin_layout Plain Layout
761 http://www.lyx.org/trac/ticket/9794
774 \begin_layout Standard
775 To update the LFUN format:
778 \begin_layout Enumerate
779 Increment the LFUN file format number in
780 \begin_inset Flex Code
783 \begin_layout Plain Layout
792 \begin_layout Enumerate
793 Implement the LFUN conversion in
794 \begin_inset Flex Code
797 \begin_layout Plain Layout
798 lib/scripts/prefs2prefs_lfuns.py
806 \begin_layout Enumerate
808 \begin_inset CommandInset ref
810 reference "enu:updatefiles"
815 \begin_inset CommandInset ref
817 reference "subsec:update_lyx_files"
822 \begin_inset Flex Code
825 \begin_layout Plain Layout
831 command, use this command:
832 \begin_inset Flex Code
835 \begin_layout Plain Layout
836 bash development/tools/updatelfuns.sh
843 \begin_inset Note Note
846 \begin_layout Plain Layout
847 This file should really be converted to python.
855 \begin_layout Enumerate
856 Update Info insets in
857 \begin_inset Flex Code
860 \begin_layout Plain Layout
867 To do so, increment the \SpecialChar LyX
868 format and proceed as in
869 \begin_inset CommandInset ref
871 reference "subsec:update_lyx_files"
876 \begin_inset CommandInset ref
878 reference "enu:Describe_format"
883 \begin_inset CommandInset ref
885 reference "enu:updatefiles"
890 In the lyx2lyx implementation (step
891 \begin_inset CommandInset ref
893 reference "enu:Add-an-entry"
897 ), implement a conversion similar to the one in
898 \begin_inset Flex Code
901 \begin_layout Plain Layout
907 above, as well as a corresponding reversion; for this one can use
908 \begin_inset Flex Code
911 \begin_layout Plain Layout
918 \begin_inset Flex Code
921 \begin_layout Plain Layout
922 lib/lyx2lyx/lyx2lyx_tools.py
931 \begin_layout Subsection
932 Backporting new styles to the stable version
933 \begin_inset CommandInset label
935 name "subsec:Backporting-new-styles"
942 \begin_layout Standard
943 Starting with the stable \SpecialChar LyX
944 2.1 branch, there is a mechanism in place to backport
945 new styles to the stable version without the need to update the file format.
946 The basic idea is that the new style definition is automatically copied
947 to the document preamble so that it can even be used by older minor versions
948 that did not yet include the style.
949 To backport a new style to the stable version, the following steps are
953 \begin_layout Enumerate
955 \begin_inset Flex Code
958 \begin_layout Plain Layout
964 to the style definition in the development version.
967 \begin_layout Enumerate
968 Copy the style definition to the stable version, but use
969 \begin_inset Flex Code
972 \begin_layout Plain Layout
979 If needed adjust the format to the one used by the stable version (see
980 the customization manual for details of the layout file format).
983 \begin_layout Enumerate
984 For each update of the style in a later stable version, increase the argument
986 \begin_inset Flex Code
989 \begin_layout Plain Layout
996 (In the stable version, the development version should not be touched.)
999 \begin_layout Standard
1000 For details about the
1001 \begin_inset Flex Code
1004 \begin_layout Plain Layout
1010 flag see the customization manual.
1012 \begin_inset Flex Code
1015 \begin_layout Plain Layout
1021 support is needed for backported styles: Since the style of the development
1022 version has an infinite version number, it will always be used.
1023 Furthermore, since its version number is less than one, the style will
1024 not be written anymore to the document header for files saved by the new
1028 \begin_layout Section
1029 New layouts and modules
1032 \begin_layout Standard
1033 \begin_inset Note Greyedout
1036 \begin_layout Description
1037 Note: This section is currently only a proposal under discussion.
1038 Please correct/amend as suited.
1039 Remove this note once a consensus is found.
1042 \begin_layout Plain Layout
1043 Summary of a recent discussion in lyx-devel by GM.
1046 \begin_layout Plain Layout
1048 \begin_inset Quotes eld
1051 Proposal for a guide on updating layouts
1052 \begin_inset Quotes erd
1055 for details and background
1058 \begin_layout Plain Layout
1059 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1067 \begin_layout Subsection
1068 \begin_inset CommandInset label
1070 name "subsec:New-layouts"
1077 \begin_layout Standard
1078 Adding a new layout file to the \SpecialChar LyX
1080 \begin_inset Quotes eld
1083 officially supported
1084 \begin_inset Quotes erd
1088 You should therefore think carefully about whether you really want to do
1089 this and discuss it on lyx-devel, since you will need to be prepared to
1090 update and fix the layout if necessary.
1091 If the layout is experimental or for a rarely used document class, then
1092 it may be better to add it to the relevant portion of the \SpecialChar LyX
1096 \begin_inset CommandInset href
1098 target "https://wiki.lyx.org/Layouts/Layouts"
1105 \begin_layout Standard
1106 In older versions of this document, it was stated that new layout files
1107 require a file format change.
1108 After some discussion it was decided that this is not needed.
1109 For reference, here are the arguments on each side:
1113 \begin_layout Plain Layout
1115 \begin_inset CommandInset href
1118 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1130 \begin_layout Description
1132 \begin_inset Quotes eld
1135 New layout files are a file format change
1136 \begin_inset Quotes erd
1142 \begin_layout Itemize
1143 All documents produced by 2.2.x can always be edited and exported even if
1145 This is important for people using different machines, or exchanging work
1149 \begin_layout Description
1151 \begin_inset Quotes eld
1154 New layout files are not a file format change
1155 \begin_inset Quotes erd
1161 \begin_layout Itemize
1162 No new LaTeX classes can be supported in a stable version, and stable versions
1163 have a typical lifetime of 2–3 years.
1166 \begin_layout Itemize
1167 We have the same situation already with custom layout files: If a document
1168 using a custom layout file is moved between machines or people, then the
1169 layout file needs to be exchanged as well.
1170 If that is not done, then we have a fallback implemented so that such documents
1171 can still be edited, but not exported, and the user gets a warning.
1175 \begin_layout Itemize
1176 The lyx2lyx script cannot do anything useful on backward conversion in such
1177 a case, and the forward conversion would be a no-op.
1180 \begin_layout Standard
1181 As said, consensus has been reached that the reasons in favor of not requiring
1182 a file format change are more compelling.
1185 \begin_layout Standard
1186 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1188 then, you should do the following:
1191 \begin_layout Enumerate
1192 Put your new layout file in
1193 \begin_inset Flex Code
1196 \begin_layout Plain Layout
1203 \begin_inset Flex Code
1206 \begin_layout Plain Layout
1207 git add lib/layouts/newlayout.layout
1212 ) so that it will be committed.
1215 \begin_layout Enumerate
1217 \begin_inset Flex Code
1220 \begin_layout Plain Layout
1226 , so that the new layout actually gets installed.
1229 \begin_layout Enumerate
1231 \begin_inset Flex Code
1234 \begin_layout Plain Layout
1235 lib/doc/LaTeXConfig.lyx
1240 containing in particular a line like
1248 \begin_layout Standard
1249 \paragraph_spacing single
1250 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1251 \begin_inset Flex Code
1254 \begin_layout Plain Layout
1255 \paragraph_spacing single
1256 info-insert textclass <name>
1262 This inset will automatically display a boxed
1263 \begin_inset Quotes eld
1267 \begin_inset Quotes erd
1271 \begin_inset Quotes eld
1275 \begin_inset Quotes erd
1278 depending on the availability of the package.
1282 \begin_layout Enumerate
1283 Add a template or example file to
1284 \begin_inset Flex Code
1287 \begin_layout Plain Layout
1294 \begin_inset Flex Code
1297 \begin_layout Plain Layout
1306 \begin_layout Enumerate
1307 Reconfigure \SpecialChar LyX
1311 \begin_layout Enumerate
1312 Ensure the autotests for the new layout pass (see
1313 \begin_inset CommandInset ref
1315 reference "par:when-to-run-an-export-test"
1322 \begin_layout Subsection
1326 \begin_layout Standard
1327 Adding a new module is very similar to adding a new layout.
1328 Therefore, the previous section applies to new modules as well, with two
1332 \begin_layout Enumerate
1333 You only need to add an entry to
1334 \begin_inset Flex Code
1337 \begin_layout Plain Layout
1338 lib/doc/LaTeXConfig.lyx
1343 if the module requires a LaTeX package.
1344 In that case, the command for entering the InsetInfo is:
1345 \begin_inset Flex Code
1348 \begin_layout Plain Layout
1349 \paragraph_spacing single
1350 info-insert package <name>
1358 \begin_layout Enumerate
1359 Modules do not need a template, only an example, which is strongly encouraged
1360 but not necessarily required.
1363 \begin_layout Subsection
1364 Layouts for document classes with incompatible versions
1367 \begin_layout Standard
1368 Every now and then, there are changes to LaTeX document classes that break
1369 backwards compatibility.
1373 \begin_layout Plain Layout
1374 Uwe has suggested we implement automatic detection of changes in class files.
1375 This could be done by running a script every month that checks if a document
1376 class was changed at CTAN and at the homepages of the scientific journals.
1377 If it reports a change, we can check if our template and layout file are
1378 still usable with the changed document class.
1379 (This is different from the autotests insofar, as this would also catch
1380 changes that do not result in compilation errors.)
1385 Reasons can be a new name for the
1386 \begin_inset Flex Code
1389 \begin_layout Plain Layout
1395 file, removed \SpecialChar LaTeX
1397 How should this best be handled in \SpecialChar LyX
1401 \begin_layout Standard
1402 The idea is to support the new version with a new \SpecialChar LyX
1406 \begin_layout Itemize
1407 Existing documents can still be opened in \SpecialChar LyX
1408 and will continue to work on
1409 systems where the old version is still installed.
1413 \begin_layout Itemize
1414 With differently named
1415 \begin_inset Flex Code
1418 \begin_layout Plain Layout
1424 files, \SpecialChar LyX
1425 can check for the availability of the particular version and reflect
1427 Different document class versions with the same file name are currently
1428 (2.2.x) not detected by the configuration script.
1429 This is planned for 2.3.
1433 \begin_layout Plain Layout
1434 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1437 \begin_layout Plain Layout
1438 However, what we really need is version detection for the configuration,
1439 so that the user can be warned if the required class file has the wrong
1441 (If the class file keeps the name over the version change, only one of
1442 the two layout files generates compilable documents.)
1445 \begin_layout Plain Layout
1446 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1455 \begin_layout Standard
1456 Moreover, because the layout file is completely new, it can be added both
1457 to the master and the stable branches, in accord with the policy discussed
1459 \begin_inset CommandInset ref
1460 LatexCommand formatted
1461 reference "subsec:New-layouts"
1466 No lyx2lyx conversion is then required when a new major version is released.
1469 \begin_layout Standard
1470 The user can then move an existing document to the new version simply by
1471 selecting a new document class.
1472 This step is well supported by \SpecialChar LyX
1473 , with established methods for handling
1474 unsupported styles and other changes.
1475 This way, no lyx2lyx code is required.
1478 \begin_layout Standard
1479 The steps to support a new version of an existing document class are thus:
1482 \begin_layout Itemize
1483 Create a new layout file including the upstream version in the name (avoid
1484 special characters like spaces and dots), e.g.
1486 \begin_inset Flex Code
1489 \begin_layout Plain Layout
1490 acmsiggraph-v0-92.layout
1498 \begin_layout Itemize
1499 Include the name of the
1500 \begin_inset Flex Code
1503 \begin_layout Plain Layout
1509 file as an optional argument in the
1510 \begin_inset Flex Code
1513 \begin_layout Plain Layout
1521 line and include the version number in the GUI name:
1522 \begin_inset Newline newline
1526 \begin_inset Flex Code
1529 \begin_layout Plain Layout
1532 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1533 \begin_inset space ~
1544 \begin_layout Itemize
1545 Update the GUI name in the old layout file (whose name should not have been
1547 \begin_inset Newline newline
1551 \begin_inset Flex Code
1554 \begin_layout Plain Layout
1557 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1558 \begin_inset space ~
1569 \begin_layout Itemize
1570 To avoid duplicate definitions, the new layout can
1571 \begin_inset Flex Code
1574 \begin_layout Plain Layout
1580 the old layout file and add\SpecialChar breakableslash
1581 remove\SpecialChar breakableslash
1582 obsolete\SpecialChar breakableslash
1583 modify settings and styles (similar
1585 \begin_inset Flex Code
1588 \begin_layout Plain Layout
1598 \begin_layout Standard
1599 It may be tempting to let the new layout be the
1600 \begin_inset Quotes eld
1604 \begin_inset Quotes erd
1607 and have the old layout import it.
1608 However, this should not be done because any changes to the new layout
1609 would need undo steps in the importing old layout.
1613 \begin_layout Itemize
1614 If the new LaTeX document class obsoletes the old one, update the example
1615 and template files to use the new layout.
1616 Add a note about the changes (preferably with a pointer to the documentation
1621 \begin_layout Standard
1622 This way, new documents based on the template or example will use the up-to-date
1623 document class version.
1627 \begin_layout Standard
1628 \begin_inset Newpage newpage
1634 \begin_layout Section
1638 \begin_layout Standard
1639 Automated tests are an important tool to detect bugs and regressions in
1640 software development.
1641 Some projects like gcc even require each bug fix to be accompanied by a
1642 test case for the automatic test suite, that would detect this bug.
1643 Testing interactive features automatically is of course very hard, but
1644 core functionality like document import and export can be tested quite
1645 easily, and some tests of this kind exist.
1648 \begin_layout Subsection
1652 \begin_layout Standard
1653 There are attempts to set up a suite of unit tests for LyX.
1656 \begin_layout Standard
1657 TODO: describe what is done and what is still to do.
1660 \begin_layout Subsection
1664 \begin_layout Standard
1665 The tex2lyx tests are located in the
1666 \begin_inset Flex Code
1669 \begin_layout Plain Layout
1675 subfolder of the \SpecialChar LyX
1676 source code distribution.
1677 The actual testing is performed by the simple python script
1678 \begin_inset Flex Code
1681 \begin_layout Plain Layout
1682 src/tex2lyx/test/runtests.py
1688 Each test consists of two files:
1689 \begin_inset Flex Code
1692 \begin_layout Plain Layout
1698 contains the \SpecialChar LaTeX
1699 code that should be tested.
1701 \begin_inset Flex Code
1704 \begin_layout Plain Layout
1710 contains the expected output of tex2lyx.
1711 When a test is run, the actual produced output is compared with the stored
1713 The test passes if both are identical.
1714 The test machinery is also able to generate a file
1715 \begin_inset Flex Code
1718 \begin_layout Plain Layout
1724 by exporting the produced .lyx file with \SpecialChar LyX
1726 This may be useful for roundtrip comparisons.
1729 \begin_layout Subsubsection
1733 \begin_layout Standard
1734 The tex2lyx tests can be run in several ways.
1736 \begin_inset Flex Code
1739 \begin_layout Plain Layout
1745 subfolder of the build directory, the commands
1746 \begin_inset Flex Code
1749 \begin_layout Plain Layout
1755 (cmake, all platforms),
1756 \begin_inset Flex Code
1759 \begin_layout Plain Layout
1765 (cmake, when using a make based build system and not MSVC) or
1766 \begin_inset Flex Code
1769 \begin_layout Plain Layout
1775 (autotools) will run the tex2lyx tests.
1776 Alternatively, in the root of the build directory, the command
1777 \begin_inset Flex Code
1780 \begin_layout Plain Layout
1786 runs all tests whose names match the regex
1787 \begin_inset Quotes eld
1791 \begin_inset Quotes erd
1795 Another way to run the tex2lyx tests in the root build directory is to
1796 instead use the command
1797 \begin_inset Flex Code
1800 \begin_layout Plain Layout
1801 ctest -L '(cmplyx|roundtrip)'
1806 , which runs all tests categorized with the label
1807 \begin_inset Quotes eld
1811 \begin_inset Quotes erd
1815 \begin_inset Quotes eld
1819 \begin_inset Quotes erd
1823 If a test fails, the differences between the expected and actual results
1824 are output in unified diff format.
1827 \begin_layout Subsubsection
1828 Updating test references
1829 \begin_inset CommandInset label
1831 name "sec:Updating-test-references"
1838 \begin_layout Standard
1839 In some cases a changed tex2lyx output is not a test failure, but wanted,
1841 \begin_inset space \thinspace{}
1845 \begin_inset space \space{}
1848 if a tex2lyx bug was fixed, or a new feature was added.
1849 In these cases the stored references need to be updated.
1850 To do so if using autotools, call
1851 \begin_inset Flex Code
1854 \begin_layout Plain Layout
1861 \begin_inset Flex Code
1864 \begin_layout Plain Layout
1870 subdirectory of the build directory.
1871 If instead using CMake, call
1872 \begin_inset Flex Code
1875 \begin_layout Plain Layout
1876 make updatetex2lyxtests
1881 in the build directory or in the
1882 \begin_inset Flex Code
1885 \begin_layout Plain Layout
1891 subdirectory of the build directory.
1895 \begin_layout Plain Layout
1896 Note that this is a case where a make target in the build directory can
1897 affect the source directory, which might not be advisable.
1902 On Windows do the following:
1905 \begin_layout Itemize
1906 Assure that the path to the python.exe is in your system PATH variable.
1909 \begin_layout Itemize
1910 Double-click on the file
1911 \begin_inset Flex Code
1914 \begin_layout Plain Layout
1915 updatetex2lyxtests.vcxproj
1920 in the build directory or in the
1921 \begin_inset Flex Code
1924 \begin_layout Plain Layout
1930 subdirectory of your build directory.
1933 \begin_layout Itemize
1934 In the appearing MSVC program right-click on the project
1938 in the project explorer and chose
1945 \begin_layout Standard
1946 For convenience, these commands also produce re-exported roundtrip .lyx.tex
1948 Please examine the changed output carefully before committing the changed
1949 files to the repository: Since the test machinery does not do a roundtrip
1951 \begin_inset Formula $\Rightarrow$
1955 \begin_inset Formula $\Rightarrow$
1958 .tex, and does not compare the produced dvi or pdf output, it assumes that
1959 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
1961 There is only one chance to detect wrong output: before committing a new
1963 Once it is committed, it is quite difficult to verify whether it is correct.
1966 \begin_layout Standard
1971 update the test references by opening them with \SpecialChar LyX
1972 or directly running lyx2lyx
1974 This would not work, since lyx2lyx and \SpecialChar LyX
1975 produce slightly different files
1976 regarding insignificant whitespace and line breaks.
1979 \begin_layout Subsubsection
1983 \begin_layout Standard
1984 In many cases tests for new features may be added to one of the existing
1985 test files, but sometimes this is not possible or not wanted.
1986 Then a new test file needs to be added:
1989 \begin_layout Enumerate
1991 \begin_inset Flex Code
1994 \begin_layout Plain Layout
1995 src/tex2lyx/test/<test name>.tex
2000 and run tex2lyx in roundtrip mode to produce the file
2001 \begin_inset Flex Code
2004 \begin_layout Plain Layout
2005 src/tex2lyx/test/<test name>.lyx.lyx
2011 This file will be the new reference.
2014 \begin_layout Enumerate
2015 Once you confirmed that the tex2lyx output is correct, add the new files
2016 to the corresponding lists in
2017 \begin_inset Flex Code
2020 \begin_layout Plain Layout
2021 src/tex2lyx/test/runtests.py
2027 \begin_inset Flex Code
2030 \begin_layout Plain Layout
2031 src/tex2lyx/Makefile.am
2037 \begin_inset Flex Code
2040 \begin_layout Plain Layout
2041 src/tex2lyx/test/CMakeLists.txt
2049 \begin_layout Enumerate
2050 Commit the changes to the repository, or send a patch to the development
2051 list and ask for committing if you do not have commit rights.
2054 \begin_layout Subsection
2055 ctest automatic tests
2058 \begin_layout Standard
2059 Some tests are located in the
2060 \begin_inset Flex Code
2063 \begin_layout Plain Layout
2064 development/autotests/
2069 subfolder of the \SpecialChar LyX
2070 source code distribution.
2075 \begin_layout Plain Layout
2076 The README document in this folder only describes the
2077 \begin_inset Quotes eld
2081 \begin_inset Quotes erd
2084 subset of autotests!
2092 \begin_layout Standard
2093 These tests can be run by the commands
2094 \begin_inset Flex Code
2097 \begin_layout Plain Layout
2107 (all platforms) or (when using a make based build system and not MSVC)
2109 \begin_inset Flex Code
2112 \begin_layout Plain Layout
2119 \begin_inset Flex Code
2122 \begin_layout Plain Layout
2133 The test logs are written to the
2134 \begin_inset Flex Code
2137 \begin_layout Plain Layout
2151 \begin_layout Subsubsection
2155 \begin_layout Standard
2156 The export tests are integration tests.
2157 They take longer to run and are more likely to break than the tex2lyx tests.
2158 Nevertheless, they have caught many regressions and without a better alternativ
2159 e it is important to keep them up-to-date and understand how they work.
2162 \begin_layout Standard
2164 \begin_inset Quotes eld
2168 \begin_inset Quotes erd
2171 documentation, template, and example documents.
2172 In addition, there are a number of dedicated sample documents in the
2173 \begin_inset Flex Code
2176 \begin_layout Plain Layout
2182 subfolder of the \SpecialChar LyX
2183 source code distribution.
2184 All samples are (after copying and eventual processing by scripts) exported
2185 to various output formats via the
2186 \begin_inset Flex Code
2189 \begin_layout Plain Layout
2195 command line option.
2196 The tests checks for errors reported by LyX.
2197 (However, error-free export is no guarantee for an error-free output document.)
2200 \begin_layout Paragraph
2201 \begin_inset CommandInset label
2203 name "par:when-to-run-an-export-test"
2207 Expectations of LyX developers
2210 \begin_layout Standard
2211 Because the export tests are integration tests and take a long time to run,
2212 LyX developers are rarely expected to run all of the tests.
2213 Here are some good practices to follow by developers:
2216 \begin_layout Itemize
2217 When making a non-trivial change to a .layout file, run the export and layout
2218 tests corresponding with that .layout file.
2221 \begin_layout Itemize
2222 When making non-trivial changes to a .lyx file, run the export tests correspondin
2223 g to that .lyx file.
2228 \begin_layout Plain Layout
2229 This rule is due to revision.
2233 \begin_layout Plain Layout
2234 There is an objection from the documentation maintainer that working on
2235 the documentation must not be complicated by having to consider non-standard
2239 \begin_layout Itemize
2240 successful compiling/testing an edited documentation file with pdflatex
2241 suffices to ensure it can be commited, not tests with other exports are
2245 \begin_layout Plain Layout
2246 If sudden failures with other exports due to “half-tested” documentation
2247 updates are a problem for the test maintainer, the test suite should use
2251 \begin_layout Itemize
2252 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2255 \begin_layout Itemize
2256 updated regularely (but on a time chosen by the test suite maintainer) from
2257 the originals in lib/doc/
2260 \begin_layout Plain Layout
2264 \begin_layout Itemize
2265 no test will fail due to ongoing work on documentation,
2268 \begin_layout Itemize
2269 the documentation is still tested in full (with some delay),
2272 \begin_layout Itemize
2273 failures with non-default export can be examined and handled accordingly
2274 in one run with the cache update,
2277 \begin_layout Itemize
2278 “interesting failures” (like the nested-language+polyglossia problem in
2279 es/Customization can be separated and moved into dedicated test samples.
2287 \begin_layout Itemize
2288 When making non-trivial changes to LyX's \SpecialChar LaTeX
2290 touching the encoding code or package handling code that you expect will
2291 change the exported \SpecialChar LaTeX
2296 \begin_layout Standard
2297 \paragraph_spacing single
2298 Consider running all of the export tests before and after your change.
2299 If there are differences, please reconcile these (i.e.
2300 fix the bug or fix the tests)
2305 Ask for help if you're not sure what to.
2308 \begin_layout Standard
2309 If you do not want to run the tests,
2312 \begin_layout Itemize
2313 post the patch on the list and others will run the tests and eventually
2317 \begin_layout Itemize
2318 commit, but be prepared to fix eventually arising problems or to revert
2319 the commit if there is no easy fix.
2323 \begin_layout Itemize
2324 Understand how to interpret test failures.
2325 If your commit is found to have broken a test, you should be able to interpret
2326 the test results when made aware of them.
2328 \begin_inset CommandInset ref
2330 reference "subsec:Interpreting-export-tests"
2337 \begin_layout Paragraph
2338 \begin_inset CommandInset label
2340 name "par:export-test-output-formats"
2347 \begin_layout Standard
2348 The following output formats are currently tested for each sample document
2350 \begin_inset CommandInset ref
2352 reference "par:Export-test-filtering"
2359 \begin_layout Labeling
2360 \labelwidthstring 00.00.0000
2365 \begin_layout Labeling
2366 \labelwidthstring 00.00.0000
2367 lyx16 LyX 1.6 file format (lyx2lyx)
2370 \begin_layout Labeling
2371 \labelwidthstring 00.00.0000
2372 lyx21 LyX 2.1 file format (lyx2lyx)
2375 \begin_layout Labeling
2376 \labelwidthstring 00.00.0000
2377 xhtml LyXHTML (native LyX HTML export)
2381 \begin_layout Labeling
2382 \labelwidthstring 00.00.0000
2384 \begin_inset space ~
2388 \begin_inset space ~
2395 \begin_layout Labeling
2396 \labelwidthstring pdf5msystemFM
2397 dvi DVI (8-bit latex)
2400 \begin_layout Labeling
2401 \labelwidthstring pdf5msystemFM
2402 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2405 \begin_layout Labeling
2406 \labelwidthstring pdf5msystemFM
2407 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2410 \begin_layout Labeling
2411 \labelwidthstring pdf5msystemFM
2415 \begin_layout Labeling
2416 \labelwidthstring pdf5msystemFM
2417 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2420 \begin_layout Labeling
2421 \labelwidthstring pdf5msystemFM
2422 pdf4_systemF PDF (XeTeX with Unicode fonts)
2425 \begin_layout Labeling
2426 \labelwidthstring pdf5msystemFM
2427 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2430 \begin_layout Labeling
2431 \labelwidthstring pdf5msystemFM
2432 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2436 \begin_layout Labeling
2437 \labelwidthstring 00.00.0000
2439 \begin_inset space ~
2443 \begin_inset space ~
2447 \begin_inset space ~
2451 \begin_inset space ~
2458 \begin_layout Labeling
2459 \labelwidthstring pdf5msystemFM
2460 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2463 \begin_layout Labeling
2464 \labelwidthstring pdf5msystemFM
2465 pdf3 DVI -> PDF (dvipdfm)
2469 \begin_layout Labeling
2470 \labelwidthstring 00.00.0000
2472 \begin_inset space ~
2475 tested: (or only if set as default output format in the document source)
2479 \begin_layout Labeling
2480 \labelwidthstring pdf5msystemFM
2484 \begin_layout Labeling
2485 \labelwidthstring pdf5msystemFM
2486 luatex LaTeX (LuaTeX)
2489 \begin_layout Labeling
2490 \labelwidthstring pdf5msystemFM
2491 dviluatex LaTeX (dviluatex)
2494 \begin_layout Labeling
2495 \labelwidthstring pdf5msystemFM
2496 pdflatex LaTeX (pdflatex)
2499 \begin_layout Labeling
2500 \labelwidthstring pdf5msystemFM
2501 platex LaTeX (pLaTeX)
2504 \begin_layout Labeling
2505 \labelwidthstring pdf5msystemFM
2509 \begin_layout Labeling
2510 \labelwidthstring pdf5msystemFM
2511 eps3 EPS (encapsulated Postscript) (cropped)
2514 \begin_layout Labeling
2515 \labelwidthstring pdf5msystemFM
2516 ps DVI -> Postscript (dvips)
2519 \begin_layout Labeling
2520 \labelwidthstring pdf5msystemFM
2524 \begin_layout Labeling
2525 \labelwidthstring pdf5msystemFM
2526 text (nor text2, ..., text4)
2529 \begin_layout Labeling
2530 \labelwidthstring pdf5msystemFM
2534 \begin_layout Labeling
2535 \labelwidthstring pdf5msystemFM
2539 \begin_layout Labeling
2540 \labelwidthstring pdf5msystemFM
2544 \begin_layout Labeling
2545 \labelwidthstring pdf5msystemFM
2550 \begin_layout Paragraph
2551 \begin_inset CommandInset label
2553 name "par:Configuring-ctests"
2557 Configuring the tests
2560 \begin_layout Standard
2561 To enable the export autotests, add the
2562 \begin_inset Flex Code
2565 \begin_layout Plain Layout
2566 -DLYX_ENABLE_EXPORT_TESTS=ON
2575 \begin_layout Standard
2576 \begin_inset Flex Code
2579 \begin_layout Plain Layout
2580 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2588 \begin_layout Standard
2590 This flag will increase the time for the cmake command by several seconds,
2591 mainly because of the process of inverting tests (see Section
2592 \begin_inset CommandInset ref
2594 reference "subsec:Interpreting-export-tests"
2601 \begin_layout Paragraph
2602 \begin_inset CommandInset label
2604 name "par:ctest-options"
2611 \begin_layout Standard
2612 To run all tests, in the build directory simply run the command
2613 \begin_inset Flex Code
2616 \begin_layout Plain Layout
2623 A full, up-to-date TeXLive installation is recommended to run the tests.
2624 Otherwise, some tests will fail.
2625 Tests with additional requirements are labeled
2626 \begin_inset Quotes eld
2629 unreliable:nonstandard
2630 \begin_inset Quotes erd
2637 \begin_layout Standard
2638 To run only some of the tests, use command line options (see examples below):
2641 \begin_layout Labeling
2642 \labelwidthstring -R
2643 \begin_inset Flex Code
2646 \begin_layout Plain Layout
2652 Run only the tests whose names match the given regular expression.
2655 \begin_layout Labeling
2656 \labelwidthstring -R
2657 \begin_inset Flex Code
2660 \begin_layout Plain Layout
2666 Run only the tests whose labels match the given regular expression.
2667 A test may have more that one label.
2671 \begin_layout Labeling
2672 \labelwidthstring -R
2673 \begin_inset Flex Code
2676 \begin_layout Plain Layout
2682 Exclude the tests whose names match the given regular expression.
2685 \begin_layout Labeling
2686 \labelwidthstring -R
2687 \begin_inset Flex Code
2690 \begin_layout Plain Layout
2696 Exclude the tests whose labels match the given regular expression.
2697 Cannot be combined with
2698 \begin_inset Flex Code
2701 \begin_layout Plain Layout
2710 \begin_layout Standard
2711 The following options help to find good selection patterns:
2714 \begin_layout Labeling
2715 \labelwidthstring -R
2716 \begin_inset Flex Code
2719 \begin_layout Plain Layout
2725 List the tests that would be run but not actually run them.
2730 \begin_layout Standard
2731 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2732 to know how many tests there are or whether your
2733 \begin_inset Flex Code
2736 \begin_layout Plain Layout
2742 regular expression did what you expected.
2746 \begin_layout Labeling
2747 \labelwidthstring -R
2748 \begin_inset Flex Code
2751 \begin_layout Plain Layout
2752 \SpecialChar nobreakdash
2753 \SpecialChar nobreakdash
2759 print the list of all labels associated with the test set.
2760 Can also be combined with -R, -L, -E, ...
2764 \begin_layout Standard
2765 Other useful options are:
2768 \begin_layout Labeling
2769 \labelwidthstring -R
2770 \begin_inset Flex Code
2773 \begin_layout Plain Layout
2779 Run the tests in parallel using the given number of jobs.
2783 \begin_layout Standard
2784 We are still working on getting the tests to run in parallel.
2785 However, when running the tests in parallel, sometimes tests fail that
2786 pass when run sequentially.
2787 A reasonable approach is to first run the tests in parallel and then run
2788 the failed tests sequentially.
2791 \begin_layout Standard
2792 For example, to run 8 jobs at a time:
2795 \begin_layout Standard
2796 \begin_inset Flex Code
2799 \begin_layout Plain Layout
2808 \begin_layout Standard
2809 \begin_inset Flex Code
2812 \begin_layout Plain Layout
2813 ctest \SpecialChar nobreakdash
2814 \SpecialChar nobreakdash
2823 \begin_layout Standard
2824 When specifying a subset of the tests (e.g.
2826 \begin_inset Flex Code
2829 \begin_layout Plain Layout
2830 \SpecialChar nobreakdash
2836 ), the same subset must be specified when using the
2837 \begin_inset Flex Code
2840 \begin_layout Plain Layout
2841 \SpecialChar nobreakdash
2842 \SpecialChar nobreakdash
2848 option because it is the test numbers that are used to index which tests
2849 failed on the previous run.
2852 \begin_layout Standard
2854 Note that some tests cannot be run in parallel.
2855 These tests are marked in the code with the
2856 \begin_inset Flex Code
2859 \begin_layout Plain Layout
2870 \begin_layout Labeling
2871 \labelwidthstring -R
2872 \begin_inset Flex Code
2875 \begin_layout Plain Layout
2876 \SpecialChar nobreakdash
2877 \SpecialChar nobreakdash
2883 Set a global timeout on all tests that do not already have a timeout set
2888 \begin_layout Standard
2889 There have been bugs in LyX and in \SpecialChar LaTeX
2890 which cause compilation to hang, and
2891 without a timeout a test might never stop (in one case there was even a
2893 If a test times out, the
2894 \begin_inset Flex Code
2897 \begin_layout Plain Layout
2903 command exits with error, but you can distinguish between a timed out test
2904 and a failed test in the output reported at the end of the
2905 \begin_inset Flex Code
2908 \begin_layout Plain Layout
2918 \begin_layout Standard
2920 \begin_inset Flex Code
2923 \begin_layout Plain Layout
2929 ) the full list of command line options.
2932 \begin_layout Paragraph
2936 \begin_layout Itemize
2937 run only the export tests:
2938 \begin_inset Flex Code
2941 \begin_layout Plain Layout
2950 \begin_layout Itemize
2952 \begin_inset Flex Code
2955 \begin_layout Plain Layout
2956 ctest -L "inverted|suspended"
2964 \begin_layout Itemize
2965 list all export tests which match any of the labelling patterns:
2966 \begin_inset Flex Code
2969 \begin_layout Plain Layout
2980 \begin_layout Itemize
2981 exclude rarely used output formats and post-processing tests
2982 \begin_inset Flex Code
2985 \begin_layout Plain Layout
2986 ctest -L export -E "_(texF|dvi3|pdf3?)"
2994 \begin_layout Paragraph
2995 \begin_inset CommandInset label
2997 name "subsec:Interpreting-export-tests"
3001 Interpreting the export test results
3004 \begin_layout Standard
3005 A test can fail for several reasons, not all of them bad.
3008 \begin_layout Enumerate
3009 A new or edited sample document may be incompatible with some output formats.
3012 \begin_layout Enumerate
3013 A dependency is not met (e.g.
3014 the \SpecialChar LaTeX
3016 One hint that this is the case is that the corresponding
3017 \begin_inset Flex Code
3020 \begin_layout Plain Layout
3026 test will likely also fail.
3029 \begin_layout Enumerate
3030 An inverted test fails to fail (i.e.
3031 export that previously failed now works).
3034 \begin_layout Enumerate
3035 An external dependency was updated (e.g.
3040 \begin_layout Enumerate
3041 A recent code change introduced a bug.
3044 \begin_layout Enumerate
3045 \begin_inset CommandInset label
3051 A change in a document exposed a previously unknown bug or an incompatibility
3052 with an export format (e.g.
3053 Lua\SpecialChar LaTeX
3057 \begin_layout Standard
3058 Because the .lyx files are exported in several formats, it is not surprising
3059 that many of the exports fail.
3060 This expectation of failure is addressed by
3061 \begin_inset Quotes eld
3065 \begin_inset Quotes erd
3068 the tests, that is, by marking the test as
3069 \begin_inset Quotes eld
3073 \begin_inset Quotes erd
3076 if the export exits with error and as
3077 \begin_inset Quotes eld
3081 \begin_inset Quotes erd
3084 if the export succeeds
3089 It follows that these expected failures will not show up as failed tests
3090 in the test results and thus will not pollute the
3091 \begin_inset Quotes eld
3095 \begin_inset Quotes erd
3099 If the export actually succeeds, then the test will fail.
3100 The purpose of this failure is to get your attention—something has changed,
3101 possibly for the better.
3104 \begin_layout Standard
3105 We try to document why a test is inverted or ignored.
3106 See the comment (prefixed with
3107 \begin_inset Flex Code
3110 \begin_layout Plain Layout
3116 ) above the block in which the test is listed as inverted or ignored in
3118 \begin_inset Flex Code
3121 \begin_layout Plain Layout
3122 development/autotests/suspiciousTests
3128 \begin_inset Flex Code
3131 \begin_layout Plain Layout
3132 development/autotests/unreliableTests
3138 \begin_inset Flex Code
3141 \begin_layout Plain Layout
3142 development/autotests/ignoredTests
3151 \begin_layout Standard
3152 A good question is why do we enable the tests for non-default formats? The
3153 answer is that if a non-default route is broken it is often because a bug
3154 was introduced in LyX and not because a document-specific change was made
3155 that is not supported by the route.
3156 In other words, there is a high signal/noise ratio in the export tests
3157 for some non-default formats.
3161 \begin_layout Standard
3162 When a test or several tests fail, consider checking the files in the
3163 \begin_inset Flex Code
3166 \begin_layout Plain Layout
3172 subdirectory of your build directory.
3173 In this subdirectory are three files: the file
3174 \begin_inset Flex Code
3177 \begin_layout Plain Layout
3183 simply lists the tests that failed on your last
3184 \begin_inset Flex Code
3187 \begin_layout Plain Layout
3194 \begin_inset Flex Code
3197 \begin_layout Plain Layout
3203 file contains the output from the tests (and often has details explaining
3204 why a test failed); and the
3205 \begin_inset Flex Code
3208 \begin_layout Plain Layout
3214 file lists the times that it took to run the tests.
3217 \begin_layout Paragraph
3218 What action should you take if a test fails?
3221 \begin_layout Standard
3222 \paragraph_spacing single
3223 It is always good to check manually why something fails and if it passes
3224 if the PDF output is good.
3227 \begin_layout Itemize
3228 Generally, if a change breaks compilation for the target format (for the
3229 manuals pdf2) without solving some important other issue,
3231 fix or revert the commit
3233 that led to failure.
3236 \begin_layout Itemize
3237 If it is not possible to (immediately) fix the failure but there are reasons
3238 not to revert the commit (e.g.
3239 it fixes another more important issue),
3243 the failing test case (see
3244 \begin_inset CommandInset ref
3246 reference "par:Inverted-tests"
3253 \begin_layout Itemize
3258 test case fails because the export now works,
3262 the test by removing the labeling pattern from
3263 \begin_inset Quotes eld
3267 \begin_inset Quotes erd
3271 \begin_inset CommandInset ref
3273 reference "par:Inverted-tests"
3280 \begin_layout Itemize
3281 If the export did not fail previously but led to wrong output (PDF, say),
3282 it is in fact an improvement when the test now fails, label it as
3283 \begin_inset Quotes eld
3286 unreliable:wrong:output
3287 \begin_inset Quotes erd
3291 \begin_inset CommandInset ref
3293 reference "par:Unreliable-tests"
3300 \begin_layout Itemize
3301 In case of tests failing due to missing requirements (when only a subset
3302 of TeXLive is installed or a test labeled
3303 \begin_inset Quotes eld
3306 unreliable:nonstandard
3307 \begin_inset Quotes erd
3310 fails), ignore the failure, ask for someone else to run the test, or install
3311 the missing ressources and try again.
3314 \begin_layout Paragraph
3315 \begin_inset CommandInset label
3317 name "par:Inverted-tests"
3324 \begin_layout Standard
3325 Test cases whose name matches a pattern in the file
3326 \begin_inset Flex Code
3329 \begin_layout Plain Layout
3330 development/autotests/suspiciousTests
3340 They get also the test property
3341 \begin_inset Flex Code
3344 \begin_layout Plain Layout
3351 they are reported as failing if the export works without error
3352 \begin_inset Flex URL
3355 \begin_layout Plain Layout
3357 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3365 \begin_layout Standard
3366 Add failing cases to this file, if they cannot be solved
3367 \begin_inset Quotes eld
3371 \begin_inset Quotes erd
3374 but it is expected that the export will work in a foreseeable future, e.g.
3375 low priority issues like failures to export to a non-target format (for
3376 the manuals everything except pdf2).
3379 \begin_layout Standard
3380 The following sublabels are currently present in
3381 \begin_inset Flex Code
3384 \begin_layout Plain Layout
3393 \begin_layout Description
3394 todo test failures that require attention:
3398 \begin_layout Itemize
3399 minor issues to explore and properly sort later,
3402 \begin_layout Itemize
3406 \begin_layout Itemize
3407 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3411 \begin_layout Description
3412 lyxbugs LyX bugs with a Trac number.
3415 \begin_layout Description
3416 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3420 \begin_layout Standard
3421 "Wontfix" if demonstrating correct use and OK in the default output format.
3425 \begin_layout Description
3426 texissues Export fails due to LaTeX limitations like non-ASCII characters
3427 in verbatim or listings, incompatible packages, ...
3431 \begin_layout Standard
3432 "Wontfix" if documents demonstrate correct use in the default output format:
3435 \begin_layout Itemize
3436 If the source can be made more robust without becoming "hackish", fix the
3440 \begin_layout Itemize
3441 if LyX could be enhanced to care for a permanent TeX limitation, file a
3442 ticket at trac and add a pattern under lyxbugs,
3445 \begin_layout Itemize
3446 otherwise, add a pattern here.
3450 \begin_layout Description
3451 attic Documents in the attic.
3452 (Kept for reference and format conversion test.)
3455 \begin_layout Subparagraph
3459 \begin_layout Standard
3460 Test cases whose name additionally matches a pattern in the file
3461 \begin_inset Flex Code
3464 \begin_layout Plain Layout
3465 development/autotests/suspendedTests
3483 This means they are not executed using
3484 \begin_inset Flex Code
3487 \begin_layout Plain Layout
3494 \begin_inset Flex Code
3497 \begin_layout Plain Layout
3504 However, they also get the test property
3505 \begin_inset Flex Code
3508 \begin_layout Plain Layout
3515 they are reported as failing if the export works without error.
3516 From time to time they still have to be checked using
3517 \begin_inset Flex Code
3520 \begin_layout Plain Layout
3529 \begin_layout Standard
3530 These tests are suspended, because the export fails for known reasons which
3531 cannot ATM be resolved.
3532 But it is expected the reason might disappear in the future.
3533 Be it new TL or better handling in \SpecialChar LyX
3537 \begin_layout Standard
3538 For ctest commands without the
3539 \begin_inset Flex Code
3542 \begin_layout Plain Layout
3548 parameter nothing changes.
3549 Suspended or not, tests will be executed depending only on the selecting
3550 regular expression given to the ctest command (see
3551 \begin_inset CommandInset ref
3553 reference "par:ctest-options"
3560 \begin_layout Paragraph
3561 \begin_inset CommandInset label
3563 name "par:Unreliable-tests"
3570 \begin_layout Standard
3571 Test cases whose name matches a pattern in the file
3572 \begin_inset Flex Code
3575 \begin_layout Plain Layout
3576 development/autotests/unreliableTests
3588 \begin_layout Standard
3589 These tests are not executed using
3590 \begin_inset Flex Code
3593 \begin_layout Plain Layout
3600 \begin_inset Flex Code
3603 \begin_layout Plain Layout
3613 \begin_layout Standard
3614 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3615 or pass but should rather fail (wrong output).
3617 \begin_inset Note Note
3620 \begin_layout Plain Layout
3621 *invalid* tests (wrong output) are not *unreliable*.
3622 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3631 \begin_layout Description
3632 nonstandard Documents with additional requirements, e.g.
3633 a class or package file not in TeXLive.
3635 \begin_inset Note Note
3638 \begin_layout Plain Layout
3639 TODO: rename to "extra"?
3648 \begin_layout Standard
3649 These tests are labeled as
3655 \begin_layout Description
3656 erratic Tests depending on local configuration, OS, TeX distribution, package
3657 versions, or the phase of the moon.
3659 \begin_inset Note Note
3662 \begin_layout Plain Layout
3667 only for the phase-of-moon dependency?
3676 \begin_layout Standard
3677 These tests are labeled as
3683 \begin_layout Description
3685 \begin_inset space ~
3688 output Export does not fail but the resulting document has errors.
3692 \begin_layout Standard
3693 \paragraph_spacing single
3694 \begin_inset Note Note
3697 \begin_layout Plain Layout
3698 \paragraph_spacing single
3699 These tests are actually not
3707 (not measuring what they should measure).
3716 \begin_layout Paragraph
3717 \begin_inset CommandInset label
3719 name "par:Export-test-filtering"
3723 Export test filtering
3726 \begin_layout Standard
3727 The assignment of a label to a test is controlled by a set of files with
3728 regular expressions that are matched against the test names.
3731 \begin_layout Description
3732 ignoredTests (small file)
3733 \begin_inset Newline newline
3736 Tests selected here are withdrawn in the configuration step (cf.
3738 \begin_inset CommandInset ref
3740 reference "par:Configuring-ctests"
3748 \begin_layout Labeling
3749 \labelwidthstring 00.00.0000
3750 Input Test of any export combination
3753 \begin_layout Labeling
3754 \labelwidthstring 00.00.0000
3755 Output Stop if tests not selected here
3759 \begin_layout Description
3760 unreliableTests: Tests selected either pass or fail, but that is dependent
3761 on the system where the test is run.
3762 Selected tests gain the label 'unreliable'.
3766 \begin_layout Labeling
3767 \labelwidthstring 00.00.0000
3768 Input Each test which passed 'ignoredTests'
3771 \begin_layout Labeling
3772 \labelwidthstring 00.00.0000
3773 Output Stop if test selected, gain label 'unreliable'.
3777 \begin_layout Description
3779 \begin_inset space \space{}
3786 \begin_layout Labeling
3787 \labelwidthstring 00.00.0000
3788 Input Each test which passed 'unreliableTests'
3791 \begin_layout Labeling
3792 \labelwidthstring 00.00.0000
3793 Output Stop if not selected.
3796 \begin_layout Standard
3797 The following file is meant as subselections of 'suspiciousTests'.
3798 If neither subselection applies, test gains labels 'export' and 'inverted'
3801 \begin_layout Description
3802 suspendedTests Tests selected here gain the label 'suspended' but _not_
3803 'export' or 'inverted', although in ctest they remain inverted.
3804 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3808 \begin_layout Labeling
3809 \labelwidthstring 00.00.0000
3810 Input Each test selected by 'suspiciousTests'
3813 \begin_layout Labeling
3814 \labelwidthstring 00.00.0000
3815 Output Selected test gains label 'suspended'.
3821 \begin_layout Standard
3822 The following table may clarify label assignement
3825 \begin_layout Standard
3826 \begin_inset Tabular
3827 <lyxtabular version="3" rows="7" columns="12">
3828 <features tabularvalignment="middle">
3829 <column alignment="left" valignment="top" width="0pt">
3830 <column alignment="left" valignment="top" width="0pt">
3831 <column alignment="left" valignment="top" width="0pt">
3832 <column alignment="left" valignment="top" width="0pt">
3833 <column alignment="center" valignment="top">
3834 <column alignment="center" valignment="top">
3835 <column alignment="center" valignment="top">
3836 <column alignment="center" valignment="top">
3837 <column alignment="center" valignment="top">
3838 <column alignment="center" valignment="top">
3839 <column alignment="center" valignment="top">
3840 <column alignment="center" valignment="top">
3842 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3845 \begin_layout Plain Layout
3851 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3854 \begin_layout Plain Layout
3860 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3863 \begin_layout Plain Layout
3869 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3872 \begin_layout Plain Layout
3878 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3881 \begin_layout Plain Layout
3882 Marked in ctest, Assigned label
3887 <cell multicolumn="2" alignment="center" valignment="top" usebox="none">
3890 \begin_layout Plain Layout
3896 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3899 \begin_layout Plain Layout
3905 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3908 \begin_layout Plain Layout
3914 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3917 \begin_layout Plain Layout
3923 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3926 \begin_layout Plain Layout
3932 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3935 \begin_layout Plain Layout
3941 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
3944 \begin_layout Plain Layout
3952 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3955 \begin_layout Plain Layout
3961 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3964 \begin_layout Plain Layout
3970 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3973 \begin_layout Plain Layout
3979 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3982 \begin_layout Plain Layout
3988 <cell multicolumn="1" 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" usebox="none">
4000 \begin_layout Plain Layout
4006 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4009 \begin_layout Plain Layout
4015 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
4018 \begin_layout Plain Layout
4024 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4027 \begin_layout Plain Layout
4033 <cell multicolumn="2" alignment="center" valignment="top" topline="true" usebox="none">
4036 \begin_layout Plain Layout
4042 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4045 \begin_layout Plain Layout
4051 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4054 \begin_layout Plain Layout
4062 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4065 \begin_layout Plain Layout
4071 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4074 \begin_layout Plain Layout
4080 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4083 \begin_layout Plain Layout
4089 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4092 \begin_layout Plain Layout
4098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4101 \begin_layout Plain Layout
4107 <cell alignment="center" valignment="top" topline="true" usebox="none">
4110 \begin_layout Plain Layout
4116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4119 \begin_layout Plain Layout
4125 <cell alignment="center" valignment="top" topline="true" usebox="none">
4128 \begin_layout Plain Layout
4134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4137 \begin_layout Plain Layout
4143 <cell alignment="center" valignment="top" topline="true" usebox="none">
4146 \begin_layout Plain Layout
4152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4155 \begin_layout Plain Layout
4161 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4164 \begin_layout Plain Layout
4172 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4175 \begin_layout Plain Layout
4181 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4184 \begin_layout Plain Layout
4190 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4193 \begin_layout Plain Layout
4199 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="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" usebox="none">
4238 \begin_layout Plain Layout
4244 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4247 \begin_layout Plain Layout
4253 <cell alignment="center" valignment="top" topline="true" usebox="none">
4256 \begin_layout Plain Layout
4262 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4265 \begin_layout Plain Layout
4271 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4274 \begin_layout Plain Layout
4282 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4285 \begin_layout Plain Layout
4291 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4294 \begin_layout Plain Layout
4300 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4303 \begin_layout Plain Layout
4309 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="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" usebox="none">
4348 \begin_layout Plain Layout
4354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4357 \begin_layout Plain Layout
4363 <cell alignment="center" valignment="top" topline="true" usebox="none">
4366 \begin_layout Plain Layout
4372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4375 \begin_layout Plain Layout
4381 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4384 \begin_layout Plain Layout
4392 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4395 \begin_layout Plain Layout
4401 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4404 \begin_layout Plain Layout
4410 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4413 \begin_layout Plain Layout
4419 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="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" usebox="none">
4458 \begin_layout Plain Layout
4464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4467 \begin_layout Plain Layout
4473 <cell alignment="center" valignment="top" topline="true" usebox="none">
4476 \begin_layout Plain Layout
4482 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4485 \begin_layout Plain Layout
4491 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4494 \begin_layout Plain Layout
4502 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4505 \begin_layout Plain Layout
4511 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4514 \begin_layout Plain Layout
4520 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4523 \begin_layout Plain Layout
4529 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4532 \begin_layout Plain Layout
4538 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4541 \begin_layout Plain Layout
4547 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4550 \begin_layout Plain Layout
4556 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4559 \begin_layout Plain Layout
4565 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4568 \begin_layout Plain Layout
4574 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4577 \begin_layout Plain Layout
4583 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4586 \begin_layout Plain Layout
4592 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4595 \begin_layout Plain Layout
4601 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4604 \begin_layout Plain Layout
4618 \begin_layout Subsubsection
4622 \begin_layout Standard
4623 These tests check whether a .lyx file loads without any terminal messages.
4624 They correspond to the manual operations of simply opening a .lyx file on
4625 the terminal, exiting LyX once the file is loaded, and then checking whether
4626 there is any output from the terminal.
4627 These tests are useful for catching malformed .lyx files and parsing bugs.
4628 They can also be used to find a .lyx file in which an instance of something
4630 To do this, compile LyX with a local patch that outputs something to the
4631 terminal when an instance is found, and then run the check_load tests to
4632 see if any fail, which would mean that the situation occurs in the LyX
4633 documentation files corresponding to the failed tests.
4634 These tests are expectedly fragile: any LyX diagnostic message, which is
4635 not necessarily an error, would cause the tests to fail.
4636 Similarly, any message output by a library (e.g.
4637 Qt) would also cause failure.
4638 There are some messages that the check_load tests are instructed to ignore,
4639 which are stored in the file
4640 \begin_inset Flex Code
4643 \begin_layout Plain Layout
4644 development/autotests/filterCheckWarnings
4652 \begin_layout Standard
4653 Under cmake, the tests are labeled as 'load'.
4656 \begin_layout Subsubsection
4660 \begin_layout Standard
4661 Automated tests based on the "MonKey Testing" keytest program.
4662 They are documented in the README document in
4663 \begin_inset Flex Code
4666 \begin_layout Plain Layout
4667 development/autotests
4672 subfolder of the \SpecialChar LyX
4673 source code distribution.
4677 \begin_layout Subsubsection
4681 \begin_layout Standard
4682 These tests combine lyx2lyx tests with check_load tests.
4683 They fail if either fails.
4686 \begin_layout Subsubsection
4690 \begin_layout Standard
4691 The URL tests are enabled with the
4692 \begin_inset Flex Code
4695 \begin_layout Plain Layout
4696 -DLYX_ENABLE_URLTESTS=ON
4701 CMake flag and are useful for finding broken links in our documentation
4703 If a URL test fails, to see which link in particular was reported as broken,
4705 \begin_inset Flex Code
4708 \begin_layout Plain Layout
4715 These tests are extremely fragile (e.g.
4716 a test can depend on your Internet connection) and a failed URL test should
4717 not be taken too seriously.
4718 URL tests are labeled as
4723 \begin_layout Paragraph
4727 \begin_layout Standard
4728 cmake is required to run the \SpecialChar LyX
4729 tests, running them is not implemented for
4733 \begin_layout Standard
4734 The appropriate commands are:
4737 \begin_layout Itemize
4743 \begin_inset Newline newline
4746 runs all tests with label
4751 \begin_layout Itemize
4754 ctest -R 'check_.*urls'
4757 \begin_inset Newline newline
4760 runs the tests 'check_accessible_urls'
4763 \begin_layout Standard
4764 Associated test results can be examined in ctest-log directory in files
4765 of the form 'LastFailed.*URLS.log'
4768 \begin_layout Section
4769 Development policies
4772 \begin_layout Standard
4773 This chapter lists some guidelines that should be followed.
4774 This list is not complete, and many guidelines are in separate chapters,
4776 \begin_inset Quotes eld
4779 When is an update of the .lyx file format number needed?
4780 \begin_inset Quotes erd
4784 \begin_inset CommandInset ref
4786 reference "sec:When-is-an"
4793 \begin_layout Subsection
4794 When to set a fixed milestone?
4797 \begin_layout Standard
4798 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
4802 \begin_layout Enumerate
4803 Somebody is actively working on a fix.
4806 \begin_layout Enumerate
4807 The bug is so severe that it would block the release if it is not fixed.
4810 \begin_layout Standard
4811 If a bug is important, but nobody is working on it, and it is no showstopper,
4812 use a milestone like 2.1.x or 2.2.x.
4813 For all other bugs, do not set a milestone at all.
4816 \begin_layout Subsection
4817 Can we add rc entries in stable branch?
4820 \begin_layout Standard
4822 We are supposed to increase the prefs2prefs version number with such things.
4825 \begin_layout Section
4826 Documentation policies
4829 \begin_layout Standard
4830 The main documentation consists of these files:
4833 \begin_layout Description
4834 splash.lyx it is the first file you see after an installation.
4835 We assume that a new user sees this.
4836 It is therefore designed to be as simple as possible.
4837 Therefore please don't add any new formatting, only fix typos etc.
4838 Splash.lyx is up to date for \SpecialChar LyX
4839 2.1.x, currently maintained by Uwe Stöhr.
4842 \begin_layout Description
4843 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
4845 It therefore uses a limited set of formatting.
4846 For example a standard document class.
4847 Since new users will first learn about the formatting possibilities of
4849 please keep this file that simple.
4850 Intro.lyx is up to date for \SpecialChar LyX
4851 2.1.x, currently maintained by Uwe Stöhr.
4854 \begin_layout Description
4855 Tutorial.lyx our tutorial.
4856 It must be always up to date.
4857 Normally there is nothing to add since we don't want to overwhelm new users
4858 with too much details.
4859 The will learn these details while using \SpecialChar LyX
4860 and we have special manuals.
4861 Tutorial.lyx is up to date for \SpecialChar LyX
4862 2.1.x, currently maintained by Uwe Stöhr.
4865 \begin_layout Description
4866 UserGuide.lyx our main user guide.
4867 It covers a mixture of basic and detailed information.
4868 Some information is also in the Math and EmbeddedObjects manual so that
4869 the UserGuide refers to these files.
4870 UserGuide.lyx is up to date for \SpecialChar LyX
4871 2.1.x, currently maintained by Uwe Stöhr.
4874 \begin_layout Description
4875 EmbeddedObjects.lyx a special manual to explain things like tables floats
4878 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
4879 2.1.x, currently maintained by Uwe
4883 \begin_layout Description
4884 Math.lyx a special manual to explain everything regarding math in all detail.
4885 Math.lyx is up to date for \SpecialChar LyX
4886 2.1.x, currently maintained by Uwe Stöhr.
4889 \begin_layout Description
4890 Additional.lyx this manual covers information that would be too much detail
4891 for the UserGuide or would make the UserGuide uncompilable or only compilable
4892 when installing a lot of special \SpecialChar LaTeX
4894 What should be in the UserGuide or better in Additional is a matter of
4896 it is up to you to decide that.
4897 Additional.lyx is not completely up to date for \SpecialChar LyX
4900 \begin_inset space ~
4903 8 is up to date and currently maintained by Uwe Stöhr.
4904 It certainly needs a rewrite and update.
4905 For example many info in chapter
4906 \begin_inset space ~
4909 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
4913 \begin_layout Description
4914 Customization.lyx this manual covers information how to customize \SpecialChar LyX
4916 output formats, operating systems, languages etc.
4917 It is currently completely out of date and needs a major rewrite and update.
4918 If you do this please assure that your information are given for all OSes
4919 and \SpecialChar LaTeX
4920 distributions (meaning be as objective as possible).
4923 \begin_layout Standard
4925 \begin_inset space ~
4928 rules in editing the docs:
4931 \begin_layout Enumerate
4932 If you are not the maintainer of a doc file or a chapter/section, you MUST
4933 use change tracking so that the maintainer could review your changes
4936 \begin_layout Enumerate
4937 Respect the formatting of the document.
4938 The different files use different formatting styles.
4939 That is OK and has historic reasons nobody fully know ;-).
4940 But it is important to be consistent within one file.
4943 \begin_layout Enumerate
4944 All changes you make to a file in one language MUST also go the file in
4945 the other actively maintained languages.
4946 Normally the maintainer does this for you, if you are the maintainer, you
4947 must do this by copying or changing the changed or added text to the other
4948 files so that the translators sees the blue underlined text and know what
4949 they have to translate and what was changed.
4952 \begin_layout Enumerate
4953 You MUST assure that the document is compilable as
4954 \begin_inset Quotes eld
4958 \begin_inset Quotes erd