1 #LyX 2.3 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
30 \default_output_format pdf2
32 \bibtex_command default
33 \index_command default
37 \pdf_title "LyX's Development manual"
38 \pdf_author "LyX Team"
39 \pdf_subject "LyX's development documentation"
40 \pdf_keywords "LyX, Documentation, Development"
42 \pdf_bookmarksnumbered true
43 \pdf_bookmarksopen true
44 \pdf_bookmarksopenlevel 1
49 \pdf_pdfusetitle false
50 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
53 \use_package amsmath 1
54 \use_package amssymb 1
57 \use_package mathdots 1
58 \use_package mathtools 0
60 \use_package stackrel 0
61 \use_package stmaryrd 0
62 \use_package undertilde 0
64 \cite_engine_type default
68 \paperorientation portrait
72 \notefontcolor #0000ff
79 \paragraph_separation indent
80 \paragraph_indentation default
81 \quotes_language english
84 \paperpagestyle headings
85 \tracking_changes false
95 Developing \SpecialChar LyX
99 \begin_layout Subtitle
104 by the \SpecialChar LyX
109 \begin_layout Plain Layout
111 If you have comments or error corrections, please send them to the \SpecialChar LyX
114 \begin_inset Flex Code
117 \begin_layout Plain Layout
119 <lyx-docs@lists.lyx.org>
132 \begin_layout Standard
133 \begin_inset CommandInset toc
134 LatexCommand tableofcontents
141 \begin_layout Section
145 \begin_layout Standard
146 This manual documents some aspects of \SpecialChar LyX
148 It is currently rather incomplete, but will hopefully be extended in the
150 Meanwhile, additional information can be found in the
151 \begin_inset Flex Code
154 \begin_layout Plain Layout
160 subfolder of the \SpecialChar LyX
161 source code distribution.
162 This document is not translated, since the development language of \SpecialChar LyX
165 If you just want to use \SpecialChar LyX
166 , then you don't need to read this manual.
167 However, if you want to learn more about how \SpecialChar LyX
168 is developed, or even want
169 to participate in \SpecialChar LyX
170 development, you may find some interesting information
174 \begin_layout Section
178 \begin_layout Standard
180 uses several custom file formats for configuration files and documents.
181 This chapter contains some background concerning these file formats.
182 Several file formats are also described in detail in the regular user documenta
186 \begin_layout Subsection
190 \begin_layout Subsection
191 When is an update of the .lyx file format number needed?
192 \begin_inset CommandInset label
194 name "sec:When-is-an"
201 \begin_layout Standard
202 When you are working on a new feature you may ask yourself whether it needs
203 an update of the .lyx file format number.
204 Whether an update is needed or not is not always obvious.
209 Whenever there is the danger that a previous version of LyX cannot open
210 a file using the new feature, a file format update is needed.
213 \begin_layout Standard
214 The file format change allows lyx2lyx rules to implement backwards compatibility.
215 Below you can find a list of reasons for file format updates with explanations:
218 \begin_layout Description
227 setting Whenever you introduce a new setting that is stored in the document
228 header, a file format update is needed.
231 \begin_layout Description
240 setting If a certain setting becomes obsolete and gets removed, a file format
244 \begin_layout Description
270 \begin_inset space \thinspace{}
277 \begin_layout Description
278 \paragraph_spacing single
291 package The reason for this is that there is no true ERT inset for math
292 formulas: Each command is parsed, and if a user happens to define a local
293 command with the same name as a command that triggers an automatic load
294 of a package, they need to be able to switch off the automatic loading
296 This switch is stored by the
297 \begin_inset Flex Code
300 \begin_layout Plain Layout
309 \begin_layout Description
314 language that is stored in
315 \begin_inset Flex Code
318 \begin_layout Plain Layout
328 \begin_inset Note Note
331 \begin_layout Plain Layout
332 This requirement is under discussion.
341 \begin_layout Description
346 inset Of course a new inset requires a file format update.
349 \begin_layout Description
354 style If a new style or inset layout is added to any layout file or module
355 shipped with \SpecialChar LyX
356 , then a new file format is needed in the master (development)
358 It is possible to backport new styles to the stable version without a file
361 \begin_inset CommandInset ref
363 reference "subsec:Backporting-new-styles"
367 for more information.
370 \begin_layout Description
375 style If a style or inset layout is removed in any layout file or module
376 shipped with \SpecialChar LyX
377 , a new file format is required.
380 \begin_layout Standard
385 layouts and modules do
389 require a file format update (changed 03/16, see
390 \begin_inset CommandInset ref
392 reference "subsec:New-layouts"
400 \begin_layout Standard
401 If you are still unsure, please ask on the development list.
404 \begin_layout Subsection
405 \begin_inset CommandInset label
407 name "subsec:update_lyx_files"
411 How to update the file format number of .lyx files
414 \begin_layout Standard
415 Once you come to the conclusion that a file format update is needed, you
416 should use the following procedure to perform the update:
419 \begin_layout Enumerate
420 Implement and test the new feature, including the reading and writing of
422 Note that any file produced at this stage does not use a valid format,
423 so do not use this version of \SpecialChar LyX
424 for working on any important documents.
427 \begin_layout Enumerate
428 \begin_inset CommandInset label
430 name "enu:Describe_format"
434 Describe the new format in
435 \begin_inset Flex Code
438 \begin_layout Plain Layout
447 \begin_layout Enumerate
448 Update the \SpecialChar LyX
449 file format number in
450 \begin_inset Flex Code
453 \begin_layout Plain Layout
462 \begin_layout Enumerate
463 Update the range of file formats in the array
464 \begin_inset Flex Code
467 \begin_layout Plain Layout
474 \begin_inset Flex Code
477 \begin_layout Plain Layout
486 \begin_layout Enumerate
487 \begin_inset CommandInset label
489 name "enu:Add-an-entry"
493 Add an entry to both format lists (for conversion and reversion) in
494 \begin_inset Newline newline
498 \begin_inset Flex Code
501 \begin_layout Plain Layout
502 lib/lyx2lyx/lyx_2_3.py
508 Add a conversion routine if needed (e.
509 \begin_inset space \thinspace{}
512 g., a new header setting always needs a conversion that adds the new setting,
513 but a new document language does not need one).
514 Add a reversion routine if needed.
516 \begin_inset Newline newline
519 While the conversion routine is required to produce a document that is equivalen
520 t to the old version, the requirements of the reversion are not that strict.
521 If possible, try to produce a proper reversion, using ERT if needed, but
522 for some features this might be too complicated.
523 In this case, the minimum requirement of the reversion routine is that
524 it produces a valid document which can be read by an older \SpecialChar LyX
526 If absolutely needed, even data loss is allowed for the reversion.
527 (In that case, you might want to add a LyX comment that indicates what
528 you have had to do, so the user is at least warned).
531 \begin_layout Enumerate
532 Since tex2lyx has several implicit file format dependencies caused by sharing
533 code with \SpecialChar LyX
534 , updating the file format of .lyx files produced by tex2lyx at
535 the same time as updating the main .lyx file format is strongly recommended.
536 Therefore, a compiler warning will be issued if the \SpecialChar LyX
537 and tex2lyx .lyx file
538 format numbers differ.
539 In many cases the tex2lyx update requires only the first and last item
544 \begin_layout Enumerate
545 Update the tex2lyx file format number in
546 \begin_inset Flex Code
549 \begin_layout Plain Layout
558 \begin_layout Enumerate
559 If the lyx2lyx conversion from the old to the new format is empty, or if
560 tex2lyx does not yet output the changed feature, you do not need any further
562 Otherwise, search for the changed feature in tex2lyx, and adjust the output
563 according to the lyx2lyx changes.
566 \begin_layout Enumerate
567 Update the tex2lyx test references as described in
568 \begin_inset CommandInset ref
569 LatexCommand formatted
570 reference "sec:Updating-test-references"
578 \begin_layout Enumerate
579 If you did not implement full tex2lyx support for the new feature, add a
581 \begin_inset Flex Code
584 \begin_layout Plain Layout
590 describing the missing bits.
591 Note that it is perfectly fine if you do not add full tex2lyx support for
592 a new feature: The updating recommendation above is only issued for the
593 syntax of the produced .lyx file.
594 It is no problem if some features supported by \SpecialChar LyX
595 are still output as ERT
597 The problems in the past that resulted in the update recommendation were
598 related to mixed version syntax, not ERT.
601 \begin_layout Enumerate
602 It would be nice if you could create a .lyx test file which contains instances
603 of all changed or added features.
604 This could then be used to test lyx2lyx and tex2lyx.
605 Unfortunately, it has not yet been decided how to collect such examples,
606 so please ask on the development list if you want to create one.
609 \begin_layout Enumerate
610 \begin_inset CommandInset label
612 name "enu:updatefiles"
616 Update LyX's .lyx documentation files to the new format.
617 The developer who makes the change knows best what changes to expect when
618 inspecting the resulting diff.
619 Because of this, you might be able to catch a bug in the lyx2lyx code that
620 updates the format just by taking a quick scan through the large diff that
622 \begin_inset Note Note
625 \begin_layout Plain Layout
626 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
627 see which layout update made an unexpected change by looking at the git
628 log of a .lyx file that suffers the problem.
633 To do this, first make sure that there are no changes to the git repository
634 that you will not want to commit (this is needed because it will be convenient
635 to commit with the command
636 \begin_inset Flex Code
639 \begin_layout Plain Layout
646 Then run the following command in the root folder of the source:
647 \begin_inset Flex Code
650 \begin_layout Plain Layout
651 python development/tools/updatedocs.py
657 Look at the resulting changes using the command
658 \begin_inset Flex Code
661 \begin_layout Plain Layout
668 If anything looks surprising, please investigate.
669 Keep in mind that the case of
670 \begin_inset Flex Code
673 \begin_layout Plain Layout
679 is special, because it is first generated with
680 \begin_inset Flex Code
683 \begin_layout Plain Layout
689 before being converted to the latest format.
690 Finally, commit using
691 \begin_inset Flex Code
694 \begin_layout Plain Layout
703 \begin_layout Subsection
704 Updating the file format number of layout files
707 \begin_layout Standard
708 The procedure for updating the layout files is similar to that in step
709 \begin_inset CommandInset ref
711 reference "enu:updatefiles"
716 \begin_inset CommandInset ref
718 reference "subsec:update_lyx_files"
724 \begin_inset Flex Code
727 \begin_layout Plain Layout
728 python development/tools/updatelayouts.py
734 \begin_inset Flex Code
737 \begin_layout Plain Layout
746 \begin_layout Standard
747 Note that we do not automatically any local layout used in the
748 \begin_inset Flex Code
751 \begin_layout Plain Layout
757 files shipped with \SpecialChar LyX
758 because users would then not be able to export to older
760 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
761 to open the file in \SpecialChar LyX
762 2.1.x, there would be an error because the file would
763 contain a local layout whose format is too new.
764 The root reason for this is that we do not support converting layouts to
765 older layout formats, as we do for the
766 \begin_inset Flex Code
769 \begin_layout Plain Layout
778 \begin_layout Subsection
779 Updating the file format number of bind/ui files
782 \begin_layout Standard
783 A change to the functionality of existing LFUNs can require a conversion
785 \begin_inset Flex Code
788 \begin_layout Plain Layout
795 \begin_inset Flex Code
798 \begin_layout Plain Layout
804 files, and therefore an increment of the LFUN format, as well as a conversion
806 \begin_inset Flex Code
809 \begin_layout Plain Layout
816 The latter cannot be done automatically and also requires an update of
820 \begin_inset space \space{}
823 of someone who might have made a set of \SpecialChar LyX
824 teaching manuals for use in their
829 \begin_layout Plain Layout
830 \begin_inset Flex URL
833 \begin_layout Plain Layout
835 http://www.lyx.org/trac/ticket/9794
848 \begin_layout Standard
849 To update the LFUN format:
852 \begin_layout Enumerate
853 Increment the LFUN file format number in
854 \begin_inset Flex Code
857 \begin_layout Plain Layout
866 \begin_layout Enumerate
867 Implement the LFUN conversion in
868 \begin_inset Flex Code
871 \begin_layout Plain Layout
872 lib/scripts/prefs2prefs_lfuns.py
880 \begin_layout Enumerate
882 \begin_inset CommandInset ref
884 reference "enu:updatefiles"
889 \begin_inset CommandInset ref
891 reference "subsec:update_lyx_files"
896 \begin_inset Flex Code
899 \begin_layout Plain Layout
905 command, use this command:
906 \begin_inset Flex Code
909 \begin_layout Plain Layout
910 bash development/tools/updatelfuns.sh
917 \begin_inset Note Note
920 \begin_layout Plain Layout
921 This file should really be converted to python.
929 \begin_layout Enumerate
930 Update Info insets in
931 \begin_inset Flex Code
934 \begin_layout Plain Layout
941 To do so, increment the \SpecialChar LyX
942 format and proceed as in
943 \begin_inset CommandInset ref
945 reference "subsec:update_lyx_files"
950 \begin_inset CommandInset ref
952 reference "enu:Describe_format"
957 \begin_inset CommandInset ref
959 reference "enu:updatefiles"
964 In the lyx2lyx implementation (step
965 \begin_inset CommandInset ref
967 reference "enu:Add-an-entry"
971 ), implement a conversion similar to the one in
972 \begin_inset Flex Code
975 \begin_layout Plain Layout
981 above, as well as a corresponding reversion; for this one can use
982 \begin_inset Flex Code
985 \begin_layout Plain Layout
992 \begin_inset Flex Code
995 \begin_layout Plain Layout
996 lib/lyx2lyx/lyx2lyx_tools.py
1005 \begin_layout Subsection
1006 Backporting new styles to the stable version
1007 \begin_inset CommandInset label
1009 name "subsec:Backporting-new-styles"
1016 \begin_layout Standard
1017 Starting with the stable \SpecialChar LyX
1018 2.1 branch, there is a mechanism in place to backport
1019 new styles to the stable version without the need to update the file format.
1020 The basic idea is that the new style definition is automatically copied
1021 to the document preamble so that it can even be used by older minor versions
1022 that did not yet include the style.
1023 To backport a new style to the stable version, the following steps are
1027 \begin_layout Enumerate
1029 \begin_inset Flex Code
1032 \begin_layout Plain Layout
1038 to the style definition in the development version.
1041 \begin_layout Enumerate
1042 Copy the style definition to the stable version, but use
1043 \begin_inset Flex Code
1046 \begin_layout Plain Layout
1053 If needed adjust the format to the one used by the stable version (see
1054 the customization manual for details of the layout file format).
1057 \begin_layout Enumerate
1058 For each update of the style in a later stable version, increase the argument
1060 \begin_inset Flex Code
1063 \begin_layout Plain Layout
1070 (In the stable version, the development version should not be touched.)
1073 \begin_layout Standard
1074 For details about the
1075 \begin_inset Flex Code
1078 \begin_layout Plain Layout
1084 flag see the customization manual.
1086 \begin_inset Flex Code
1089 \begin_layout Plain Layout
1095 support is needed for backported styles: Since the style of the development
1096 version has an infinite version number, it will always be used.
1097 Furthermore, since its version number is less than one, the style will
1098 not be written anymore to the document header for files saved by the new
1102 \begin_layout Section
1103 New layouts and modules
1106 \begin_layout Subsection
1107 \begin_inset CommandInset label
1109 name "subsec:New-layouts"
1116 \begin_layout Standard
1117 Adding a new layout file to the \SpecialChar LyX
1119 \begin_inset Quotes eld
1122 officially supported
1123 \begin_inset Quotes erd
1127 You should therefore think carefully about whether you really want to do
1128 this and discuss it on lyx-devel, since you will need to be prepared to
1129 update and fix the layout if necessary.
1130 If the layout is experimental or for a rarely used document class, then
1131 it may be better to add it to the relevant portion of the \SpecialChar LyX
1135 \begin_inset CommandInset href
1137 target "https://wiki.lyx.org/Layouts/Layouts"
1144 \begin_layout Standard
1145 In older versions of this document, it was stated that new layout files
1146 require a file format change.
1147 After some discussion, it was decided that this is not needed.
1151 \begin_layout Plain Layout
1153 \begin_inset CommandInset href
1155 name "the thread “Proposal for a guide on updating layouts”"
1156 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1169 For reference, here are the arguments on each side
1173 \begin_layout Description
1175 \begin_inset Quotes eld
1178 New layout files are a file format change
1179 \begin_inset Quotes erd
1185 \begin_layout Itemize
1186 All documents produced by 2.2.
1187 \begin_inset Formula $x$
1190 can always be edited and exported even if
1191 \begin_inset Formula $x$
1195 This is important for people using different machines, or exchanging work
1199 \begin_layout Description
1201 \begin_inset Quotes eld
1204 New layout files are not a file format change
1205 \begin_inset Quotes erd
1211 \begin_layout Itemize
1212 No new LaTeX classes can be supported in a stable version, and stable versions
1213 have a typical lifetime of 2–3 years.
1216 \begin_layout Itemize
1217 We have the same situation already with custom layout files: If a document
1218 using a custom layout file is moved between machines or people, then the
1219 layout file needs to be exchanged as well.
1220 If that is not done, then we have a fallback implemented so that such documents
1221 can still be edited, but not exported, and the user gets a warning.
1225 \begin_layout Itemize
1226 The lyx2lyx script cannot do anything useful in such a case.
1230 \begin_layout Standard
1231 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1233 then, you should do the following:
1236 \begin_layout Enumerate
1237 Put your new layout file in
1238 \begin_inset Flex Code
1241 \begin_layout Plain Layout
1248 \begin_inset Flex Code
1251 \begin_layout Plain Layout
1252 git add lib/layouts/newlayout.layout
1257 ) so that it will be committed.
1260 \begin_layout Enumerate
1262 \begin_inset Flex Code
1265 \begin_layout Plain Layout
1271 , so that the new layout actually gets installed.
1274 \begin_layout Enumerate
1276 \begin_inset Flex Code
1279 \begin_layout Plain Layout
1280 lib/doc/LaTeXConfig.lyx
1285 containing in particular a line like
1293 \begin_layout Standard
1294 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1295 \begin_inset Flex Code
1298 \begin_layout Plain Layout
1299 info-insert textclass <name>
1305 This inset will automatically display a boxed
1306 \begin_inset Quotes eld
1310 \begin_inset Quotes erd
1314 \begin_inset Quotes eld
1318 \begin_inset Quotes erd
1321 depending on the availability of the package.
1325 \begin_layout Enumerate
1326 A template or example is strongly encouraged (but not necessarily required).
1327 It is also possible to provide both.
1329 \begin_inset Flex Code
1332 \begin_layout Plain Layout
1339 \begin_inset Flex Code
1342 \begin_layout Plain Layout
1351 \begin_layout Enumerate
1352 Reconfigure \SpecialChar LyX
1356 \begin_layout Enumerate
1357 Ensure the autotests for the new layout pass (see
1358 \begin_inset CommandInset ref
1360 reference "par:when-to-run-an-export-test"
1367 \begin_layout Subsection
1371 \begin_layout Standard
1372 Adding a new module is very similar to adding a new layout.
1373 Therefore, the previous section applies to new modules as well, with two
1377 \begin_layout Enumerate
1378 You only need to add an entry to
1379 \begin_inset Flex Code
1382 \begin_layout Plain Layout
1383 lib/doc/LaTeXConfig.lyx
1388 if the module requires a LaTeX package.
1389 In that case, the command for entering the InsetInfo is:
1390 \begin_inset Flex Code
1393 \begin_layout Plain Layout
1394 \paragraph_spacing single
1395 info-insert package <name>
1403 \begin_layout Enumerate
1404 Modules do not need a template, only an example, which is strongly encouraged
1405 but not necessarily required.
1408 \begin_layout Subsection
1409 Layouts for document classes with incompatible versions
1412 \begin_layout Standard
1413 \begin_inset Note Greyedout
1416 \begin_layout Description
1417 Note: This section is currently only a proposal under discussion.
1418 Please correct/amend as suited.
1419 Remove this note once a consensus is found.
1422 \begin_layout Plain Layout
1424 \begin_inset Quotes eld
1427 Proposal for a guide on updating layouts
1428 \begin_inset Quotes erd
1431 for details and background
1434 \begin_layout Plain Layout
1435 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1443 \begin_layout Standard
1444 Every now and then, there are changes to LaTeX document classes that break
1445 backwards compatibility.
1449 \begin_layout Plain Layout
1450 Uwe has suggested we implement automatic detection of changes in class files.
1451 This could be done by running a script every month that checks if a document
1452 class was changed at CTAN and at the homepages of the scientific journals.
1453 If it reports a change, we can check if our template and layout file are
1454 still usable with the changed document class.
1455 (This is different from the autotests insofar, as this would also catch
1456 changes that do not result in compilation errors.)
1461 Reasons can be a new name for the
1462 \begin_inset Flex Code
1465 \begin_layout Plain Layout
1471 file, removed \SpecialChar LaTeX
1473 How should this best be handled in \SpecialChar LyX
1477 \begin_layout Standard
1478 The idea is to support the new version with a new \SpecialChar LyX
1482 \begin_layout Itemize
1483 Existing documents can still be opened in \SpecialChar LyX
1484 and will continue to work on
1485 systems where the old version is still installed.
1489 \begin_layout Itemize
1490 With differently named
1491 \begin_inset Flex Code
1494 \begin_layout Plain Layout
1500 files, \SpecialChar LyX
1501 can check for the availability of the particular version and reflect
1503 Different document class versions with the same file name are currently
1504 (2.2.x) not detected by the configuration script.
1505 This is planned for 2.3.
1509 \begin_layout Plain Layout
1510 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1513 \begin_layout Plain Layout
1514 However, what we really need is version detection for the configuration,
1515 so that the user can be warned if the required class file has the wrong
1517 (If the class file keeps the name over the version change, only one of
1518 the two layout files generates compilable documents.)
1521 \begin_layout Plain Layout
1522 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1531 \begin_layout Itemize
1532 The new layout can be added both to the master and the stable branches,
1533 in accord with the policy discussed in
1534 \begin_inset CommandInset ref
1535 LatexCommand formatted
1536 reference "subsec:New-layouts"
1541 No lyx2lyx conversion is then required when a new major version is released.
1544 \begin_layout Standard
1545 The user can move an existing document to the new version simply by selecting
1546 a new document class.
1547 This step is well supported by \SpecialChar LyX
1548 , with established methods for handling
1549 unsupported styles and other changes.
1550 This way, no lyx2lyx code is required.
1553 \begin_layout Standard
1554 The steps to support a new version of an existing document class are thus:
1557 \begin_layout Itemize
1558 Create a new layout file including the upstream version in the name (avoid
1559 special characters like spaces and dots), e.g.
1561 \begin_inset Flex Code
1564 \begin_layout Plain Layout
1565 acmsiggraph-v0-92.layout
1573 \begin_layout Itemize
1574 Include the name of the
1575 \begin_inset Flex Code
1578 \begin_layout Plain Layout
1584 file as an optional argument in the
1585 \begin_inset Flex Code
1588 \begin_layout Plain Layout
1596 line and include the version number in the GUI name:
1597 \begin_inset Newline newline
1601 \begin_inset Flex Code
1604 \begin_layout Plain Layout
1607 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1608 \begin_inset space ~
1619 \begin_layout Itemize
1620 Update the GUI name in the old layout file (whose name should not be changed),
1622 \begin_inset Newline newline
1626 \begin_inset Flex Code
1629 \begin_layout Plain Layout
1632 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1633 \begin_inset space ~
1644 \begin_layout Itemize
1645 To avoid duplicate definitions, the new layout can
1646 \begin_inset Flex Code
1649 \begin_layout Plain Layout
1655 the old layout file and add\SpecialChar breakableslash
1656 remove\SpecialChar breakableslash
1657 obsolete\SpecialChar breakableslash
1658 modify settings and styles (similar
1660 \begin_inset Flex Code
1663 \begin_layout Plain Layout
1673 \begin_layout Standard
1674 It may be tempting to let the new layout be the
1675 \begin_inset Quotes eld
1679 \begin_inset Quotes erd
1682 and have the old layout import it.
1683 However, this should not be done because any changes to the new layout
1684 would need undo steps in the importing old layout.
1688 \begin_layout Itemize
1689 If the new LaTeX document class obsoletes the old one, update the example
1690 and template files to use the new layout.
1691 Add a note about the changes (preferably with a pointer to the documentation
1696 \begin_layout Standard
1697 This way, new documents based on the template or example will use the up-to-date
1698 document class version.
1702 \begin_layout Standard
1703 \begin_inset Newpage newpage
1709 \begin_layout Section
1713 \begin_layout Standard
1714 Automated tests are an important tool to detect bugs and regressions in
1715 software development.
1716 Some projects like gcc even require each bug fix to be accompanied by a
1717 test case for the automatic test suite, that would detect this bug.
1718 Testing interactive features automatically is of course very hard, but
1719 core functionality like document import and export can be tested quite
1720 easily, and some tests of this kind exist.
1723 \begin_layout Subsection
1727 \begin_layout Standard
1728 There are attempts to set up a suite of unit tests for LyX.
1731 \begin_layout Standard
1732 TODO: describe what is done and what is still to do.
1735 \begin_layout Subsection
1739 \begin_layout Standard
1740 The tex2lyx tests are located in the
1741 \begin_inset Flex Code
1744 \begin_layout Plain Layout
1750 subfolder of the \SpecialChar LyX
1751 source code distribution.
1752 The actual testing is performed by the simple python script
1753 \begin_inset Flex Code
1756 \begin_layout Plain Layout
1757 src/tex2lyx/test/runtests.py
1763 Each test consists of two files:
1764 \begin_inset Flex Code
1767 \begin_layout Plain Layout
1773 contains the \SpecialChar LaTeX
1774 code that should be tested.
1776 \begin_inset Flex Code
1779 \begin_layout Plain Layout
1785 contains the expected output of tex2lyx.
1786 When a test is run, the actual produced output is compared with the stored
1788 The test passes if both are identical.
1789 The test machinery is also able to generate a file
1790 \begin_inset Flex Code
1793 \begin_layout Plain Layout
1799 by exporting the produced .lyx file with \SpecialChar LyX
1801 This may be useful for roundtrip comparisons.
1804 \begin_layout Subsubsection
1808 \begin_layout Standard
1809 The tex2lyx tests can be run in several ways.
1811 \begin_inset Flex Code
1814 \begin_layout Plain Layout
1820 subfolder of the build directory, the commands
1821 \begin_inset Flex Code
1824 \begin_layout Plain Layout
1830 (cmake, all platforms),
1831 \begin_inset Flex Code
1834 \begin_layout Plain Layout
1840 (cmake, when using a make based build system and not MSVC) or
1841 \begin_inset Flex Code
1844 \begin_layout Plain Layout
1850 (autotools) will run the tex2lyx tests.
1851 Alternatively, in the root of the build directory, the command
1852 \begin_inset Flex Code
1855 \begin_layout Plain Layout
1861 runs all tests whose names match the regex
1862 \begin_inset Quotes eld
1866 \begin_inset Quotes erd
1870 Another way to run the tex2lyx tests in the root build directory is to
1871 instead use the command
1872 \begin_inset Flex Code
1875 \begin_layout Plain Layout
1876 ctest -L '(cmplyx|roundtrip)'
1881 , which runs all tests categorized with the label
1882 \begin_inset Quotes eld
1886 \begin_inset Quotes erd
1890 \begin_inset Quotes eld
1894 \begin_inset Quotes erd
1898 If a test fails, the differences between the expected and actual results
1899 are output in unified diff format.
1902 \begin_layout Subsubsection
1903 Updating test references
1904 \begin_inset CommandInset label
1906 name "sec:Updating-test-references"
1913 \begin_layout Standard
1914 In some cases a changed tex2lyx output is not a test failure, but wanted,
1916 \begin_inset space \thinspace{}
1920 \begin_inset space \space{}
1923 if a tex2lyx bug was fixed, or a new feature was added.
1924 In these cases the stored references need to be updated.
1925 To do so if using autotools, call
1926 \begin_inset Flex Code
1929 \begin_layout Plain Layout
1936 \begin_inset Flex Code
1939 \begin_layout Plain Layout
1945 subdirectory of the build directory.
1946 If instead using CMake, call
1947 \begin_inset Flex Code
1950 \begin_layout Plain Layout
1951 make updatetex2lyxtests
1956 in the build directory or in the
1957 \begin_inset Flex Code
1960 \begin_layout Plain Layout
1966 subdirectory of the build directory.
1970 \begin_layout Plain Layout
1971 Note that this is a case where a make target in the build directory can
1972 affect the source directory, which might not be advisable.
1977 On Windows do the following:
1980 \begin_layout Itemize
1981 Assure that the path to the python.exe is in your system PATH variable.
1984 \begin_layout Itemize
1985 Double-click on the file
1986 \begin_inset Flex Code
1989 \begin_layout Plain Layout
1990 updatetex2lyxtests.vcxproj
1995 in the build directory or in the
1996 \begin_inset Flex Code
1999 \begin_layout Plain Layout
2005 subdirectory of your build directory.
2008 \begin_layout Itemize
2009 In the appearing MSVC program right-click on the project
2013 in the project explorer and chose
2020 \begin_layout Standard
2021 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2023 Please examine the changed output carefully before committing the changed
2024 files to the repository: Since the test machinery does not do a roundtrip
2026 \begin_inset Formula $\Rightarrow$
2030 \begin_inset Formula $\Rightarrow$
2033 .tex, and does not compare the produced dvi or pdf output, it assumes that
2034 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2036 There is only one chance to detect wrong output: before committing a new
2038 Once it is committed, it is quite difficult to verify whether it is correct.
2041 \begin_layout Standard
2046 update the test references by opening them with \SpecialChar LyX
2047 or directly running lyx2lyx
2049 This would not work, since lyx2lyx and \SpecialChar LyX
2050 produce slightly different files
2051 regarding insignificant whitespace and line breaks.
2054 \begin_layout Subsubsection
2058 \begin_layout Standard
2059 In many cases tests for new features may be added to one of the existing
2060 test files, but sometimes this is not possible or not wanted.
2061 Then a new test file needs to be added:
2064 \begin_layout Enumerate
2066 \begin_inset Flex Code
2069 \begin_layout Plain Layout
2070 src/tex2lyx/test/<test name>.tex
2075 and run tex2lyx in roundtrip mode to produce the file
2076 \begin_inset Flex Code
2079 \begin_layout Plain Layout
2080 src/tex2lyx/test/<test name>.lyx.lyx
2086 This file will be the new reference.
2089 \begin_layout Enumerate
2090 Once you confirmed that the tex2lyx output is correct, add the new files
2091 to the corresponding lists in
2092 \begin_inset Flex Code
2095 \begin_layout Plain Layout
2096 src/tex2lyx/test/runtests.py
2102 \begin_inset Flex Code
2105 \begin_layout Plain Layout
2106 src/tex2lyx/Makefile.am
2112 \begin_inset Flex Code
2115 \begin_layout Plain Layout
2116 src/tex2lyx/test/CMakeLists.txt
2124 \begin_layout Enumerate
2125 Commit the changes to the repository, or send a patch to the development
2126 list and ask for committing if you do not have commit rights.
2129 \begin_layout Subsection
2130 ctest automatic tests
2133 \begin_layout Standard
2134 Some tests are located in the
2135 \begin_inset Flex Code
2138 \begin_layout Plain Layout
2139 development/autotests/
2144 subfolder of the \SpecialChar LyX
2145 source code distribution.
2150 \begin_layout Plain Layout
2151 The README document in this folder only describes the
2152 \begin_inset Quotes eld
2156 \begin_inset Quotes erd
2159 subset of autotests!
2167 \begin_layout Standard
2168 These tests can be run by the commands
2169 \begin_inset Flex Code
2172 \begin_layout Plain Layout
2182 (all platforms) or (when using a make based build system and not MSVC)
2184 \begin_inset Flex Code
2187 \begin_layout Plain Layout
2194 \begin_inset Flex Code
2197 \begin_layout Plain Layout
2208 The test logs are written to the
2209 \begin_inset Flex Code
2212 \begin_layout Plain Layout
2226 \begin_layout Subsubsection
2230 \begin_layout Standard
2231 The export tests are integration tests.
2232 They take longer to run and are more likely to break than the tex2lyx tests.
2233 Nevertheless, they have caught many regressions and without a better alternativ
2234 e it is important to keep them up-to-date and understand how they work.
2237 \begin_layout Standard
2239 \begin_inset Quotes eld
2243 \begin_inset Quotes erd
2246 documentation, template, and example documents.
2247 In addition, there are a number of dedicated sample documents in the
2248 \begin_inset Flex Code
2251 \begin_layout Plain Layout
2257 subfolder of the \SpecialChar LyX
2258 source code distribution.
2259 All samples are (after copying and eventual processing by scripts) exported
2260 to various output formats via the
2261 \begin_inset Flex Code
2264 \begin_layout Plain Layout
2270 command line option.
2271 The tests checks for errors reported by LyX.
2272 (However, error-free export is no guarantee for an error-free output document.)
2275 \begin_layout Paragraph
2276 \begin_inset CommandInset label
2278 name "par:when-to-run-an-export-test"
2282 Expectations of LyX developers
2285 \begin_layout Standard
2286 Because the export tests are integration tests and take a long time to run,
2287 LyX developers are rarely expected to run all of the tests.
2288 Here are some good practices to follow by developers:
2291 \begin_layout Itemize
2292 When making a non-trivial change to a .layout file, run the export and layout
2293 tests corresponding with that .layout file.
2296 \begin_layout Itemize
2297 When making non-trivial changes to a .lyx file, run the export tests correspondin
2298 g to that .lyx file.
2303 \begin_layout Plain Layout
2304 This rule is due to revision.
2308 \begin_layout Plain Layout
2309 There is an objection from the documentation maintainer that working on
2310 the documentation must not be complicated by having to consider non-standard
2314 \begin_layout Itemize
2315 successful compiling/testing an edited documentation file with pdflatex
2316 suffices to ensure it can be commited, not tests with other exports are
2320 \begin_layout Plain Layout
2321 If sudden failures with other exports due to “half-tested” documentation
2322 updates are a problem for the test maintainer, the test suite should use
2326 \begin_layout Itemize
2327 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2330 \begin_layout Itemize
2331 updated regularely (but on a time chosen by the test suite maintainer) from
2332 the originals in lib/doc/
2335 \begin_layout Plain Layout
2339 \begin_layout Itemize
2340 no test will fail due to ongoing work on documentation,
2343 \begin_layout Itemize
2344 the documentation is still tested in full (with some delay),
2347 \begin_layout Itemize
2348 failures with non-default export can be examined and handled accordingly
2349 in one run with the cache update,
2352 \begin_layout Itemize
2353 “interesting failures” (like the nested-language+polyglossia problem in
2354 es/Customization can be separated and moved into dedicated test samples.
2362 \begin_layout Itemize
2363 When making non-trivial changes to LyX's \SpecialChar LaTeX
2365 touching the encoding code or package handling code that you expect will
2366 change the exported \SpecialChar LaTeX
2371 \begin_layout Standard
2372 \paragraph_spacing single
2373 Consider running all of the export tests before and after your change.
2374 If there are differences, please reconcile these (i.e.
2375 fix the bug or fix the tests)
2380 Ask for help if you're not sure what to.
2383 \begin_layout Standard
2384 If you do not want to run the tests,
2387 \begin_layout Itemize
2388 post the patch on the list and others will run the tests and eventually
2392 \begin_layout Itemize
2393 commit, but be prepared to fix eventually arising problems or to revert
2394 the commit if there is no easy fix.
2398 \begin_layout Itemize
2399 Understand how to interpret test failures.
2400 If your commit is found to have broken a test, you should be able to interpret
2401 the test results when made aware of them.
2403 \begin_inset CommandInset ref
2405 reference "subsec:Interpreting-export-tests"
2412 \begin_layout Paragraph
2413 \begin_inset CommandInset label
2415 name "par:export-test-output-formats"
2422 \begin_layout Standard
2423 The following output formats are currently tested for each sample document
2425 \begin_inset CommandInset ref
2427 reference "par:Export-test-filtering"
2434 \begin_layout Labeling
2435 \labelwidthstring 00.00.0000
2440 \begin_layout Labeling
2441 \labelwidthstring 00.00.0000
2442 lyx16 LyX 1.6 file format (lyx2lyx)
2445 \begin_layout Labeling
2446 \labelwidthstring 00.00.0000
2447 lyx21 LyX 2.1 file format (lyx2lyx)
2450 \begin_layout Labeling
2451 \labelwidthstring 00.00.0000
2452 xhtml LyXHTML (native LyX HTML export)
2456 \begin_layout Labeling
2457 \labelwidthstring 00.00.0000
2459 \begin_inset space ~
2463 \begin_inset space ~
2470 \begin_layout Labeling
2471 \labelwidthstring pdf5msystemFM
2472 dvi DVI (8-bit latex)
2475 \begin_layout Labeling
2476 \labelwidthstring pdf5msystemFM
2477 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2480 \begin_layout Labeling
2481 \labelwidthstring pdf5msystemFM
2482 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2485 \begin_layout Labeling
2486 \labelwidthstring pdf5msystemFM
2490 \begin_layout Labeling
2491 \labelwidthstring pdf5msystemFM
2492 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2495 \begin_layout Labeling
2496 \labelwidthstring pdf5msystemFM
2497 pdf4_systemF PDF (XeTeX with Unicode fonts)
2500 \begin_layout Labeling
2501 \labelwidthstring pdf5msystemFM
2502 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2505 \begin_layout Labeling
2506 \labelwidthstring pdf5msystemFM
2507 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2511 \begin_layout Labeling
2512 \labelwidthstring 00.00.0000
2514 \begin_inset space ~
2518 \begin_inset space ~
2522 \begin_inset space ~
2526 \begin_inset space ~
2533 \begin_layout Labeling
2534 \labelwidthstring pdf5msystemFM
2535 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2538 \begin_layout Labeling
2539 \labelwidthstring pdf5msystemFM
2540 pdf3 DVI -> PDF (dvipdfm)
2544 \begin_layout Labeling
2545 \labelwidthstring 00.00.0000
2547 \begin_inset space ~
2550 tested: (or only if set as default output format in the document source)
2554 \begin_layout Labeling
2555 \labelwidthstring pdf5msystemFM
2559 \begin_layout Labeling
2560 \labelwidthstring pdf5msystemFM
2561 luatex LaTeX (LuaTeX)
2564 \begin_layout Labeling
2565 \labelwidthstring pdf5msystemFM
2566 dviluatex LaTeX (dviluatex)
2569 \begin_layout Labeling
2570 \labelwidthstring pdf5msystemFM
2571 pdflatex LaTeX (pdflatex)
2574 \begin_layout Labeling
2575 \labelwidthstring pdf5msystemFM
2576 platex LaTeX (pLaTeX)
2579 \begin_layout Labeling
2580 \labelwidthstring pdf5msystemFM
2584 \begin_layout Labeling
2585 \labelwidthstring pdf5msystemFM
2586 eps3 EPS (encapsulated Postscript) (cropped)
2589 \begin_layout Labeling
2590 \labelwidthstring pdf5msystemFM
2591 ps DVI -> Postscript (dvips)
2594 \begin_layout Labeling
2595 \labelwidthstring pdf5msystemFM
2599 \begin_layout Labeling
2600 \labelwidthstring pdf5msystemFM
2601 text (nor text2, ..., text4)
2604 \begin_layout Labeling
2605 \labelwidthstring pdf5msystemFM
2609 \begin_layout Labeling
2610 \labelwidthstring pdf5msystemFM
2614 \begin_layout Labeling
2615 \labelwidthstring pdf5msystemFM
2619 \begin_layout Labeling
2620 \labelwidthstring pdf5msystemFM
2625 \begin_layout Paragraph
2626 \begin_inset CommandInset label
2628 name "par:Configuring-ctests"
2632 Configuring the tests
2635 \begin_layout Standard
2636 To enable the export autotests, add the
2637 \begin_inset Flex Code
2640 \begin_layout Plain Layout
2641 -DLYX_ENABLE_EXPORT_TESTS=ON
2650 \begin_layout Standard
2651 \begin_inset Flex Code
2654 \begin_layout Plain Layout
2655 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2663 \begin_layout Standard
2665 This flag will increase the time for the cmake command by several seconds,
2666 mainly because of the process of inverting tests (see Section
2667 \begin_inset CommandInset ref
2669 reference "subsec:Interpreting-export-tests"
2676 \begin_layout Paragraph
2677 \begin_inset CommandInset label
2679 name "par:ctest-options"
2686 \begin_layout Standard
2687 To run all tests, in the build directory simply run the command
2688 \begin_inset Flex Code
2691 \begin_layout Plain Layout
2698 A full, up-to-date TeXLive installation is recommended to run the tests.
2699 Otherwise, some tests will fail.
2700 Tests with additional requirements are labeled
2701 \begin_inset Quotes eld
2704 unreliable:nonstandard
2705 \begin_inset Quotes erd
2712 \begin_layout Standard
2713 To run only some of the tests, use command line options (see examples below):
2716 \begin_layout Labeling
2717 \labelwidthstring -R
2718 \begin_inset Flex Code
2721 \begin_layout Plain Layout
2727 Run only the tests whose names match the given regular expression.
2730 \begin_layout Labeling
2731 \labelwidthstring -R
2732 \begin_inset Flex Code
2735 \begin_layout Plain Layout
2741 Run only the tests whose labels match the given regular expression.
2742 A test may have more that one label.
2746 \begin_layout Labeling
2747 \labelwidthstring -R
2748 \begin_inset Flex Code
2751 \begin_layout Plain Layout
2757 Exclude the tests whose names match the given regular expression.
2760 \begin_layout Labeling
2761 \labelwidthstring -R
2762 \begin_inset Flex Code
2765 \begin_layout Plain Layout
2771 Exclude the tests whose labels match the given regular expression.
2772 Cannot be combined with
2773 \begin_inset Flex Code
2776 \begin_layout Plain Layout
2785 \begin_layout Standard
2786 The following options help to find good selection patterns:
2789 \begin_layout Labeling
2790 \labelwidthstring -R
2791 \begin_inset Flex Code
2794 \begin_layout Plain Layout
2800 List the tests that would be run but not actually run them.
2805 \begin_layout Standard
2806 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2807 to know how many tests there are or whether your
2808 \begin_inset Flex Code
2811 \begin_layout Plain Layout
2817 regular expression did what you expected.
2821 \begin_layout Labeling
2822 \labelwidthstring -R
2823 \begin_inset Flex Code
2826 \begin_layout Plain Layout
2827 \SpecialChar nobreakdash
2828 \SpecialChar nobreakdash
2834 print the list of all labels associated with the test set.
2835 Can also be combined with -R, -L, -E, ...
2839 \begin_layout Standard
2840 Other useful options are:
2843 \begin_layout Labeling
2844 \labelwidthstring -R
2845 \begin_inset Flex Code
2848 \begin_layout Plain Layout
2854 Run the tests in parallel using the given number of jobs.
2858 \begin_layout Standard
2859 We are still working on getting the tests to run in parallel.
2860 However, when running the tests in parallel, sometimes tests fail that
2861 pass when run sequentially.
2862 A reasonable approach is to first run the tests in parallel and then run
2863 the failed tests sequentially.
2866 \begin_layout Standard
2867 For example, to run 8 jobs at a time:
2870 \begin_layout Standard
2871 \begin_inset Flex Code
2874 \begin_layout Plain Layout
2883 \begin_layout Standard
2884 \begin_inset Flex Code
2887 \begin_layout Plain Layout
2888 ctest \SpecialChar nobreakdash
2889 \SpecialChar nobreakdash
2898 \begin_layout Standard
2899 When specifying a subset of the tests (e.g.
2901 \begin_inset Flex Code
2904 \begin_layout Plain Layout
2905 \SpecialChar nobreakdash
2911 ), the same subset must be specified when using the
2912 \begin_inset Flex Code
2915 \begin_layout Plain Layout
2916 \SpecialChar nobreakdash
2917 \SpecialChar nobreakdash
2923 option because it is the test numbers that are used to index which tests
2924 failed on the previous run.
2927 \begin_layout Standard
2929 Note that some tests cannot be run in parallel.
2930 These tests are marked in the code with the
2931 \begin_inset Flex Code
2934 \begin_layout Plain Layout
2945 \begin_layout Labeling
2946 \labelwidthstring -R
2947 \begin_inset Flex Code
2950 \begin_layout Plain Layout
2951 \SpecialChar nobreakdash
2952 \SpecialChar nobreakdash
2958 Set a global timeout on all tests that do not already have a timeout set
2963 \begin_layout Standard
2964 There have been bugs in LyX and in \SpecialChar LaTeX
2965 which cause compilation to hang, and
2966 without a timeout a test might never stop (in one case there was even a
2968 If a test times out, the
2969 \begin_inset Flex Code
2972 \begin_layout Plain Layout
2978 command exits with error, but you can distinguish between a timed out test
2979 and a failed test in the output reported at the end of the
2980 \begin_inset Flex Code
2983 \begin_layout Plain Layout
2993 \begin_layout Standard
2995 \begin_inset Flex Code
2998 \begin_layout Plain Layout
3004 ) the full list of command line options.
3007 \begin_layout Paragraph
3011 \begin_layout Itemize
3012 run only the export tests:
3013 \begin_inset Flex Code
3016 \begin_layout Plain Layout
3025 \begin_layout Itemize
3027 \begin_inset Flex Code
3030 \begin_layout Plain Layout
3031 ctest -L "inverted|suspended"
3039 \begin_layout Itemize
3040 list all export tests which match any of the labelling patterns:
3041 \begin_inset Flex Code
3044 \begin_layout Plain Layout
3055 \begin_layout Itemize
3056 exclude rarely used output formats and post-processing tests
3057 \begin_inset Flex Code
3060 \begin_layout Plain Layout
3061 ctest -L export -E "_(texF|dvi3|pdf3?)"
3069 \begin_layout Paragraph
3070 \begin_inset CommandInset label
3072 name "subsec:Interpreting-export-tests"
3076 Interpreting the export test results
3079 \begin_layout Standard
3080 A test can fail for several reasons, not all of them bad.
3083 \begin_layout Enumerate
3084 A new or edited sample document may be incompatible with some output formats.
3087 \begin_layout Enumerate
3088 A dependency is not met (e.g.
3089 the \SpecialChar LaTeX
3091 One hint that this is the case is that the corresponding
3092 \begin_inset Flex Code
3095 \begin_layout Plain Layout
3101 test will likely also fail.
3104 \begin_layout Enumerate
3105 An inverted test fails to fail (i.e.
3106 export that previously failed now works).
3109 \begin_layout Enumerate
3110 An external dependency was updated (e.g.
3115 \begin_layout Enumerate
3116 A recent code change introduced a bug.
3119 \begin_layout Enumerate
3120 \begin_inset CommandInset label
3126 A change in a document exposed a previously unknown bug or an incompatibility
3127 with an export format (e.g.
3128 Lua\SpecialChar LaTeX
3132 \begin_layout Standard
3133 Because the .lyx files are exported in several formats, it is not surprising
3134 that many of the exports fail.
3135 This expectation of failure is addressed by
3136 \begin_inset Quotes eld
3140 \begin_inset Quotes erd
3143 the tests, that is, by marking the test as
3144 \begin_inset Quotes eld
3148 \begin_inset Quotes erd
3151 if the export exits with error and as
3152 \begin_inset Quotes eld
3156 \begin_inset Quotes erd
3159 if the export succeeds
3164 It follows that these expected failures will not show up as failed tests
3165 in the test results and thus will not pollute the
3166 \begin_inset Quotes eld
3170 \begin_inset Quotes erd
3174 If the export actually succeeds, then the test will fail.
3175 The purpose of this failure is to get your attention—something has changed,
3176 possibly for the better.
3179 \begin_layout Standard
3180 We try to document why a test is inverted or ignored.
3181 See the comment (prefixed with
3182 \begin_inset Flex Code
3185 \begin_layout Plain Layout
3191 ) above the block in which the test is listed as inverted or ignored in
3193 \begin_inset Flex Code
3196 \begin_layout Plain Layout
3197 development/autotests/invertedTests
3203 \begin_inset Flex Code
3206 \begin_layout Plain Layout
3207 development/autotests/unreliableTests
3213 \begin_inset Flex Code
3216 \begin_layout Plain Layout
3217 development/autotests/ignoredTests
3226 \begin_layout Standard
3227 A good question is why do we enable the tests for non-default formats? The
3228 answer is that if a non-default route is broken it is often because a bug
3229 was introduced in LyX and not because a document-specific change was made
3230 that is not supported by the route.
3231 In other words, there is a high signal/noise ratio in the export tests
3232 for some non-default formats.
3236 \begin_layout Standard
3237 When a test or several tests fail, consider checking the files in the
3238 \begin_inset Flex Code
3241 \begin_layout Plain Layout
3247 subdirectory of your build directory.
3248 In this subdirectory are three files: the file
3249 \begin_inset Flex Code
3252 \begin_layout Plain Layout
3258 simply lists the tests that failed on your last
3259 \begin_inset Flex Code
3262 \begin_layout Plain Layout
3269 \begin_inset Flex Code
3272 \begin_layout Plain Layout
3278 file contains the output from the tests (and often has details explaining
3279 why a test failed); and the
3280 \begin_inset Flex Code
3283 \begin_layout Plain Layout
3289 file lists the times that it took to run the tests.
3292 \begin_layout Paragraph
3293 What action should you take if a test fails?
3296 \begin_layout Standard
3297 \paragraph_spacing single
3298 It is always good to check manually why something fails and if it passes
3299 if the PDF output is good.
3302 \begin_layout Itemize
3303 Generally, if a change breaks compilation for the target format (for the
3304 manuals pdf2) without solving some important other issue,
3306 fix or revert the commit
3308 that led to failure.
3311 \begin_layout Itemize
3312 If it is not possible to (immediately) fix the failure but there are reasons
3313 not to revert the commit (e.g.
3314 it fixes another more important issue),
3318 the failing test case (see
3319 \begin_inset CommandInset ref
3321 reference "par:Inverted-tests"
3328 \begin_layout Itemize
3333 test case fails because the export now works,
3337 the test by removing the pattern from the
3338 \begin_inset Quotes eld
3342 \begin_inset Quotes erd
3346 \begin_inset CommandInset ref
3348 reference "par:Inverted-tests"
3355 \begin_layout Itemize
3356 If the export did not fail previously but led to wrong output (PDF, say),
3360 \begin_layout Plain Layout
3361 Non-failing test with wrong output should be labeledas
3362 \begin_inset Quotes eld
3365 unreliable:wrong_output
3366 \begin_inset Quotes erd
3370 \begin_inset CommandInset ref
3372 reference "par:Unreliable-tests"
3381 it is in fact an improvement when the test now fails.
3386 the failing test case (see
3387 \begin_inset CommandInset ref
3389 reference "par:Inverted-tests"
3396 \begin_layout Itemize
3397 In case of tests failing due to missing requirements (tests labeled
3398 \begin_inset Quotes eld
3401 unreliable:nonstandard
3402 \begin_inset Quotes erd
3405 or testing on a system with only a subset of TeXLive installed), ignore
3406 the failure, ask for someone else to run the test, or install the missing
3407 resources and try again.
3410 \begin_layout Itemize
3411 Check the log file Testing/Temporary/LastTest.log.
3412 In case of latex-errors rerun the failing test with environment variable
3413 'LAX_DEBUG_LATEX' set to '1'.
3414 This will include latex messages in LastTest.log, so it should be easier
3415 to interpret the fail-reason.
3418 \begin_layout Paragraph
3419 \begin_inset CommandInset label
3421 name "par:Inverted-tests"
3428 \begin_layout Standard
3429 Test cases whose name matches a pattern in the file
3430 \begin_inset Flex Code
3433 \begin_layout Plain Layout
3434 development/autotests/invertedTests
3444 They get also the test property
3445 \begin_inset Flex Code
3448 \begin_layout Plain Layout
3455 they are reported as failing if the export works without error
3456 \begin_inset Flex URL
3459 \begin_layout Plain Layout
3461 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3469 \begin_layout Standard
3470 Add failing cases to this file, if they cannot be solved
3471 \begin_inset Quotes eld
3475 \begin_inset Quotes erd
3478 but it is expected that the export will work in a foreseeable future, e.g.
3479 low priority issues like failures to export to a non-target format (for
3480 the manuals everything except pdf2).
3483 \begin_layout Standard
3484 The following sublabels are currently present in
3485 \begin_inset Flex Code
3488 \begin_layout Plain Layout
3497 \begin_layout Description
3498 todo test failures that require attention:
3502 \begin_layout Itemize
3503 minor issues to explore and properly sort later,
3506 \begin_layout Itemize
3510 \begin_layout Itemize
3511 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3515 \begin_layout Description
3516 lyxbugs LyX bugs with a Trac number.
3519 \begin_layout Description
3520 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3524 \begin_layout Standard
3525 "Wontfix" if demonstrating correct use and OK in the default output format.
3529 \begin_layout Description
3530 texissues Export fails due to LaTeX limitations like non-ASCII characters
3531 in verbatim or listings, incompatible packages, ...
3535 \begin_layout Standard
3536 "Wontfix" if documents demonstrate correct use in the default output format:
3539 \begin_layout Itemize
3540 If the source can be made more robust without becoming "hackish", fix the
3544 \begin_layout Itemize
3545 if LyX could be enhanced to care for a permanent TeX limitation, file a
3546 ticket at trac and add a pattern under lyxbugs,
3549 \begin_layout Itemize
3550 otherwise, add a pattern here.
3554 \begin_layout Description
3555 attic Documents in the attic (kept for reference and format conversion test).
3557 \begin_inset Quotes eld
3561 \begin_inset Quotes erd
3567 \begin_layout Subparagraph
3571 \begin_layout Standard
3572 Test cases whose name additionally matches a pattern in the file
3573 \begin_inset Flex Code
3576 \begin_layout Plain Layout
3577 development/autotests/suspendedTests
3595 This means they are not executed using
3596 \begin_inset Flex Code
3599 \begin_layout Plain Layout
3606 \begin_inset Flex Code
3609 \begin_layout Plain Layout
3616 However, they also get the test property
3617 \begin_inset Flex Code
3620 \begin_layout Plain Layout
3627 they are reported as failing if the export works without error.
3628 From time to time they still have to be checked using
3629 \begin_inset Flex Code
3632 \begin_layout Plain Layout
3641 \begin_layout Standard
3642 These tests are suspended, because the export fails for known reasons which
3643 cannot ATM be resolved.
3644 But it is expected the reason might disappear in the future.
3645 Be it new TL or better handling in \SpecialChar LyX
3649 \begin_layout Standard
3650 For ctest commands without the
3651 \begin_inset Flex Code
3654 \begin_layout Plain Layout
3660 parameter nothing changes.
3661 Suspended or not, tests will be executed depending only on the selecting
3662 regular expression given to the ctest command (see
3663 \begin_inset CommandInset ref
3665 reference "par:ctest-options"
3672 \begin_layout Paragraph
3673 \begin_inset CommandInset label
3675 name "par:Unreliable-tests"
3682 \begin_layout Standard
3683 Test cases whose name matches a pattern in the file
3684 \begin_inset Flex Code
3687 \begin_layout Plain Layout
3688 development/autotests/unreliableTests
3700 \begin_layout Standard
3701 These tests are not executed using
3702 \begin_inset Flex Code
3705 \begin_layout Plain Layout
3712 \begin_inset Flex Code
3715 \begin_layout Plain Layout
3725 \begin_layout Standard
3726 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3727 or pass but should rather fail (wrong output).
3729 \begin_inset Note Note
3732 \begin_layout Plain Layout
3733 *invalid* tests (wrong output) are not *unreliable*.
3734 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3743 \begin_layout Standard
3744 The following sublabels are currently present in
3745 \begin_inset Flex Code
3748 \begin_layout Plain Layout
3757 \begin_layout Description
3758 nonstandard Documents with additional requirements, e.g.
3759 a class or package file not in TeXLive.
3761 \begin_inset Note Note
3764 \begin_layout Plain Layout
3766 \begin_inset Quotes eld
3770 \begin_inset Quotes erd
3774 \begin_inset Quotes eld
3778 \begin_inset Quotes erd
3789 \begin_layout Description
3790 erratic Tests depending on local configuration or the phase of the moon.
3794 \begin_layout Description
3795 varying_versions Test depending on TeX distribution, package versions or
3799 \begin_layout Description
3801 \begin_inset space ~
3804 output Export does not fail but the resulting document has (undetected)
3809 \begin_layout Standard
3810 \paragraph_spacing single
3811 \begin_inset Note Note
3814 \begin_layout Plain Layout
3815 \paragraph_spacing single
3816 These tests are in a strict sense not unreliable but
3820 (not measuring what they should measure).
3829 \begin_layout Paragraph
3830 \begin_inset CommandInset label
3832 name "par:Export-test-filtering"
3836 Export test filtering
3839 \begin_layout Standard
3840 The assignment of a label to a test is controlled by a set of files with
3841 regular expressions that are matched against the test names.
3844 \begin_layout Description
3845 ignoredTests (small file)
3846 \begin_inset Newline newline
3849 Tests selected here are withdrawn in the configuration step (cf.
3851 \begin_inset CommandInset ref
3853 reference "par:Configuring-ctests"
3861 \begin_layout Labeling
3862 \labelwidthstring 00.00.0000
3863 Input Test of any export combination
3866 \begin_layout Labeling
3867 \labelwidthstring 00.00.0000
3868 Output Stop if tests not selected here
3872 \begin_layout Description
3873 unreliableTests: Tests selected pass or fail dependent on the system where
3875 Selected tests gain the label 'unreliable'.
3879 \begin_layout Labeling
3880 \labelwidthstring 00.00.0000
3881 Input Each test which passed 'ignoredTests'
3884 \begin_layout Labeling
3885 \labelwidthstring 00.00.0000
3886 Output Stop if test selected, gain label 'unreliable'.
3890 \begin_layout Description
3892 \begin_inset space \space{}
3899 \begin_layout Labeling
3900 \labelwidthstring 00.00.0000
3901 Input Each test which passed 'unreliableTests'
3904 \begin_layout Labeling
3905 \labelwidthstring 00.00.0000
3906 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3907 tests are reported as failing if the export works without error.) If no
3908 subselection applies, gain labels 'export' and 'inverted'.
3911 \begin_layout Standard
3912 The following filter perfoms a subselection of 'invertedTests':
3915 \begin_layout Description
3916 suspendedTests Tests selected here gain the label 'suspended' but _not_
3917 'export' or 'inverted', although in ctest they remain inverted.
3918 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3922 \begin_layout Labeling
3923 \labelwidthstring 00.00.0000
3924 Input Each test selected by 'invertedTests'
3927 \begin_layout Labeling
3928 \labelwidthstring 00.00.0000
3929 Output Selected test gains label 'suspended'.
3935 \begin_layout Standard
3936 The following table may clarify label assignement
3939 \begin_layout Standard
3940 \begin_inset Tabular
3941 <lyxtabular version="3" rows="7" columns="9">
3942 <features tabularvalignment="middle">
3943 <column alignment="left" valignment="top" width="0pt">
3944 <column alignment="left" valignment="top" width="0pt">
3945 <column alignment="left" valignment="top" width="0pt">
3946 <column alignment="left" valignment="top" width="0pt">
3947 <column alignment="center" valignment="top">
3948 <column alignment="center" valignment="top">
3949 <column alignment="center" valignment="top">
3950 <column alignment="center" valignment="top">
3951 <column alignment="center" valignment="top">
3953 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3956 \begin_layout Plain Layout
3957 Test matching pattern in file:
3962 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3965 \begin_layout Plain Layout
3971 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3974 \begin_layout Plain Layout
3980 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3983 \begin_layout Plain Layout
3989 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3992 \begin_layout Plain Layout
3998 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4001 \begin_layout Plain Layout
4007 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4010 \begin_layout Plain Layout
4016 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4019 \begin_layout Plain Layout
4025 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4028 \begin_layout Plain Layout
4036 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4039 \begin_layout Plain Layout
4045 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4048 \begin_layout Plain Layout
4054 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4057 \begin_layout Plain Layout
4063 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4066 \begin_layout Plain Layout
4072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4075 \begin_layout Plain Layout
4081 <cell alignment="center" valignment="top" topline="true" usebox="none">
4084 \begin_layout Plain Layout
4090 <cell alignment="center" valignment="top" topline="true" usebox="none">
4093 \begin_layout Plain Layout
4099 <cell alignment="center" valignment="top" topline="true" usebox="none">
4102 \begin_layout Plain Layout
4108 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4111 \begin_layout Plain Layout
4119 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4122 \begin_layout Plain Layout
4128 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4131 \begin_layout Plain Layout
4137 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4140 \begin_layout Plain Layout
4146 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4149 \begin_layout Plain Layout
4155 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4158 \begin_layout Plain Layout
4164 <cell alignment="center" valignment="top" topline="true" usebox="none">
4167 \begin_layout Plain Layout
4173 <cell alignment="center" valignment="top" topline="true" usebox="none">
4176 \begin_layout Plain Layout
4182 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4185 \begin_layout Plain Layout
4191 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4194 \begin_layout Plain Layout
4202 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4205 \begin_layout Plain Layout
4211 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4214 \begin_layout Plain Layout
4220 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4223 \begin_layout Plain Layout
4229 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4232 \begin_layout Plain Layout
4238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4241 \begin_layout Plain Layout
4247 <cell alignment="center" valignment="top" topline="true" usebox="none">
4250 \begin_layout Plain Layout
4256 <cell alignment="center" valignment="top" topline="true" usebox="none">
4259 \begin_layout Plain Layout
4265 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4268 \begin_layout Plain Layout
4274 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4277 \begin_layout Plain Layout
4285 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4288 \begin_layout Plain Layout
4294 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4297 \begin_layout Plain Layout
4303 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4306 \begin_layout Plain Layout
4312 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4315 \begin_layout Plain Layout
4321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4324 \begin_layout Plain Layout
4330 <cell alignment="center" valignment="top" topline="true" usebox="none">
4333 \begin_layout Plain Layout
4339 <cell alignment="center" valignment="top" topline="true" usebox="none">
4342 \begin_layout Plain Layout
4348 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4351 \begin_layout Plain Layout
4357 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4360 \begin_layout Plain Layout
4368 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4371 \begin_layout Plain Layout
4377 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4380 \begin_layout Plain Layout
4386 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4389 \begin_layout Plain Layout
4395 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4398 \begin_layout Plain Layout
4404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4407 \begin_layout Plain Layout
4413 <cell alignment="center" valignment="top" topline="true" usebox="none">
4416 \begin_layout Plain Layout
4422 <cell alignment="center" valignment="top" topline="true" usebox="none">
4425 \begin_layout Plain Layout
4431 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4434 \begin_layout Plain Layout
4440 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4443 \begin_layout Plain Layout
4451 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4454 \begin_layout Plain Layout
4460 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4463 \begin_layout Plain Layout
4469 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4472 \begin_layout Plain Layout
4478 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4481 \begin_layout Plain Layout
4487 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4490 \begin_layout Plain Layout
4496 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4499 \begin_layout Plain Layout
4505 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4508 \begin_layout Plain Layout
4514 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4517 \begin_layout Plain Layout
4523 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4526 \begin_layout Plain Layout
4540 \begin_layout Standard
4541 \begin_inset Note Note
4544 \begin_layout Plain Layout
4546 \begin_inset Quotes eld
4550 \begin_inset Quotes erd
4553 filter, this would be far less complicated:
4556 \begin_layout Plain Layout
4557 \begin_inset Tabular
4558 <lyxtabular version="3" rows="6" columns="7">
4559 <features tabularvalignment="middle">
4560 <column alignment="left" valignment="top" width="0pt">
4561 <column alignment="left" valignment="top" width="0pt">
4562 <column alignment="left" valignment="top" width="0pt">
4563 <column alignment="center" valignment="top">
4564 <column alignment="center" valignment="top">
4565 <column alignment="center" valignment="top">
4566 <column alignment="center" valignment="top">
4568 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4571 \begin_layout Plain Layout
4572 Test matching pattern in file:
4577 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4580 \begin_layout Plain Layout
4586 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4589 \begin_layout Plain Layout
4595 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4598 \begin_layout Plain Layout
4604 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4607 \begin_layout Plain Layout
4613 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4616 \begin_layout Plain Layout
4622 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4625 \begin_layout Plain Layout
4633 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4636 \begin_layout Plain Layout
4642 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4645 \begin_layout Plain Layout
4651 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4654 \begin_layout Plain Layout
4660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4663 \begin_layout Plain Layout
4669 <cell alignment="center" valignment="top" topline="true" usebox="none">
4672 \begin_layout Plain Layout
4678 <cell alignment="center" valignment="top" topline="true" usebox="none">
4681 \begin_layout Plain Layout
4687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4690 \begin_layout Plain Layout
4698 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4701 \begin_layout Plain Layout
4707 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4710 \begin_layout Plain Layout
4716 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4719 \begin_layout Plain Layout
4725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4728 \begin_layout Plain Layout
4734 <cell alignment="center" valignment="top" topline="true" usebox="none">
4737 \begin_layout Plain Layout
4743 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4746 \begin_layout Plain Layout
4752 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4755 \begin_layout Plain Layout
4763 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4766 \begin_layout Plain Layout
4772 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4775 \begin_layout Plain Layout
4781 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4784 \begin_layout Plain Layout
4790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4793 \begin_layout Plain Layout
4799 <cell alignment="center" valignment="top" topline="true" usebox="none">
4802 \begin_layout Plain Layout
4808 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4811 \begin_layout Plain Layout
4817 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4820 \begin_layout Plain Layout
4828 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4831 \begin_layout Plain Layout
4837 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4840 \begin_layout Plain Layout
4846 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4849 \begin_layout Plain Layout
4855 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4858 \begin_layout Plain Layout
4864 <cell alignment="center" valignment="top" topline="true" usebox="none">
4867 \begin_layout Plain Layout
4873 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4876 \begin_layout Plain Layout
4882 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4885 \begin_layout Plain Layout
4893 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4896 \begin_layout Plain Layout
4902 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4905 \begin_layout Plain Layout
4911 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4914 \begin_layout Plain Layout
4920 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4923 \begin_layout Plain Layout
4929 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4932 \begin_layout Plain Layout
4938 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4941 \begin_layout Plain Layout
4947 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4950 \begin_layout Plain Layout
4969 \begin_layout Subsubsection
4973 \begin_layout Standard
4974 These tests check whether a .lyx file loads without any terminal messages.
4975 They correspond to the manual operations of simply opening a .lyx file on
4976 the terminal, exiting LyX once the file is loaded, and then checking whether
4977 there is any output from the terminal.
4978 These tests are useful for catching malformed .lyx files and parsing bugs.
4979 They can also be used to find a .lyx file in which an instance of something
4981 To do this, compile LyX with a local patch that outputs something to the
4982 terminal when an instance is found, and then run the check_load tests to
4983 see if any fail, which would mean that the situation occurs in the LyX
4984 documentation files corresponding to the failed tests.
4985 These tests are expectedly fragile: any LyX diagnostic message, which is
4986 not necessarily an error, would cause the tests to fail.
4987 Similarly, any message output by a library (e.g.
4988 Qt) would also cause failure.
4989 There are some messages that the check_load tests are instructed to ignore,
4990 which are stored in the file
4991 \begin_inset Flex Code
4994 \begin_layout Plain Layout
4995 development/autotests/filterCheckWarnings
5003 \begin_layout Standard
5004 Under cmake, the tests are labeled as 'load'.
5007 \begin_layout Subsubsection
5011 \begin_layout Standard
5012 Automated tests based on the "MonKey Testing" keytest program are enabled
5013 if the necessary dependencies are found and if the CMake flag
5014 \begin_inset Flex Code
5017 \begin_layout Plain Layout
5018 -DLYX_ENABLE_KEYTESTS=ON
5024 They are documented in the README document in
5025 \begin_inset Flex Code
5028 \begin_layout Plain Layout
5029 development/autotests
5034 subfolder of the \SpecialChar LyX
5035 source code distribution.
5038 \begin_layout Subsubsection
5042 \begin_layout Standard
5043 These tests combine lyx2lyx tests with check_load tests.
5044 They fail if either fails.
5047 \begin_layout Subsubsection
5051 \begin_layout Standard
5052 The URL tests are enabled with the
5053 \begin_inset Flex Code
5056 \begin_layout Plain Layout
5057 -DLYX_ENABLE_URLTESTS=ON
5062 CMake flag and are useful for finding broken links in our documentation
5064 If a URL test fails, to see which link in particular was reported as broken,
5066 \begin_inset Flex Code
5069 \begin_layout Plain Layout
5076 These tests are extremely fragile (e.g.
5077 a test can depend on your Internet connection) and a failed URL test should
5078 not be taken too seriously.
5079 URL tests are labeled as
5084 \begin_layout Paragraph
5088 \begin_layout Standard
5089 cmake is required to run the \SpecialChar LyX
5090 tests, running them is not implemented for
5094 \begin_layout Standard
5095 The appropriate commands are:
5098 \begin_layout Itemize
5104 \begin_inset Newline newline
5107 runs all tests with label
5112 \begin_layout Itemize
5115 ctest -R 'check_.*urls'
5118 \begin_inset Newline newline
5121 runs the tests 'check_accessible_urls'
5124 \begin_layout Standard
5125 Associated test results can be examined in ctest-log directory in files
5126 of the form 'LastFailed.*URLS.log'
5129 \begin_layout Section
5130 Development policies
5133 \begin_layout Standard
5134 This chapter lists some guidelines that should be followed.
5135 This list is not complete, and many guidelines are in separate chapters,
5137 \begin_inset Quotes eld
5140 When is an update of the .lyx file format number needed?
5141 \begin_inset Quotes erd
5145 \begin_inset CommandInset ref
5147 reference "sec:When-is-an"
5154 \begin_layout Subsection
5155 When to set a fixed milestone?
5158 \begin_layout Standard
5159 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5163 \begin_layout Enumerate
5164 Somebody is actively working on a fix.
5167 \begin_layout Enumerate
5168 The bug is so severe that it would block the release if it is not fixed.
5171 \begin_layout Standard
5172 If a bug is important, but nobody is working on it, and it is no showstopper,
5173 use a milestone like 2.1.x or 2.2.x.
5174 For all other bugs, do not set a milestone at all.
5177 \begin_layout Subsection
5178 Can we add rc entries in stable branch?
5181 \begin_layout Standard
5183 We are supposed to increase the prefs2prefs version number with such things.
5186 \begin_layout Section
5187 Documentation policies
5190 \begin_layout Subsection
5194 \begin_layout Standard
5196 \begin_inset space ~
5199 rules in editing the docs:
5202 \begin_layout Enumerate
5203 \begin_inset CommandInset label
5205 name "enu:If-you-are"
5209 If you are not the maintainer of a doc file or a chapter/section, you MUST
5210 use change tracking so that the maintainer could review your changes
5213 \begin_layout Enumerate
5214 Respect the formatting of the document.
5215 The different files use different formatting styles.
5216 That is OK and has historic reasons nobody fully knows ;-).
5217 But it is important to be consistent within one file.
5220 \begin_layout Enumerate
5221 All changes you make to a file in one language MUST also go the file in
5222 the other actively maintained languages.
5223 Normally the maintainer does this for you, if you are the maintainer, you
5224 must do this by copying or changing the changed or added text to the other
5225 files so that the translators sees the blue underlined text and know what
5226 they have to translate and what was changed.
5229 \begin_layout Enumerate
5230 You MUST assure that the document is compilable as
5231 \begin_inset Quotes eld
5235 \begin_inset Quotes erd
5238 or the document's default output format after your changes.
5241 \begin_layout Enumerate
5242 All fixes (typos, compilation fixes, updates info etc.) go at first into
5243 the current GIT branch because the user should benefit from all fixes with
5244 every minor release.
5245 Feel free to commit directly to branch as long as you follow rule
5246 \begin_inset space ~
5250 \begin_inset CommandInset ref
5252 reference "enu:If-you-are"
5257 You can immediately commit to master as well.
5260 \begin_layout Enumerate
5261 The fileformat of a file must not be changed unless you document a new feature
5262 in LyX that requires a new fileformat.
5263 The reason for this rule is to keep it easy for the doc maintainers to
5264 port/backport changes to from master/branch.
5267 \begin_layout Standard
5268 The main documentation consists of these files:
5271 \begin_layout Description
5272 splash.lyx it is the first file you see after an installation.
5273 We assume that a new user sees this.
5274 It is therefore designed to be as simple as possible.
5275 Therefore please don't add any new formatting, only fix typos etc.
5276 Splash.lyx is up to date for \SpecialChar LyX
5277 2.1.x, currently maintained by Uwe Stöhr.
5280 \begin_layout Description
5281 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5283 It therefore uses a limited set of formatting.
5284 For example a standard document class.
5285 Since new users will first learn about the formatting possibilities of
5287 please keep this file that simple.
5288 Intro.lyx is up to date for \SpecialChar LyX
5289 2.1.x, currently maintained by Uwe Stöhr.
5292 \begin_layout Description
5293 Tutorial.lyx our tutorial.
5294 It must be always up to date.
5295 Normally there is nothing to add since we don't want to overwhelm new users
5296 with too much details.
5297 The will learn these details while using \SpecialChar LyX
5298 and we have special manuals.
5299 Tutorial.lyx is up to date for \SpecialChar LyX
5300 2.1.x, currently maintained by Uwe Stöhr.
5303 \begin_layout Description
5304 UserGuide.lyx our main user guide.
5305 It covers a mixture of basic and detailed information.
5306 Some information is also in the Math and EmbeddedObjects manual so that
5307 the UserGuide refers to these files.
5308 UserGuide.lyx is up to date for \SpecialChar LyX
5309 2.1.x, currently maintained by Uwe Stöhr.
5312 \begin_layout Description
5313 EmbeddedObjects.lyx a special manual to explain things like tables floats
5316 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5317 2.1.x, currently maintained by Uwe
5321 \begin_layout Description
5322 Math.lyx a special manual to explain everything regarding math in all detail.
5323 Math.lyx is up to date for \SpecialChar LyX
5324 2.1.x, currently maintained by Uwe Stöhr.
5327 \begin_layout Description
5328 Additional.lyx this manual covers information that would be too much detail
5329 for the UserGuide or would make the UserGuide uncompilable or only compilable
5330 when installing a lot of special \SpecialChar LaTeX
5332 What should be in the UserGuide or better in Additional is a matter of
5334 it is up to you to decide that.
5335 Additional.lyx is not completely up to date for \SpecialChar LyX
5338 \begin_inset space ~
5341 8 is up to date and currently maintained by Uwe Stöhr.
5342 It certainly needs a rewrite and update.
5343 For example many info in chapter
5344 \begin_inset space ~
5347 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5351 \begin_layout Description
5352 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5354 output formats, operating systems, languages etc.
5355 It is currently completely out of date and needs a major rewrite and update.
5356 If you do this please assure that your information are given for all OSes
5357 and \SpecialChar LaTeX
5358 distributions (meaning be as objective as possible).