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
29 \use_dash_ligatures true
31 \default_output_format pdf2
33 \bibtex_command default
34 \index_command default
38 \pdf_title "LyX's Development manual"
39 \pdf_author "LyX Team"
40 \pdf_subject "LyX's development documentation"
41 \pdf_keywords "LyX, Documentation, Development"
43 \pdf_bookmarksnumbered true
44 \pdf_bookmarksopen true
45 \pdf_bookmarksopenlevel 1
50 \pdf_pdfusetitle false
51 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
54 \use_package amsmath 1
55 \use_package amssymb 1
58 \use_package mathdots 1
59 \use_package mathtools 1
61 \use_package stackrel 1
62 \use_package stmaryrd 1
63 \use_package undertilde 1
65 \cite_engine_type default
69 \paperorientation portrait
73 \notefontcolor #0000ff
80 \paragraph_separation indent
81 \paragraph_indentation default
83 \math_numbering_side default
88 \paperpagestyle headings
89 \tracking_changes false
100 Developing \SpecialChar LyX
104 \begin_layout Subtitle
109 by the \SpecialChar LyX
114 \begin_layout Plain Layout
116 If you have comments or error corrections, please send them to the \SpecialChar LyX
119 \begin_inset Flex Code
122 \begin_layout Plain Layout
124 <lyx-docs@lists.lyx.org>
137 \begin_layout Standard
138 \begin_inset CommandInset toc
139 LatexCommand tableofcontents
146 \begin_layout Section
150 \begin_layout Standard
151 This manual documents some aspects of \SpecialChar LyX
153 It is currently rather incomplete, but will hopefully be extended in the
155 Meanwhile, additional information can be found in the
156 \begin_inset Flex Code
159 \begin_layout Plain Layout
165 subfolder of the \SpecialChar LyX
166 source code distribution.
167 This document is not translated, since the development language of \SpecialChar LyX
170 If you just want to use \SpecialChar LyX
171 , then you don't need to read this manual.
172 However, if you want to learn more about how \SpecialChar LyX
173 is developed, or even want
174 to participate in \SpecialChar LyX
175 development, you may find some interesting information
179 \begin_layout Section
183 \begin_layout Standard
185 uses several custom file formats for configuration files and documents.
186 This chapter contains some background concerning these file formats.
187 Several file formats are also described in detail in the regular user documenta
191 \begin_layout Subsection
195 \begin_layout Subsection
196 When is an update of the .lyx file format number needed?
197 \begin_inset CommandInset label
199 name "sec:When-is-an"
206 \begin_layout Standard
207 When you are working on a new feature you may ask yourself whether it needs
208 an update of the .lyx file format number.
209 Whether an update is needed or not is not always obvious.
214 Whenever there is the danger that a previous version of LyX cannot open
215 a file using the new feature, a file format update is needed.
218 \begin_layout Standard
219 The file format change allows lyx2lyx rules to implement backwards compatibility.
220 Below you can find a list of reasons for file format updates with explanations:
223 \begin_layout Description
232 setting Whenever you introduce a new setting that is stored in the document
233 header, a file format update is needed.
236 \begin_layout Description
245 setting If a certain setting becomes obsolete and gets removed, a file format
249 \begin_layout Description
275 \begin_inset space \thinspace{}
282 \begin_layout Description
283 \paragraph_spacing single
296 package The reason for this is that there is no true ERT inset for math
297 formulas: Each command is parsed, and if a user happens to define a local
298 command with the same name as a command that triggers an automatic load
299 of a package, they need to be able to switch off the automatic loading
301 This switch is stored by the
302 \begin_inset Flex Code
305 \begin_layout Plain Layout
314 \begin_layout Description
319 language that is stored in
320 \begin_inset Flex Code
323 \begin_layout Plain Layout
333 \begin_inset Note Note
336 \begin_layout Plain Layout
337 This requirement is under discussion.
346 \begin_layout Description
351 inset Of course a new inset requires a file format update.
354 \begin_layout Description
359 style If a new style or inset layout is added to any layout file or module
360 shipped with \SpecialChar LyX
361 , then a new file format is needed in the master (development)
363 It is possible to backport new styles to the stable version without a file
366 \begin_inset CommandInset ref
368 reference "subsec:Backporting-new-styles"
372 for more information.
375 \begin_layout Description
380 style If a style or inset layout is removed in any layout file or module
381 shipped with \SpecialChar LyX
382 , a new file format is required.
385 \begin_layout Standard
390 layouts and modules do
394 require a file format update (changed 03/16, see
395 \begin_inset CommandInset ref
397 reference "subsec:New-layouts"
405 \begin_layout Standard
406 If you are still unsure, please ask on the development list.
409 \begin_layout Subsection
410 \begin_inset CommandInset label
412 name "subsec:update_lyx_files"
416 How to update the file format number of .lyx files
419 \begin_layout Standard
420 Once you come to the conclusion that a file format update is needed, you
421 should use the following procedure to perform the update:
424 \begin_layout Enumerate
425 Implement and test the new feature, including the reading and writing of
427 Note that any file produced at this stage does not use a valid format,
428 so do not use this version of \SpecialChar LyX
429 for working on any important documents.
432 \begin_layout Enumerate
433 \begin_inset CommandInset label
435 name "enu:Describe_format"
439 Describe the new format in
440 \begin_inset Flex Code
443 \begin_layout Plain Layout
452 \begin_layout Enumerate
453 Update the \SpecialChar LyX
454 file format number in
455 \begin_inset Flex Code
458 \begin_layout Plain Layout
467 \begin_layout Enumerate
468 \begin_inset CommandInset label
470 name "enu:Add-an-entry"
474 Add an entry to both format lists (for conversion and reversion) in
475 \begin_inset Newline newline
479 \begin_inset Flex Code
482 \begin_layout Plain Layout
483 lib/lyx2lyx/lyx_2_3.py
489 Add a conversion routine if needed (e.
490 \begin_inset space \thinspace{}
493 g., a new header setting always needs a conversion that adds the new setting,
494 but a new document language does not need one).
495 Add a reversion routine if needed.
497 \begin_inset Newline newline
500 While the conversion routine is required to produce a document that is equivalen
501 t to the old version, the requirements of the reversion are not that strict.
502 If possible, try to produce a proper reversion, using ERT if needed, but
503 for some features this might be too complicated.
504 In this case, the minimum requirement of the reversion routine is that
505 it produces a valid document which can be read by an older \SpecialChar LyX
507 If absolutely needed, even data loss is allowed for the reversion.
508 (In that case, you might want to add a LyX comment that indicates what
509 you have had to do, so the user is at least warned).
512 \begin_layout Enumerate
513 Since tex2lyx has several implicit file format dependencies caused by sharing
514 code with \SpecialChar LyX
515 , updating the file format of .lyx files produced by tex2lyx at
516 the same time as updating the main .lyx file format is strongly recommended.
517 Therefore, a compiler warning will be issued if the \SpecialChar LyX
518 and tex2lyx .lyx file
519 format numbers differ.
520 In many cases the tex2lyx update requires only the first and last item
525 \begin_layout Enumerate
526 Update the tex2lyx file format number in
527 \begin_inset Flex Code
530 \begin_layout Plain Layout
539 \begin_layout Enumerate
540 If the lyx2lyx conversion from the old to the new format is empty, or if
541 tex2lyx does not yet output the changed feature, you do not need any further
543 Otherwise, search for the changed feature in tex2lyx, and adjust the output
544 according to the lyx2lyx changes.
547 \begin_layout Enumerate
548 Update the tex2lyx test references as described in
549 \begin_inset CommandInset ref
550 LatexCommand formatted
551 reference "sec:Updating-test-references"
559 \begin_layout Enumerate
560 If you did not implement full tex2lyx support for the new feature, add a
562 \begin_inset Flex Code
565 \begin_layout Plain Layout
571 describing the missing bits.
572 Note that it is perfectly fine if you do not add full tex2lyx support for
573 a new feature: The updating recommendation above is only issued for the
574 syntax of the produced .lyx file.
575 It is no problem if some features supported by \SpecialChar LyX
576 are still output as ERT
578 The problems in the past that resulted in the update recommendation were
579 related to mixed version syntax, not ERT.
582 \begin_layout Enumerate
583 It would be nice if you could create a .lyx test file which contains instances
584 of all changed or added features.
585 This could then be used to test lyx2lyx and tex2lyx.
586 Unfortunately, it has not yet been decided how to collect such examples,
587 so please ask on the development list if you want to create one.
590 \begin_layout Enumerate
591 \begin_inset CommandInset label
593 name "enu:updatefiles"
597 Test your lyx2lyx code by updating LyX's .lyx documentation files to the
599 The developer who makes the change knows best what changes to expect when
600 inspecting the resulting diff.
601 Because of this, you might be able to catch a bug in the lyx2lyx code that
602 updates the format just by taking a quick scan through the large diff that
604 \begin_inset Note Note
607 \begin_layout Plain Layout
608 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
609 see which layout update made an unexpected change by looking at the git
610 log of a .lyx file that suffers the problem.
615 To do this, first make sure that there are no changes to the git repository
616 that you will not want to commit (this is needed because it will be convenient
617 to commit with the command
618 \begin_inset Flex Code
621 \begin_layout Plain Layout
628 Then run the following command in the root folder of the source:
629 \begin_inset Flex Code
632 \begin_layout Plain Layout
633 python development/tools/updatedocs.py
639 Look at the resulting changes using the command
640 \begin_inset Flex Code
643 \begin_layout Plain Layout
650 If anything looks surprising, please investigate.
651 Keep in mind that the case of
652 \begin_inset Flex Code
655 \begin_layout Plain Layout
661 is special, because it is first generated with
662 \begin_inset Flex Code
665 \begin_layout Plain Layout
671 before being converted to the latest format.
672 \begin_inset Newline newline
676 \begin_inset Note Greyedout
679 \begin_layout Plain Layout
684 Only commit file format changes in the doc files if these files are using
685 the new feature of the new file format.
691 \begin_inset CommandInset ref
693 reference "enu:The-fileformat-of"
697 of the documentation policies described in sec.
702 \begin_inset CommandInset ref
704 reference "sec:Documentation-policies"
716 \begin_layout Enumerate
717 Finally, commit using
718 \begin_inset Flex Code
721 \begin_layout Plain Layout
730 \begin_layout Subsection
731 Updating the file format number of layout files
734 \begin_layout Standard
735 The procedure for updating the layout files is similar to that in step
736 \begin_inset CommandInset ref
738 reference "enu:updatefiles"
743 \begin_inset CommandInset ref
745 reference "subsec:update_lyx_files"
751 \begin_inset Flex Code
754 \begin_layout Plain Layout
755 python development/tools/updatelayouts.py
761 \begin_inset Flex Code
764 \begin_layout Plain Layout
773 \begin_layout Standard
774 Note that we do not automatically update any local layout used in the
775 \begin_inset Flex Code
778 \begin_layout Plain Layout
784 files shipped with \SpecialChar LyX
785 because users would then not be able to export to older
787 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
788 to open the file in \SpecialChar LyX
789 2.1.x, there would be an error because the file would
790 contain a local layout whose format is too new.
791 The root reason for this is that we do not support converting layouts to
792 older layout formats, as we do for the
793 \begin_inset Flex Code
796 \begin_layout Plain Layout
805 \begin_layout Subsection
806 Updating the file format number of bind/ui files
809 \begin_layout Standard
810 A change to the functionality of existing LFUNs can require a conversion
812 \begin_inset Flex Code
815 \begin_layout Plain Layout
822 \begin_inset Flex Code
825 \begin_layout Plain Layout
831 files, and therefore an increment of the LFUN format, as well as a conversion
833 \begin_inset Flex Code
836 \begin_layout Plain Layout
843 The latter cannot be done automatically and also requires an update of
847 \begin_inset space \space{}
850 of someone who might have made a set of \SpecialChar LyX
851 teaching manuals for use in their
856 \begin_layout Plain Layout
857 \begin_inset Flex URL
860 \begin_layout Plain Layout
862 http://www.lyx.org/trac/ticket/9794
875 \begin_layout Standard
876 To update the LFUN format:
879 \begin_layout Enumerate
880 Increment the LFUN file format number in
881 \begin_inset Flex Code
884 \begin_layout Plain Layout
893 \begin_layout Enumerate
894 Implement the LFUN conversion in
895 \begin_inset Flex Code
898 \begin_layout Plain Layout
899 lib/scripts/prefs2prefs_lfuns.py
907 \begin_layout Enumerate
909 \begin_inset CommandInset ref
911 reference "enu:updatefiles"
916 \begin_inset CommandInset ref
918 reference "subsec:update_lyx_files"
923 \begin_inset Flex Code
926 \begin_layout Plain Layout
932 command, use this command:
933 \begin_inset Flex Code
936 \begin_layout Plain Layout
937 bash development/tools/updatelfuns.sh
944 \begin_inset Note Note
947 \begin_layout Plain Layout
948 This file should really be converted to python.
956 \begin_layout Enumerate
957 Update Info insets in
958 \begin_inset Flex Code
961 \begin_layout Plain Layout
968 To do so, increment the \SpecialChar LyX
969 format and proceed as in
970 \begin_inset CommandInset ref
972 reference "subsec:update_lyx_files"
977 \begin_inset CommandInset ref
979 reference "enu:Describe_format"
984 \begin_inset CommandInset ref
986 reference "enu:updatefiles"
991 In the lyx2lyx implementation (step
992 \begin_inset CommandInset ref
994 reference "enu:Add-an-entry"
998 ), implement a conversion similar to the one in
999 \begin_inset Flex Code
1002 \begin_layout Plain Layout
1003 prefs2prefs_lfuns.py
1008 above, as well as a corresponding reversion; for this one can use
1009 \begin_inset Flex Code
1012 \begin_layout Plain Layout
1019 \begin_inset Flex Code
1022 \begin_layout Plain Layout
1023 lib/lyx2lyx/lyx2lyx_tools.py
1032 \begin_layout Subsection
1033 Backporting new styles to the stable version
1034 \begin_inset CommandInset label
1036 name "subsec:Backporting-new-styles"
1043 \begin_layout Standard
1044 Starting with the stable \SpecialChar LyX
1045 2.1 branch, there is a mechanism in place to backport
1046 new styles to the stable version without the need to update the file format.
1047 The basic idea is that the new style definition is automatically copied
1048 to the document preamble so that it can even be used by older minor versions
1049 that did not yet include the style.
1050 To backport a new style to the stable version, the following steps are
1054 \begin_layout Enumerate
1056 \begin_inset Flex Code
1059 \begin_layout Plain Layout
1065 to the style definition in the development version.
1068 \begin_layout Enumerate
1069 Copy the style definition to the stable version, but use
1070 \begin_inset Flex Code
1073 \begin_layout Plain Layout
1080 If needed adjust the format to the one used by the stable version (see
1081 the customization manual for details of the layout file format).
1084 \begin_layout Enumerate
1085 For each update of the style in a later stable version, increase the argument
1087 \begin_inset Flex Code
1090 \begin_layout Plain Layout
1097 (In the stable version, the development version should not be touched.)
1100 \begin_layout Standard
1101 For details about the
1102 \begin_inset Flex Code
1105 \begin_layout Plain Layout
1111 flag see the customization manual.
1113 \begin_inset Flex Code
1116 \begin_layout Plain Layout
1122 support is needed for backported styles: Since the style of the development
1123 version has an infinite version number, it will always be used.
1124 Furthermore, since its version number is less than one, the style will
1125 not be written anymore to the document header for files saved by the new
1129 \begin_layout Section
1130 New layouts and modules
1133 \begin_layout Subsection
1134 \begin_inset CommandInset label
1136 name "subsec:New-layouts"
1143 \begin_layout Standard
1144 Adding a new layout file to the \SpecialChar LyX
1146 \begin_inset Quotes eld
1149 officially supported
1150 \begin_inset Quotes erd
1154 You should therefore think carefully about whether you really want to do
1155 this and discuss it on lyx-devel, since you will need to be prepared to
1156 update and fix the layout if necessary.
1157 If the layout is experimental or for a rarely used document class, then
1158 it may be better to add it to the relevant portion of the \SpecialChar LyX
1162 \begin_inset CommandInset href
1164 target "https://wiki.lyx.org/Layouts/Layouts"
1172 \begin_layout Standard
1173 In older versions of this document, it was stated that new layout files
1174 require a file format change.
1175 After some discussion, it was decided that this is not needed.
1179 \begin_layout Plain Layout
1181 \begin_inset CommandInset href
1183 name "the thread “Proposal for a guide on updating layouts”"
1184 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1198 For reference, here are the arguments on each side
1202 \begin_layout Description
1204 \begin_inset Quotes eld
1207 New layout files are a file format change
1208 \begin_inset Quotes erd
1214 \begin_layout Itemize
1215 All documents produced by 2.2.
1216 \begin_inset Formula $x$
1219 can always be edited and exported even if
1220 \begin_inset Formula $x$
1224 This is important for people using different machines, or exchanging work
1228 \begin_layout Description
1230 \begin_inset Quotes eld
1233 New layout files are not a file format change
1234 \begin_inset Quotes erd
1240 \begin_layout Itemize
1241 No new LaTeX classes can be supported in a stable version, and stable versions
1242 have a typical lifetime of 2–3 years.
1245 \begin_layout Itemize
1246 We have the same situation already with custom layout files: If a document
1247 using a custom layout file is moved between machines or people, then the
1248 layout file needs to be exchanged as well.
1249 If that is not done, then we have a fallback implemented so that such documents
1250 can still be edited, but not exported, and the user gets a warning.
1254 \begin_layout Itemize
1255 The lyx2lyx script cannot do anything useful in such a case.
1259 \begin_layout Standard
1260 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1262 then, you should do the following:
1265 \begin_layout Enumerate
1266 Put your new layout file in
1267 \begin_inset Flex Code
1270 \begin_layout Plain Layout
1277 \begin_inset Flex Code
1280 \begin_layout Plain Layout
1281 git add lib/layouts/newlayout.layout
1286 ) so that it will be committed.
1289 \begin_layout Enumerate
1291 \begin_inset Flex Code
1294 \begin_layout Plain Layout
1300 , so that the new layout actually gets installed.
1303 \begin_layout Enumerate
1305 \begin_inset Flex Code
1308 \begin_layout Plain Layout
1309 lib/doc/LaTeXConfig.lyx
1314 containing in particular a line like
1322 \begin_layout Standard
1323 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1324 \begin_inset Flex Code
1327 \begin_layout Plain Layout
1328 info-insert textclass <name>
1334 This inset will automatically display a boxed
1335 \begin_inset Quotes eld
1339 \begin_inset Quotes erd
1343 \begin_inset Quotes eld
1347 \begin_inset Quotes erd
1350 depending on the availability of the package.
1354 \begin_layout Enumerate
1355 A template or example is strongly encouraged (but not necessarily required).
1356 It is also possible to provide both.
1358 \begin_inset Flex Code
1361 \begin_layout Plain Layout
1368 \begin_inset Flex Code
1371 \begin_layout Plain Layout
1380 \begin_layout Enumerate
1381 Reconfigure \SpecialChar LyX
1385 \begin_layout Enumerate
1386 Ensure the autotests for the new layout pass (see
1387 \begin_inset CommandInset ref
1389 reference "par:when-to-run-an-export-test"
1396 \begin_layout Subsection
1400 \begin_layout Standard
1401 Adding a new module is very similar to adding a new layout.
1402 Therefore, the previous section applies to new modules as well, with two
1406 \begin_layout Enumerate
1407 You only need to add an entry to
1408 \begin_inset Flex Code
1411 \begin_layout Plain Layout
1412 lib/doc/LaTeXConfig.lyx
1417 if the module requires a LaTeX package.
1418 In that case, the command for entering the InsetInfo is:
1419 \begin_inset Flex Code
1422 \begin_layout Plain Layout
1423 \paragraph_spacing single
1424 info-insert package <name>
1432 \begin_layout Enumerate
1433 Modules do not need a template, only an example, which is strongly encouraged
1434 but not necessarily required.
1437 \begin_layout Subsection
1438 Layouts for document classes with incompatible versions
1441 \begin_layout Standard
1442 \begin_inset Note Greyedout
1445 \begin_layout Description
1446 Note: This section is currently only a proposal under discussion.
1447 Please correct/amend as suited.
1448 Remove this note once a consensus is found.
1451 \begin_layout Plain Layout
1453 \begin_inset Quotes eld
1456 Proposal for a guide on updating layouts
1457 \begin_inset Quotes erd
1460 for details and background
1463 \begin_layout Plain Layout
1464 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1472 \begin_layout Standard
1473 Every now and then, there are changes to LaTeX document classes that break
1474 backwards compatibility.
1478 \begin_layout Plain Layout
1479 Uwe has suggested we implement automatic detection of changes in class files.
1480 This could be done by running a script every month that checks if a document
1481 class was changed at CTAN and at the homepages of the scientific journals.
1482 If it reports a change, we can check if our template and layout file are
1483 still usable with the changed document class.
1484 (This is different from the autotests insofar, as this would also catch
1485 changes that do not result in compilation errors.)
1490 Reasons can be a new name for the
1491 \begin_inset Flex Code
1494 \begin_layout Plain Layout
1500 file, removed \SpecialChar LaTeX
1502 How should this best be handled in \SpecialChar LyX
1506 \begin_layout Standard
1507 The idea is to support the new version with a new \SpecialChar LyX
1511 \begin_layout Itemize
1512 Existing documents can still be opened in \SpecialChar LyX
1513 and will continue to work on
1514 systems where the old version is still installed.
1518 \begin_layout Itemize
1519 With differently named
1520 \begin_inset Flex Code
1523 \begin_layout Plain Layout
1529 files, \SpecialChar LyX
1530 can check for the availability of the particular version and reflect
1532 Different document class versions with the same file name are currently
1533 (2.2.x) not detected by the configuration script.
1534 This is planned for 2.3.
1538 \begin_layout Plain Layout
1539 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1542 \begin_layout Plain Layout
1543 However, what we really need is version detection for the configuration,
1544 so that the user can be warned if the required class file has the wrong
1546 (If the class file keeps the name over the version change, only one of
1547 the two layout files generates compilable documents.)
1550 \begin_layout Plain Layout
1551 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1560 \begin_layout Itemize
1561 The new layout can be added both to the master and the stable branches,
1562 in accord with the policy discussed in
1563 \begin_inset CommandInset ref
1564 LatexCommand formatted
1565 reference "subsec:New-layouts"
1570 No lyx2lyx conversion is then required when a new major version is released.
1573 \begin_layout Standard
1574 The user can move an existing document to the new version simply by selecting
1575 a new document class.
1576 This step is well supported by \SpecialChar LyX
1577 , with established methods for handling
1578 unsupported styles and other changes.
1579 This way, no lyx2lyx code is required.
1582 \begin_layout Standard
1583 The steps to support a new version of an existing document class are thus:
1586 \begin_layout Itemize
1587 Create a new layout file including the upstream version in the name (avoid
1588 special characters like spaces and dots), e.g.
1590 \begin_inset Flex Code
1593 \begin_layout Plain Layout
1594 acmsiggraph-v0-92.layout
1602 \begin_layout Itemize
1603 Include the name of the
1604 \begin_inset Flex Code
1607 \begin_layout Plain Layout
1613 file as an optional argument in the
1614 \begin_inset Flex Code
1617 \begin_layout Plain Layout
1625 line and include the version number in the GUI name:
1626 \begin_inset Newline newline
1630 \begin_inset Flex Code
1633 \begin_layout Plain Layout
1636 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1637 \begin_inset space ~
1648 \begin_layout Itemize
1649 Update the GUI name in the old layout file (whose name should not be changed),
1651 \begin_inset Newline newline
1655 \begin_inset Flex Code
1658 \begin_layout Plain Layout
1661 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1662 \begin_inset space ~
1673 \begin_layout Itemize
1674 To avoid duplicate definitions, the new layout can
1675 \begin_inset Flex Code
1678 \begin_layout Plain Layout
1684 the old layout file and add\SpecialChar breakableslash
1685 remove\SpecialChar breakableslash
1686 obsolete\SpecialChar breakableslash
1687 modify settings and styles (similar
1689 \begin_inset Flex Code
1692 \begin_layout Plain Layout
1702 \begin_layout Standard
1703 It may be tempting to let the new layout be the
1704 \begin_inset Quotes eld
1708 \begin_inset Quotes erd
1711 and have the old layout import it.
1712 However, this should not be done because any changes to the new layout
1713 would need undo steps in the importing old layout.
1717 \begin_layout Itemize
1718 If the new LaTeX document class obsoletes the old one, update the example
1719 and template files to use the new layout.
1720 Add a note about the changes (preferably with a pointer to the documentation
1725 \begin_layout Standard
1726 This way, new documents based on the template or example will use the up-to-date
1727 document class version.
1731 \begin_layout Standard
1732 \begin_inset Newpage newpage
1738 \begin_layout Section
1742 \begin_layout Standard
1743 Automated tests are an important tool to detect bugs and regressions in
1744 software development.
1745 Some projects like gcc even require each bug fix to be accompanied by a
1746 test case for the automatic test suite, that would detect this bug.
1747 Testing interactive features automatically is of course very hard, but
1748 core functionality like document import and export can be tested quite
1749 easily, and some tests of this kind exist.
1752 \begin_layout Subsection
1756 \begin_layout Standard
1757 There are attempts to set up a suite of unit tests for LyX.
1760 \begin_layout Standard
1761 TODO: describe what is done and what is still to do.
1764 \begin_layout Subsection
1768 \begin_layout Standard
1769 The tex2lyx tests are located in the
1770 \begin_inset Flex Code
1773 \begin_layout Plain Layout
1779 subfolder of the \SpecialChar LyX
1780 source code distribution.
1781 The actual testing is performed by the simple python script
1782 \begin_inset Flex Code
1785 \begin_layout Plain Layout
1786 src/tex2lyx/test/runtests.py
1792 Each test consists of two files:
1793 \begin_inset Flex Code
1796 \begin_layout Plain Layout
1802 contains the \SpecialChar LaTeX
1803 code that should be tested.
1805 \begin_inset Flex Code
1808 \begin_layout Plain Layout
1814 contains the expected output of tex2lyx.
1815 When a test is run, the actual produced output is compared with the stored
1817 The test passes if both are identical.
1818 The test machinery is also able to generate a file
1819 \begin_inset Flex Code
1822 \begin_layout Plain Layout
1828 by exporting the produced .lyx file with \SpecialChar LyX
1830 This may be useful for roundtrip comparisons.
1833 \begin_layout Subsubsection
1837 \begin_layout Standard
1838 The tex2lyx tests can be run in several ways.
1840 \begin_inset Flex Code
1843 \begin_layout Plain Layout
1849 subfolder of the build directory, the commands
1850 \begin_inset Flex Code
1853 \begin_layout Plain Layout
1859 (cmake, all platforms),
1860 \begin_inset Flex Code
1863 \begin_layout Plain Layout
1869 (cmake, when using a make based build system and not MSVC) or
1870 \begin_inset Flex Code
1873 \begin_layout Plain Layout
1879 (autotools) will run the tex2lyx tests.
1880 Alternatively, in the root of the build directory, the command
1881 \begin_inset Flex Code
1884 \begin_layout Plain Layout
1890 runs all tests whose names match the regex
1891 \begin_inset Quotes eld
1895 \begin_inset Quotes erd
1899 Another way to run the tex2lyx tests in the root build directory is to
1900 instead use the command
1901 \begin_inset Flex Code
1904 \begin_layout Plain Layout
1905 ctest -L '(cmplyx|roundtrip)'
1910 , which runs all tests categorized with the label
1911 \begin_inset Quotes eld
1915 \begin_inset Quotes erd
1919 \begin_inset Quotes eld
1923 \begin_inset Quotes erd
1927 If a test fails, the differences between the expected and actual results
1928 are output in unified diff format.
1931 \begin_layout Subsubsection
1932 Updating test references
1933 \begin_inset CommandInset label
1935 name "sec:Updating-test-references"
1942 \begin_layout Standard
1943 In some cases a changed tex2lyx output is not a test failure, but wanted,
1945 \begin_inset space \thinspace{}
1949 \begin_inset space \space{}
1952 if a tex2lyx bug was fixed, or a new feature was added.
1953 In these cases the stored references need to be updated.
1954 To do so if using autotools, call
1955 \begin_inset Flex Code
1958 \begin_layout Plain Layout
1965 \begin_inset Flex Code
1968 \begin_layout Plain Layout
1974 subdirectory of the build directory.
1975 If instead using CMake, call
1976 \begin_inset Flex Code
1979 \begin_layout Plain Layout
1980 make updatetex2lyxtests
1985 in the build directory or in the
1986 \begin_inset Flex Code
1989 \begin_layout Plain Layout
1995 subdirectory of the build directory.
1999 \begin_layout Plain Layout
2000 Note that this is a case where a make target in the build directory can
2001 affect the source directory, which might not be advisable.
2006 On Windows do the following:
2009 \begin_layout Itemize
2010 Assure that the path to the python.exe is in your system PATH variable.
2013 \begin_layout Itemize
2014 Double-click on the file
2015 \begin_inset Flex Code
2018 \begin_layout Plain Layout
2019 updatetex2lyxtests.vcxproj
2024 in the build directory or in the
2025 \begin_inset Flex Code
2028 \begin_layout Plain Layout
2034 subdirectory of your build directory.
2037 \begin_layout Itemize
2038 In the appearing MSVC program assure that you build the
2042 version, then right-click on the project
2046 in the project explorer and choose then
2049 \begin_inset space ~
2052 Only\SpecialChar menuseparator
2054 \begin_inset space ~
2062 \begin_layout Standard
2063 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2065 Please examine the changed output carefully before committing the changed
2066 files to the repository: Since the test machinery does not do a roundtrip
2068 \begin_inset Formula $\Rightarrow$
2072 \begin_inset Formula $\Rightarrow$
2075 .tex, and does not compare the produced dvi or pdf output, it assumes that
2076 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2078 There is only one chance to detect wrong output: before committing a new
2080 Once it is committed, it is quite difficult to verify whether it is correct.
2083 \begin_layout Standard
2088 update the test references by opening them with \SpecialChar LyX
2089 or directly running lyx2lyx
2091 This would not work, since lyx2lyx and \SpecialChar LyX
2092 produce slightly different files
2093 regarding insignificant whitespace and line breaks.
2096 \begin_layout Subsubsection
2100 \begin_layout Standard
2101 In many cases tests for new features may be added to one of the existing
2102 test files, but sometimes this is not possible or not wanted.
2103 Then a new test file needs to be added:
2106 \begin_layout Enumerate
2108 \begin_inset Flex Code
2111 \begin_layout Plain Layout
2112 src/tex2lyx/test/<test name>.tex
2117 and run tex2lyx in roundtrip mode to produce the file
2118 \begin_inset Flex Code
2121 \begin_layout Plain Layout
2122 src/tex2lyx/test/<test name>.lyx.lyx
2128 This file will be the new reference.
2131 \begin_layout Enumerate
2132 Once you confirmed that the tex2lyx output is correct, add the new files
2133 to the corresponding lists in
2134 \begin_inset Flex Code
2137 \begin_layout Plain Layout
2138 src/tex2lyx/test/runtests.py
2144 \begin_inset Flex Code
2147 \begin_layout Plain Layout
2148 src/tex2lyx/Makefile.am
2154 \begin_inset Flex Code
2157 \begin_layout Plain Layout
2158 src/tex2lyx/test/CMakeLists.txt
2166 \begin_layout Enumerate
2167 Commit the changes to the repository, or send a patch to the development
2168 list and ask for committing if you do not have commit rights.
2171 \begin_layout Subsection
2172 ctest automatic tests
2175 \begin_layout Standard
2176 Some tests are located in the
2177 \begin_inset Flex Code
2180 \begin_layout Plain Layout
2181 development/autotests/
2186 subfolder of the \SpecialChar LyX
2187 source code distribution.
2192 \begin_layout Plain Layout
2193 The README document in this folder only describes the
2194 \begin_inset Quotes eld
2198 \begin_inset Quotes erd
2201 subset of autotests!
2209 \begin_layout Standard
2210 These tests can be run by the commands
2211 \begin_inset Flex Code
2214 \begin_layout Plain Layout
2224 (all platforms) or (when using a make based build system and not MSVC)
2226 \begin_inset Flex Code
2229 \begin_layout Plain Layout
2236 \begin_inset Flex Code
2239 \begin_layout Plain Layout
2250 The test logs are written to the
2251 \begin_inset Flex Code
2254 \begin_layout Plain Layout
2268 \begin_layout Subsubsection
2272 \begin_layout Standard
2273 The export tests are integration tests.
2274 They take longer to run and are more likely to break than the tex2lyx tests.
2275 Nevertheless, they have caught many regressions and without a better alternativ
2276 e it is important to keep them up-to-date and understand how they work.
2279 \begin_layout Standard
2281 \begin_inset Quotes eld
2285 \begin_inset Quotes erd
2288 documentation, template, and example documents.
2289 In addition, there are a number of dedicated sample documents in the
2290 \begin_inset Flex Code
2293 \begin_layout Plain Layout
2299 subfolder of the \SpecialChar LyX
2300 source code distribution.
2301 All samples are (after copying and eventual processing by scripts) exported
2302 to various output formats via the
2303 \begin_inset Flex Code
2306 \begin_layout Plain Layout
2312 command line option.
2313 The tests checks for errors reported by LyX.
2314 (However, error-free export is no guarantee for an error-free output document.)
2317 \begin_layout Paragraph
2318 \begin_inset CommandInset label
2320 name "par:when-to-run-an-export-test"
2324 Expectations of LyX developers
2327 \begin_layout Standard
2328 Because the export tests are integration tests and take a long time to run,
2329 LyX developers are rarely expected to run all of the tests.
2330 Here are some good practices to follow by developers:
2333 \begin_layout Itemize
2334 When making a non-trivial change to a .layout file, run the export and layout
2335 tests corresponding with that .layout file.
2338 \begin_layout Itemize
2339 When making non-trivial changes to a .lyx file, run the export tests correspondin
2340 g to that .lyx file.
2345 \begin_layout Plain Layout
2346 This rule is due to revision.
2350 \begin_layout Plain Layout
2351 There is an objection from the documentation maintainer that working on
2352 the documentation must not be complicated by having to consider non-standard
2356 \begin_layout Itemize
2357 successful compiling/testing an edited documentation file with pdflatex
2358 suffices to ensure it can be commited, not tests with other exports are
2362 \begin_layout Plain Layout
2363 If sudden failures with other exports due to “half-tested” documentation
2364 updates are a problem for the test maintainer, the test suite should use
2368 \begin_layout Itemize
2369 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2372 \begin_layout Itemize
2373 updated regularely (but on a time chosen by the test suite maintainer) from
2374 the originals in lib/doc/
2377 \begin_layout Plain Layout
2381 \begin_layout Itemize
2382 no test will fail due to ongoing work on documentation,
2385 \begin_layout Itemize
2386 the documentation is still tested in full (with some delay),
2389 \begin_layout Itemize
2390 failures with non-default export can be examined and handled accordingly
2391 in one run with the cache update,
2394 \begin_layout Itemize
2395 “interesting failures” (like the nested-language+polyglossia problem in
2396 es/Customization can be separated and moved into dedicated test samples.
2404 \begin_layout Itemize
2405 When making non-trivial changes to LyX's \SpecialChar LaTeX
2407 touching the encoding code or package handling code that you expect will
2408 change the exported \SpecialChar LaTeX
2413 \begin_layout Standard
2414 \paragraph_spacing single
2415 Consider running all of the export tests before and after your change.
2416 If there are differences, please reconcile these (i.e.
2417 fix the bug or fix the tests)
2422 Ask for help if you're not sure what to.
2425 \begin_layout Standard
2426 If you do not want to run the tests,
2429 \begin_layout Itemize
2430 post the patch on the list and others will run the tests and eventually
2434 \begin_layout Itemize
2435 commit, but be prepared to fix eventually arising problems or to revert
2436 the commit if there is no easy fix.
2440 \begin_layout Itemize
2441 Understand how to interpret test failures.
2442 If your commit is found to have broken a test, you should be able to interpret
2443 the test results when made aware of them.
2445 \begin_inset CommandInset ref
2447 reference "subsec:Interpreting-export-tests"
2454 \begin_layout Paragraph
2455 \begin_inset CommandInset label
2457 name "par:export-test-output-formats"
2464 \begin_layout Standard
2465 The following output formats are currently tested for each sample document
2467 \begin_inset CommandInset ref
2469 reference "par:Export-test-filtering"
2476 \begin_layout Labeling
2477 \labelwidthstring 00.00.0000
2482 \begin_layout Labeling
2483 \labelwidthstring 00.00.0000
2484 lyx16 LyX 1.6 file format (lyx2lyx)
2487 \begin_layout Labeling
2488 \labelwidthstring 00.00.0000
2489 lyx21 LyX 2.1 file format (lyx2lyx)
2492 \begin_layout Labeling
2493 \labelwidthstring 00.00.0000
2494 xhtml LyXHTML (native LyX HTML export)
2498 \begin_layout Labeling
2499 \labelwidthstring 00.00.0000
2501 \begin_inset space ~
2505 \begin_inset space ~
2512 \begin_layout Labeling
2513 \labelwidthstring pdf5msystemFM
2514 dvi DVI (8-bit latex)
2517 \begin_layout Labeling
2518 \labelwidthstring pdf5msystemFM
2519 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2522 \begin_layout Labeling
2523 \labelwidthstring pdf5msystemFM
2524 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2527 \begin_layout Labeling
2528 \labelwidthstring pdf5msystemFM
2532 \begin_layout Labeling
2533 \labelwidthstring pdf5msystemFM
2534 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2537 \begin_layout Labeling
2538 \labelwidthstring pdf5msystemFM
2539 pdf4_systemF PDF (XeTeX with Unicode fonts)
2542 \begin_layout Labeling
2543 \labelwidthstring pdf5msystemFM
2544 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2547 \begin_layout Labeling
2548 \labelwidthstring pdf5msystemFM
2549 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2553 \begin_layout Labeling
2554 \labelwidthstring 00.00.0000
2556 \begin_inset space ~
2560 \begin_inset space ~
2564 \begin_inset space ~
2568 \begin_inset space ~
2575 \begin_layout Labeling
2576 \labelwidthstring pdf5msystemFM
2577 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2580 \begin_layout Labeling
2581 \labelwidthstring pdf5msystemFM
2582 pdf3 DVI -> PDF (dvipdfm)
2586 \begin_layout Labeling
2587 \labelwidthstring 00.00.0000
2589 \begin_inset space ~
2592 tested: (or only if set as default output format in the document source)
2596 \begin_layout Labeling
2597 \labelwidthstring pdf5msystemFM
2601 \begin_layout Labeling
2602 \labelwidthstring pdf5msystemFM
2603 luatex LaTeX (LuaTeX)
2606 \begin_layout Labeling
2607 \labelwidthstring pdf5msystemFM
2608 dviluatex LaTeX (dviluatex)
2611 \begin_layout Labeling
2612 \labelwidthstring pdf5msystemFM
2613 pdflatex LaTeX (pdflatex)
2616 \begin_layout Labeling
2617 \labelwidthstring pdf5msystemFM
2618 platex LaTeX (pLaTeX)
2621 \begin_layout Labeling
2622 \labelwidthstring pdf5msystemFM
2626 \begin_layout Labeling
2627 \labelwidthstring pdf5msystemFM
2628 eps3 EPS (encapsulated Postscript) (cropped)
2631 \begin_layout Labeling
2632 \labelwidthstring pdf5msystemFM
2633 ps DVI -> Postscript (dvips)
2636 \begin_layout Labeling
2637 \labelwidthstring pdf5msystemFM
2641 \begin_layout Labeling
2642 \labelwidthstring pdf5msystemFM
2643 text (nor text2, ..., text4)
2646 \begin_layout Labeling
2647 \labelwidthstring pdf5msystemFM
2651 \begin_layout Labeling
2652 \labelwidthstring pdf5msystemFM
2656 \begin_layout Labeling
2657 \labelwidthstring pdf5msystemFM
2661 \begin_layout Labeling
2662 \labelwidthstring pdf5msystemFM
2667 \begin_layout Paragraph
2668 \begin_inset CommandInset label
2670 name "par:Configuring-ctests"
2674 Configuring the tests
2677 \begin_layout Standard
2678 To enable the export autotests, add the
2679 \begin_inset Flex Code
2682 \begin_layout Plain Layout
2683 -DLYX_ENABLE_EXPORT_TESTS=ON
2692 \begin_layout Standard
2693 \begin_inset Flex Code
2696 \begin_layout Plain Layout
2697 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2705 \begin_layout Standard
2707 This flag will increase the time for the cmake command by several seconds,
2708 mainly because of the process of inverting tests (see Section
2709 \begin_inset CommandInset ref
2711 reference "subsec:Interpreting-export-tests"
2718 \begin_layout Paragraph
2719 \begin_inset CommandInset label
2721 name "par:ctest-options"
2728 \begin_layout Standard
2729 To run all tests, in the build directory simply run the command
2730 \begin_inset Flex Code
2733 \begin_layout Plain Layout
2740 A full, up-to-date TeXLive installation is recommended to run the tests.
2741 Otherwise, some tests will fail.
2742 Tests with additional requirements are labeled
2743 \begin_inset Quotes eld
2746 unreliable:nonstandard
2747 \begin_inset Quotes erd
2754 \begin_layout Standard
2755 To run only some of the tests, use command line options (see examples below):
2758 \begin_layout Labeling
2759 \labelwidthstring -R
2760 \begin_inset Flex Code
2763 \begin_layout Plain Layout
2769 Run only the tests whose names match the given regular expression.
2772 \begin_layout Labeling
2773 \labelwidthstring -R
2774 \begin_inset Flex Code
2777 \begin_layout Plain Layout
2783 Run only the tests whose labels match the given regular expression.
2784 A test may have more that one label.
2788 \begin_layout Labeling
2789 \labelwidthstring -R
2790 \begin_inset Flex Code
2793 \begin_layout Plain Layout
2799 Exclude the tests whose names match the given regular expression.
2802 \begin_layout Labeling
2803 \labelwidthstring -R
2804 \begin_inset Flex Code
2807 \begin_layout Plain Layout
2813 Exclude the tests whose labels match the given regular expression.
2814 Cannot be combined with
2815 \begin_inset Flex Code
2818 \begin_layout Plain Layout
2827 \begin_layout Standard
2828 The following options help to find good selection patterns:
2831 \begin_layout Labeling
2832 \labelwidthstring -R
2833 \begin_inset Flex Code
2836 \begin_layout Plain Layout
2842 List the tests that would be run but not actually run them.
2847 \begin_layout Standard
2848 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2849 to know how many tests there are or whether your
2850 \begin_inset Flex Code
2853 \begin_layout Plain Layout
2859 regular expression did what you expected.
2863 \begin_layout Labeling
2864 \labelwidthstring -R
2865 \begin_inset Flex Code
2868 \begin_layout Plain Layout
2869 \SpecialChar nobreakdash
2870 \SpecialChar nobreakdash
2876 print the list of all labels associated with the test set.
2877 Can also be combined with -R, -L, -E, ...
2881 \begin_layout Standard
2882 Other useful options are:
2885 \begin_layout Labeling
2886 \labelwidthstring -R
2887 \begin_inset Flex Code
2890 \begin_layout Plain Layout
2896 Run the tests in parallel using the given number of jobs.
2900 \begin_layout Standard
2901 We are still working on getting the tests to run in parallel.
2902 However, when running the tests in parallel, sometimes tests fail that
2903 pass when run sequentially.
2904 A reasonable approach is to first run the tests in parallel and then run
2905 the failed tests sequentially.
2908 \begin_layout Standard
2909 For example, to run 8 jobs at a time:
2912 \begin_layout Standard
2913 \begin_inset Flex Code
2916 \begin_layout Plain Layout
2925 \begin_layout Standard
2926 \begin_inset Flex Code
2929 \begin_layout Plain Layout
2930 ctest \SpecialChar nobreakdash
2931 \SpecialChar nobreakdash
2940 \begin_layout Standard
2941 When specifying a subset of the tests (e.g.
2943 \begin_inset Flex Code
2946 \begin_layout Plain Layout
2947 \SpecialChar nobreakdash
2953 ), the same subset must be specified when using the
2954 \begin_inset Flex Code
2957 \begin_layout Plain Layout
2958 \SpecialChar nobreakdash
2959 \SpecialChar nobreakdash
2965 option because it is the test numbers that are used to index which tests
2966 failed on the previous run.
2969 \begin_layout Standard
2971 Note that some tests cannot be run in parallel.
2972 These tests are marked in the code with the
2973 \begin_inset Flex Code
2976 \begin_layout Plain Layout
2987 \begin_layout Labeling
2988 \labelwidthstring -R
2989 \begin_inset Flex Code
2992 \begin_layout Plain Layout
2993 \SpecialChar nobreakdash
2994 \SpecialChar nobreakdash
3000 Set a global timeout on all tests that do not already have a timeout set
3005 \begin_layout Standard
3006 There have been bugs in LyX and in \SpecialChar LaTeX
3007 which cause compilation to hang, and
3008 without a timeout a test might never stop (in one case there was even a
3010 If a test times out, the
3011 \begin_inset Flex Code
3014 \begin_layout Plain Layout
3020 command exits with error, but you can distinguish between a timed out test
3021 and a failed test in the output reported at the end of the
3022 \begin_inset Flex Code
3025 \begin_layout Plain Layout
3035 \begin_layout Standard
3037 \begin_inset Flex Code
3040 \begin_layout Plain Layout
3046 ) the full list of command line options.
3049 \begin_layout Paragraph
3053 \begin_layout Itemize
3054 run only the export tests:
3055 \begin_inset Flex Code
3058 \begin_layout Plain Layout
3067 \begin_layout Itemize
3069 \begin_inset Flex Code
3072 \begin_layout Plain Layout
3073 ctest -L "inverted|suspended"
3081 \begin_layout Itemize
3082 list all export tests which match any of the labelling patterns:
3083 \begin_inset Flex Code
3086 \begin_layout Plain Layout
3097 \begin_layout Itemize
3098 exclude rarely used output formats and post-processing tests
3099 \begin_inset Flex Code
3102 \begin_layout Plain Layout
3103 ctest -L export -E "_(texF|dvi3|pdf3?)"
3111 \begin_layout Paragraph
3112 \begin_inset CommandInset label
3114 name "subsec:Interpreting-export-tests"
3118 Interpreting the export test results
3121 \begin_layout Standard
3122 A test can fail for several reasons, not all of them bad.
3125 \begin_layout Enumerate
3126 A new or edited sample document may be incompatible with some output formats.
3129 \begin_layout Enumerate
3130 A dependency is not met (e.g.
3131 the \SpecialChar LaTeX
3133 One hint that this is the case is that the corresponding
3134 \begin_inset Flex Code
3137 \begin_layout Plain Layout
3143 test will likely also fail.
3146 \begin_layout Enumerate
3147 An inverted test fails to fail (i.e.
3148 export that previously failed now works).
3151 \begin_layout Enumerate
3152 An external dependency was updated (e.g.
3157 \begin_layout Enumerate
3158 A recent code change introduced a bug.
3161 \begin_layout Enumerate
3162 \begin_inset CommandInset label
3168 A change in a document exposed a previously unknown bug or an incompatibility
3169 with an export format (e.g.
3170 Lua\SpecialChar LaTeX
3174 \begin_layout Standard
3175 Because the .lyx files are exported in several formats, it is not surprising
3176 that many of the exports fail.
3177 This expectation of failure is addressed by
3178 \begin_inset Quotes eld
3182 \begin_inset Quotes erd
3185 the tests, that is, by marking the test as
3186 \begin_inset Quotes eld
3190 \begin_inset Quotes erd
3193 if the export exits with error and as
3194 \begin_inset Quotes eld
3198 \begin_inset Quotes erd
3201 if the export succeeds
3206 It follows that these expected failures will not show up as failed tests
3207 in the test results and thus will not pollute the
3208 \begin_inset Quotes eld
3212 \begin_inset Quotes erd
3216 If the export actually succeeds, then the test will fail.
3217 The purpose of this failure is to get your attention—something has changed,
3218 possibly for the better.
3221 \begin_layout Standard
3222 We try to document why a test is inverted or ignored.
3223 See the comment (prefixed with
3224 \begin_inset Flex Code
3227 \begin_layout Plain Layout
3233 ) above the block in which the test is listed as inverted or ignored in
3235 \begin_inset Flex Code
3238 \begin_layout Plain Layout
3239 development/autotests/invertedTests
3245 \begin_inset Flex Code
3248 \begin_layout Plain Layout
3249 development/autotests/unreliableTests
3255 \begin_inset Flex Code
3258 \begin_layout Plain Layout
3259 development/autotests/ignoredTests
3268 \begin_layout Standard
3269 A good question is why do we enable the tests for non-default formats? The
3270 answer is that if a non-default route is broken it is often because a bug
3271 was introduced in LyX and not because a document-specific change was made
3272 that is not supported by the route.
3273 In other words, there is a high signal/noise ratio in the export tests
3274 for some non-default formats.
3278 \begin_layout Standard
3279 When a test or several tests fail, consider checking the files in the
3280 \begin_inset Flex Code
3283 \begin_layout Plain Layout
3289 subdirectory of your build directory.
3290 In this subdirectory are three files: the file
3291 \begin_inset Flex Code
3294 \begin_layout Plain Layout
3300 simply lists the tests that failed on your last
3301 \begin_inset Flex Code
3304 \begin_layout Plain Layout
3311 \begin_inset Flex Code
3314 \begin_layout Plain Layout
3320 file contains the output from the tests (and often has details explaining
3321 why a test failed); and the
3322 \begin_inset Flex Code
3325 \begin_layout Plain Layout
3331 file lists the times that it took to run the tests.
3334 \begin_layout Paragraph
3335 What action should you take if a test fails?
3338 \begin_layout Standard
3339 \paragraph_spacing single
3340 It is always good to check manually why something fails and if it passes
3341 if the PDF output is good.
3344 \begin_layout Itemize
3345 Generally, if a change breaks compilation for the target format (for the
3346 manuals pdf2) without solving some important other issue,
3348 fix or revert the commit
3350 that led to failure.
3353 \begin_layout Itemize
3354 If it is not possible to (immediately) fix the failure but there are reasons
3355 not to revert the commit (e.g.
3356 it fixes another more important issue),
3360 the failing test case (see
3361 \begin_inset CommandInset ref
3363 reference "par:Inverted-tests"
3370 \begin_layout Itemize
3375 test case fails because the export now works,
3379 the test by removing the pattern from the
3380 \begin_inset Quotes eld
3384 \begin_inset Quotes erd
3388 \begin_inset CommandInset ref
3390 reference "par:Inverted-tests"
3397 \begin_layout Itemize
3398 If the export did not fail previously but led to wrong output (PDF, say),
3402 \begin_layout Plain Layout
3403 Non-failing test with wrong output should be labeled as
3404 \begin_inset Quotes eld
3407 unreliable:wrong_output
3408 \begin_inset Quotes erd
3412 \begin_inset CommandInset ref
3414 reference "par:Unreliable-tests"
3423 it is in fact an improvement when the test now fails.
3428 the failing test case (see
3429 \begin_inset CommandInset ref
3431 reference "par:Inverted-tests"
3438 \begin_layout Itemize
3439 In case of tests failing due to missing requirements (tests labeled
3440 \begin_inset Quotes eld
3443 unreliable:nonstandard
3444 \begin_inset Quotes erd
3447 or testing on a system with only a subset of TeXLive installed), ignore
3448 the failure, ask for someone else to run the test, or install the missing
3449 resources and try again.
3452 \begin_layout Itemize
3453 Check the log file Testing/Temporary/LastTest.log.
3454 In case of latex-errors rerun the failing test with environment variable
3455 'LYX_DEBUG_LATEX' set to '1'.
3456 This will include latex messages in LastTest.log, so it should be easier
3457 to interpret the fail-reason.
3460 \begin_layout Paragraph
3461 \begin_inset CommandInset label
3463 name "par:Inverted-tests"
3470 \begin_layout Standard
3471 Test cases whose name matches a pattern in the file
3472 \begin_inset Flex Code
3475 \begin_layout Plain Layout
3476 development/autotests/invertedTests
3486 They get also the test property
3487 \begin_inset Flex Code
3490 \begin_layout Plain Layout
3497 they are reported as failing if the export works without error
3498 \begin_inset Flex URL
3501 \begin_layout Plain Layout
3503 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3511 \begin_layout Standard
3512 Add failing cases to this file, if they cannot be solved
3513 \begin_inset Quotes eld
3517 \begin_inset Quotes erd
3520 but it is expected that the export will work in a foreseeable future, e.g.
3521 low priority issues like failures to export to a non-target format (for
3522 the manuals everything except pdf2).
3525 \begin_layout Standard
3526 The following sublabels are currently present in
3527 \begin_inset Flex Code
3530 \begin_layout Plain Layout
3539 \begin_layout Description
3540 todo test failures that require attention:
3544 \begin_layout Itemize
3545 minor issues to explore and properly sort later,
3548 \begin_layout Itemize
3552 \begin_layout Itemize
3553 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3557 \begin_layout Description
3558 lyxbugs LyX bugs with a Trac number.
3561 \begin_layout Description
3562 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3566 \begin_layout Standard
3567 "Wontfix" if demonstrating correct use and OK in the default output format.
3571 \begin_layout Description
3572 texissues Export fails due to LaTeX limitations like non-ASCII characters
3573 in verbatim or listings, incompatible packages, ...
3577 \begin_layout Standard
3578 "Wontfix" if documents demonstrate correct use in the default output format:
3581 \begin_layout Itemize
3582 If the source can be made more robust without becoming "hackish", fix the
3586 \begin_layout Itemize
3587 if LyX could be enhanced to care for a permanent TeX limitation, file a
3588 ticket at trac and add a pattern under lyxbugs,
3591 \begin_layout Itemize
3592 otherwise, add a pattern here.
3596 \begin_layout Description
3597 attic Documents in the attic (kept for reference and format conversion test).
3599 \begin_inset Quotes eld
3603 \begin_inset Quotes erd
3609 \begin_layout Subparagraph
3613 \begin_layout Standard
3614 Test cases whose name additionally matches a pattern in the file
3615 \begin_inset Flex Code
3618 \begin_layout Plain Layout
3619 development/autotests/suspendedTests
3637 This means they are not executed using
3638 \begin_inset Flex Code
3641 \begin_layout Plain Layout
3648 \begin_inset Flex Code
3651 \begin_layout Plain Layout
3658 However, they also get the test property
3659 \begin_inset Flex Code
3662 \begin_layout Plain Layout
3669 they are reported as failing if the export works without error.
3670 From time to time they still have to be checked using
3671 \begin_inset Flex Code
3674 \begin_layout Plain Layout
3683 \begin_layout Standard
3684 These tests are suspended, because the export fails for known reasons which
3685 cannot ATM be resolved.
3686 But it is expected the reason might disappear in the future.
3687 Be it new TL or better handling in \SpecialChar LyX
3691 \begin_layout Standard
3692 For ctest commands without the
3693 \begin_inset Flex Code
3696 \begin_layout Plain Layout
3702 parameter nothing changes.
3703 Suspended or not, tests will be executed depending only on the selecting
3704 regular expression given to the ctest command (see
3705 \begin_inset CommandInset ref
3707 reference "par:ctest-options"
3714 \begin_layout Paragraph
3715 \begin_inset CommandInset label
3717 name "par:Unreliable-tests"
3724 \begin_layout Standard
3725 Test cases whose name matches a pattern in the file
3726 \begin_inset Flex Code
3729 \begin_layout Plain Layout
3730 development/autotests/unreliableTests
3742 \begin_layout Standard
3743 These tests are not executed using
3744 \begin_inset Flex Code
3747 \begin_layout Plain Layout
3754 \begin_inset Flex Code
3757 \begin_layout Plain Layout
3767 \begin_layout Standard
3768 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3769 or pass but should rather fail (wrong output).
3771 \begin_inset Note Note
3774 \begin_layout Plain Layout
3775 *invalid* tests (wrong output) are not *unreliable*.
3776 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3785 \begin_layout Standard
3786 The following sublabels are currently present in
3787 \begin_inset Flex Code
3790 \begin_layout Plain Layout
3799 \begin_layout Description
3800 nonstandard Documents with additional requirements, e.g.
3801 a class or package file not in TeXLive.
3803 \begin_inset Note Note
3806 \begin_layout Plain Layout
3808 \begin_inset Quotes eld
3812 \begin_inset Quotes erd
3816 \begin_inset Quotes eld
3820 \begin_inset Quotes erd
3831 \begin_layout Description
3832 erratic Tests depending on local configuration or the phase of the moon.
3836 \begin_layout Description
3837 varying_versions Tests depending on e.g.
3838 OS or version of a non-TeX-Live dependency.
3839 Note that a full, up-to-date TeX Live installation is required so this
3840 sublabel is about versions of other dependencies.
3843 \begin_layout Description
3845 \begin_inset space ~
3848 output Export does not fail but the resulting document has (undetected)
3853 \begin_layout Standard
3854 \paragraph_spacing single
3855 \begin_inset Note Note
3858 \begin_layout Plain Layout
3859 \paragraph_spacing single
3860 These tests are in a strict sense not unreliable but
3864 (not measuring what they should measure).
3873 \begin_layout Paragraph
3874 \begin_inset CommandInset label
3876 name "par:Export-test-filtering"
3880 Export test filtering
3883 \begin_layout Standard
3884 The assignment of a label to a test is controlled by a set of files with
3885 regular expressions that are matched against the test names.
3888 \begin_layout Description
3889 ignoredTests (small file)
3890 \begin_inset Newline newline
3893 Tests selected here are withdrawn in the configuration step (cf.
3895 \begin_inset CommandInset ref
3897 reference "par:Configuring-ctests"
3905 \begin_layout Labeling
3906 \labelwidthstring 00.00.0000
3907 Input Test of any export combination
3910 \begin_layout Labeling
3911 \labelwidthstring 00.00.0000
3912 Output Stop if tests not selected here
3916 \begin_layout Description
3917 unreliableTests: Tests selected pass or fail dependent on the system where
3919 Selected tests gain the label 'unreliable'.
3923 \begin_layout Labeling
3924 \labelwidthstring 00.00.0000
3925 Input Each test which passed 'ignoredTests'
3928 \begin_layout Labeling
3929 \labelwidthstring 00.00.0000
3930 Output Gain label 'unreliable', proceed with checking for 'inverted'.
3934 \begin_layout Description
3936 \begin_inset space \space{}
3943 \begin_layout Labeling
3944 \labelwidthstring 00.00.0000
3945 Input Each test which passed 'ignoredTests'
3948 \begin_layout Labeling
3949 \labelwidthstring 00.00.0000
3950 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3951 tests are reported as failing if the export works without error.) If no
3952 subselection applies, gain labels 'export' and 'inverted'.
3955 \begin_layout Standard
3956 The following filter perfoms a subselection of 'invertedTests':
3959 \begin_layout Description
3960 suspendedTests Tests selected here gain the label 'suspended' but _not_
3961 'export' or 'inverted', although in ctest they remain inverted.
3962 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3966 \begin_layout Labeling
3967 \labelwidthstring 00.00.0000
3968 Input Each test selected by 'invertedTests'
3971 \begin_layout Labeling
3972 \labelwidthstring 00.00.0000
3973 Output Selected test gains label 'suspended'.
3979 \begin_layout Standard
3980 The following table may clarify label assignement
3983 \begin_layout Standard
3984 \begin_inset space \hspace{}
3989 \begin_inset Tabular
3990 <lyxtabular version="3" rows="6" columns="8">
3991 <features tabularvalignment="middle">
3992 <column alignment="left" valignment="top" width="2cm">
3993 <column alignment="left" valignment="top" width="2.5cm">
3994 <column alignment="left" valignment="top" width="2cm">
3995 <column alignment="center" valignment="top" width="2.5cm">
3996 <column alignment="center" valignment="top">
3997 <column alignment="center" valignment="top">
3998 <column alignment="center" valignment="top">
3999 <column alignment="center" valignment="top">
4001 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4004 \begin_layout Plain Layout
4005 Test matching pattern in file:
4010 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4013 \begin_layout Plain Layout
4019 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4022 \begin_layout Plain Layout
4028 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4031 \begin_layout Plain Layout
4037 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4040 \begin_layout Plain Layout
4046 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4049 \begin_layout Plain Layout
4055 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4058 \begin_layout Plain Layout
4064 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4067 \begin_layout Plain Layout
4075 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4078 \begin_layout Plain Layout
4079 ignored\SpecialChar softhyphen
4085 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4088 \begin_layout Plain Layout
4089 unreliable\SpecialChar softhyphen
4095 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4098 \begin_layout Plain Layout
4099 inverted\SpecialChar softhyphen
4105 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4108 \begin_layout Plain Layout
4109 suspended\SpecialChar softhyphen
4115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4118 \begin_layout Plain Layout
4124 <cell alignment="center" valignment="top" topline="true" usebox="none">
4127 \begin_layout Plain Layout
4133 <cell alignment="center" valignment="top" topline="true" usebox="none">
4136 \begin_layout Plain Layout
4142 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4145 \begin_layout Plain Layout
4153 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4156 \begin_layout Plain Layout
4162 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4165 \begin_layout Plain Layout
4171 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4174 \begin_layout Plain Layout
4180 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4183 \begin_layout Plain Layout
4189 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4192 \begin_layout Plain Layout
4198 <cell alignment="center" valignment="top" topline="true" usebox="none">
4201 \begin_layout Plain Layout
4207 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4210 \begin_layout Plain Layout
4216 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4219 \begin_layout Plain Layout
4227 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4230 \begin_layout Plain Layout
4236 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4239 \begin_layout Plain Layout
4241 \begin_inset Newline newline
4245 \begin_inset Newline newline
4253 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4256 \begin_layout Plain Layout
4262 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4265 \begin_layout Plain Layout
4271 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4274 \begin_layout Plain Layout
4280 <cell alignment="center" valignment="top" topline="true" usebox="none">
4283 \begin_layout Plain Layout
4289 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4292 \begin_layout Plain Layout
4298 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4301 \begin_layout Plain Layout
4309 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4312 \begin_layout Plain Layout
4318 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4321 \begin_layout Plain Layout
4327 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4330 \begin_layout Plain Layout
4336 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4339 \begin_layout Plain Layout
4345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4348 \begin_layout Plain Layout
4354 <cell alignment="center" valignment="top" topline="true" usebox="none">
4357 \begin_layout Plain Layout
4363 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4366 \begin_layout Plain Layout
4372 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4375 \begin_layout Plain Layout
4383 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4386 \begin_layout Plain Layout
4392 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4395 \begin_layout Plain Layout
4401 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4404 \begin_layout Plain Layout
4410 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4413 \begin_layout Plain Layout
4419 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4422 \begin_layout Plain Layout
4428 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4431 \begin_layout Plain Layout
4437 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4440 \begin_layout Plain Layout
4446 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4449 \begin_layout Plain Layout
4463 \begin_layout Standard
4464 \begin_inset Note Note
4467 \begin_layout Plain Layout
4469 \begin_inset Quotes eld
4473 \begin_inset Quotes erd
4476 filter, this would be far less complicated:
4479 \begin_layout Plain Layout
4480 \begin_inset Tabular
4481 <lyxtabular version="3" rows="6" columns="7">
4482 <features tabularvalignment="middle">
4483 <column alignment="left" valignment="top" width="0pt">
4484 <column alignment="left" valignment="top" width="0pt">
4485 <column alignment="left" valignment="top" width="0pt">
4486 <column alignment="center" valignment="top">
4487 <column alignment="center" valignment="top">
4488 <column alignment="center" valignment="top">
4489 <column alignment="center" valignment="top">
4491 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4494 \begin_layout Plain Layout
4495 Test matching pattern in file:
4500 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4503 \begin_layout Plain Layout
4509 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4512 \begin_layout Plain Layout
4518 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4521 \begin_layout Plain Layout
4527 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4530 \begin_layout Plain Layout
4536 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4539 \begin_layout Plain Layout
4545 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4548 \begin_layout Plain Layout
4556 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4559 \begin_layout Plain Layout
4565 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4568 \begin_layout Plain Layout
4574 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4577 \begin_layout Plain Layout
4583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4586 \begin_layout Plain Layout
4592 <cell alignment="center" valignment="top" topline="true" usebox="none">
4595 \begin_layout Plain Layout
4601 <cell alignment="center" valignment="top" topline="true" usebox="none">
4604 \begin_layout Plain Layout
4610 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4613 \begin_layout Plain Layout
4621 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4624 \begin_layout Plain Layout
4630 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4633 \begin_layout Plain Layout
4639 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4642 \begin_layout Plain Layout
4648 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4651 \begin_layout Plain Layout
4657 <cell alignment="center" valignment="top" topline="true" usebox="none">
4660 \begin_layout Plain Layout
4666 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4669 \begin_layout Plain Layout
4675 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4678 \begin_layout Plain Layout
4686 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4689 \begin_layout Plain Layout
4695 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4698 \begin_layout Plain Layout
4704 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4707 \begin_layout Plain Layout
4713 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4716 \begin_layout Plain Layout
4722 <cell alignment="center" valignment="top" topline="true" usebox="none">
4725 \begin_layout Plain Layout
4731 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4734 \begin_layout Plain Layout
4740 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4743 \begin_layout Plain Layout
4751 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4754 \begin_layout Plain Layout
4760 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4763 \begin_layout Plain Layout
4769 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4772 \begin_layout Plain Layout
4778 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4781 \begin_layout Plain Layout
4787 <cell alignment="center" valignment="top" topline="true" usebox="none">
4790 \begin_layout Plain Layout
4796 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4799 \begin_layout Plain Layout
4805 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4808 \begin_layout Plain Layout
4816 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4819 \begin_layout Plain Layout
4825 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4828 \begin_layout Plain Layout
4834 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4837 \begin_layout Plain Layout
4843 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4846 \begin_layout Plain Layout
4852 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4855 \begin_layout Plain Layout
4861 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4864 \begin_layout Plain Layout
4870 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4873 \begin_layout Plain Layout
4892 \begin_layout Subsubsection
4896 \begin_layout Standard
4897 These tests check whether a .lyx file loads without any terminal messages.
4898 They correspond to the manual operations of simply opening a .lyx file on
4899 the terminal, exiting LyX once the file is loaded, and then checking whether
4900 there is any output from the terminal.
4901 These tests are useful for catching malformed .lyx files and parsing bugs.
4902 They can also be used to find a .lyx file in which an instance of something
4904 To do this, compile LyX with a local patch that outputs something to the
4905 terminal when an instance is found, and then run the check_load tests to
4906 see if any fail, which would mean that the situation occurs in the LyX
4907 documentation files corresponding to the failed tests.
4908 These tests are expectedly fragile: any LyX diagnostic message, which is
4909 not necessarily an error, would cause the tests to fail.
4910 Similarly, any message output by a library (e.g.
4911 Qt) would also cause failure.
4912 There are some messages that the check_load tests are instructed to ignore,
4913 which are stored in the file
4914 \begin_inset Flex Code
4917 \begin_layout Plain Layout
4918 development/autotests/filterCheckWarnings
4926 \begin_layout Standard
4927 Under cmake, the tests are labeled as 'load'.
4930 \begin_layout Subsubsection
4934 \begin_layout Standard
4935 Automated tests based on the "MonKey Testing" keytest program are enabled
4936 if the necessary dependencies are found and if the CMake flag
4937 \begin_inset Flex Code
4940 \begin_layout Plain Layout
4941 -DLYX_ENABLE_KEYTESTS=ON
4947 They are documented in the README document in
4948 \begin_inset Flex Code
4951 \begin_layout Plain Layout
4952 development/autotests
4957 subfolder of the \SpecialChar LyX
4958 source code distribution.
4961 \begin_layout Subsubsection
4965 \begin_layout Standard
4966 These tests combine lyx2lyx tests with check_load tests.
4967 They fail if either fails.
4970 \begin_layout Subsubsection
4974 \begin_layout Standard
4975 The URL tests are enabled with the
4976 \begin_inset Flex Code
4979 \begin_layout Plain Layout
4980 -DLYX_ENABLE_URLTESTS=ON
4985 CMake flag and are useful for finding broken links in our documentation
4987 If a URL test fails, to see which link in particular was reported as broken,
4989 \begin_inset Flex Code
4992 \begin_layout Plain Layout
4999 These tests are extremely fragile (e.g.
5000 a test can depend on your Internet connection) and a failed URL test should
5001 not be taken too seriously.
5002 URL tests are labeled as
5007 \begin_layout Paragraph
5011 \begin_layout Standard
5012 cmake is required to run the \SpecialChar LyX
5013 tests, running them is not implemented for
5017 \begin_layout Standard
5018 The appropriate commands are:
5021 \begin_layout Itemize
5027 \begin_inset Newline newline
5030 runs all tests with label
5035 \begin_layout Itemize
5038 ctest -R 'check_.*urls'
5041 \begin_inset Newline newline
5044 runs the tests 'check_accessible_urls'
5047 \begin_layout Standard
5048 Associated test results can be examined in ctest-log directory in files
5049 of the form 'LastFailed.*URLS.log'
5052 \begin_layout Section
5053 Development policies
5056 \begin_layout Standard
5057 This chapter lists some guidelines that should be followed.
5058 This list is not complete, and many guidelines are in separate chapters,
5060 \begin_inset Quotes eld
5063 When is an update of the .lyx file format number needed?
5064 \begin_inset Quotes erd
5068 \begin_inset CommandInset ref
5070 reference "sec:When-is-an"
5077 \begin_layout Subsection
5078 When to set a fixed milestone?
5081 \begin_layout Standard
5082 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5086 \begin_layout Enumerate
5087 Somebody is actively working on a fix.
5090 \begin_layout Enumerate
5091 The bug is so severe that it would block the release if it is not fixed.
5094 \begin_layout Standard
5095 If a bug is important, but nobody is working on it, and it is no showstopper,
5096 use a milestone like 2.1.x or 2.2.x.
5097 For all other bugs, do not set a milestone at all.
5100 \begin_layout Subsection
5101 Can we add rc entries in stable branch?
5104 \begin_layout Standard
5106 We are supposed to increase the prefs2prefs version number with such things.
5109 \begin_layout Section
5110 \begin_inset CommandInset label
5112 name "sec:Documentation-policies"
5116 Documentation policies
5119 \begin_layout Subsection
5123 \begin_layout Standard
5125 \begin_inset space ~
5128 rules in editing the docs:
5131 \begin_layout Enumerate
5132 \begin_inset CommandInset label
5134 name "enu:If-you-are"
5138 If you are not the maintainer of a doc file or a chapter/section, you MUST
5139 use change tracking so that the maintainer could review your changes
5142 \begin_layout Enumerate
5143 Respect the formatting of the document.
5144 The different files use different formatting styles.
5145 That is OK and has historic reasons nobody fully knows ;-).
5146 But it is important to be consistent within one file.
5149 \begin_layout Enumerate
5150 All changes you make to a file in one language MUST also go the file in
5151 the other actively maintained languages.
5152 Normally the maintainer does this for you, if you are the maintainer, you
5153 must do this by copying or changing the changed or added text to the other
5154 files so that the translators sees the blue underlined text and know what
5155 they have to translate and what was changed.
5158 \begin_layout Enumerate
5159 You MUST assure that the document is compilable as
5160 \begin_inset Quotes eld
5164 \begin_inset Quotes erd
5167 or the document's default output format after your changes.
5170 \begin_layout Enumerate
5171 All fixes (typos, compilation fixes, updates info etc.) go at first into
5172 the current GIT branch because the user should benefit from all fixes with
5173 every minor release.
5174 Feel free to commit directly to branch as long as you follow rule
5175 \begin_inset space ~
5179 \begin_inset CommandInset ref
5181 reference "enu:If-you-are"
5186 You can immediately commit to master as well.
5189 \begin_layout Enumerate
5190 \begin_inset CommandInset label
5192 name "enu:The-fileformat-of"
5196 The fileformat of a file must not be changed unless you document a new feature
5197 in LyX that requires a new fileformat.
5198 The reason for this rule is to keep it easy for the doc maintainers to
5199 port/backport changes to from master/branch.
5202 \begin_layout Standard
5203 The main documentation consists of these files:
5206 \begin_layout Description
5207 splash.lyx it is the first file you see after an installation.
5208 We assume that a new user sees this.
5209 It is therefore designed to be as simple as possible.
5210 Therefore please don't add any new formatting, only fix typos etc.
5211 Splash.lyx is up to date for \SpecialChar LyX
5212 2.1.x, currently maintained by Uwe Stöhr.
5215 \begin_layout Description
5216 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5218 It therefore uses a limited set of formatting.
5219 For example a standard document class.
5220 Since new users will first learn about the formatting possibilities of
5222 please keep this file that simple.
5223 Intro.lyx is up to date for \SpecialChar LyX
5224 2.1.x, currently maintained by Uwe Stöhr.
5227 \begin_layout Description
5228 Tutorial.lyx our tutorial.
5229 It must be always up to date.
5230 Normally there is nothing to add since we don't want to overwhelm new users
5231 with too much details.
5232 The will learn these details while using \SpecialChar LyX
5233 and we have special manuals.
5234 Tutorial.lyx is up to date for \SpecialChar LyX
5235 2.1.x, currently maintained by Uwe Stöhr.
5238 \begin_layout Description
5239 UserGuide.lyx our main user guide.
5240 It covers a mixture of basic and detailed information.
5241 Some information is also in the Math and EmbeddedObjects manual so that
5242 the UserGuide refers to these files.
5243 UserGuide.lyx is up to date for \SpecialChar LyX
5244 2.1.x, currently maintained by Uwe Stöhr.
5247 \begin_layout Description
5248 EmbeddedObjects.lyx a special manual to explain things like tables floats
5251 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5252 2.1.x, currently maintained by Uwe
5256 \begin_layout Description
5257 Math.lyx a special manual to explain everything regarding math in all detail.
5258 Math.lyx is up to date for \SpecialChar LyX
5259 2.1.x, currently maintained by Uwe Stöhr.
5262 \begin_layout Description
5263 Additional.lyx this manual covers information that would be too much detail
5264 for the UserGuide or would make the UserGuide uncompilable or only compilable
5265 when installing a lot of special \SpecialChar LaTeX
5267 What should be in the UserGuide or better in Additional is a matter of
5269 it is up to you to decide that.
5270 Additional.lyx is not completely up to date for \SpecialChar LyX
5273 \begin_inset space ~
5276 8 is up to date and currently maintained by Uwe Stöhr.
5277 It certainly needs a rewrite and update.
5278 For example many info in chapter
5279 \begin_inset space ~
5282 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5286 \begin_layout Description
5287 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5289 output formats, operating systems, languages etc.
5290 It is currently completely out of date and needs a major rewrite and update.
5291 If you do this please assure that your information are given for all OSes
5292 and \SpecialChar LaTeX
5293 distributions (meaning be as objective as possible).