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
85 \paperpagestyle headings
86 \tracking_changes false
96 Developing \SpecialChar LyX
100 \begin_layout Subtitle
105 by the \SpecialChar LyX
110 \begin_layout Plain Layout
112 If you have comments or error corrections, please send them to the \SpecialChar LyX
115 \begin_inset Flex Code
118 \begin_layout Plain Layout
120 <lyx-docs@lists.lyx.org>
133 \begin_layout Standard
134 \begin_inset CommandInset toc
135 LatexCommand tableofcontents
142 \begin_layout Section
146 \begin_layout Standard
147 This manual documents some aspects of \SpecialChar LyX
149 It is currently rather incomplete, but will hopefully be extended in the
151 Meanwhile, additional information can be found in the
152 \begin_inset Flex Code
155 \begin_layout Plain Layout
161 subfolder of the \SpecialChar LyX
162 source code distribution.
163 This document is not translated, since the development language of \SpecialChar LyX
166 If you just want to use \SpecialChar LyX
167 , then you don't need to read this manual.
168 However, if you want to learn more about how \SpecialChar LyX
169 is developed, or even want
170 to participate in \SpecialChar LyX
171 development, you may find some interesting information
175 \begin_layout Section
179 \begin_layout Standard
181 uses several custom file formats for configuration files and documents.
182 This chapter contains some background concerning these file formats.
183 Several file formats are also described in detail in the regular user documenta
187 \begin_layout Subsection
191 \begin_layout Subsection
192 When is an update of the .lyx file format number needed?
193 \begin_inset CommandInset label
195 name "sec:When-is-an"
202 \begin_layout Standard
203 When you are working on a new feature you may ask yourself whether it needs
204 an update of the .lyx file format number.
205 Whether an update is needed or not is not always obvious.
210 Whenever there is the danger that a previous version of LyX cannot open
211 a file using the new feature, a file format update is needed.
214 \begin_layout Standard
215 The file format change allows lyx2lyx rules to implement backwards compatibility.
216 Below you can find a list of reasons for file format updates with explanations:
219 \begin_layout Description
228 setting Whenever you introduce a new setting that is stored in the document
229 header, a file format update is needed.
232 \begin_layout Description
241 setting If a certain setting becomes obsolete and gets removed, a file format
245 \begin_layout Description
271 \begin_inset space \thinspace{}
278 \begin_layout Description
279 \paragraph_spacing single
292 package The reason for this is that there is no true ERT inset for math
293 formulas: Each command is parsed, and if a user happens to define a local
294 command with the same name as a command that triggers an automatic load
295 of a package, they need to be able to switch off the automatic loading
297 This switch is stored by the
298 \begin_inset Flex Code
301 \begin_layout Plain Layout
310 \begin_layout Description
315 language that is stored in
316 \begin_inset Flex Code
319 \begin_layout Plain Layout
329 \begin_inset Note Note
332 \begin_layout Plain Layout
333 This requirement is under discussion.
342 \begin_layout Description
347 inset Of course a new inset requires a file format update.
350 \begin_layout Description
355 style If a new style or inset layout is added to any layout file or module
356 shipped with \SpecialChar LyX
357 , then a new file format is needed in the master (development)
359 It is possible to backport new styles to the stable version without a file
362 \begin_inset CommandInset ref
364 reference "subsec:Backporting-new-styles"
368 for more information.
371 \begin_layout Description
376 style If a style or inset layout is removed in any layout file or module
377 shipped with \SpecialChar LyX
378 , a new file format is required.
381 \begin_layout Standard
386 layouts and modules do
390 require a file format update (changed 03/16, see
391 \begin_inset CommandInset ref
393 reference "subsec:New-layouts"
401 \begin_layout Standard
402 If you are still unsure, please ask on the development list.
405 \begin_layout Subsection
406 \begin_inset CommandInset label
408 name "subsec:update_lyx_files"
412 How to update the file format number of .lyx files
415 \begin_layout Standard
416 Once you come to the conclusion that a file format update is needed, you
417 should use the following procedure to perform the update:
420 \begin_layout Enumerate
421 Implement and test the new feature, including the reading and writing of
423 Note that any file produced at this stage does not use a valid format,
424 so do not use this version of \SpecialChar LyX
425 for working on any important documents.
428 \begin_layout Enumerate
429 \begin_inset CommandInset label
431 name "enu:Describe_format"
435 Describe the new format in
436 \begin_inset Flex Code
439 \begin_layout Plain Layout
448 \begin_layout Enumerate
449 Update the \SpecialChar LyX
450 file format number in
451 \begin_inset Flex Code
454 \begin_layout Plain Layout
463 \begin_layout Enumerate
464 \begin_inset CommandInset label
466 name "enu:Add-an-entry"
470 Add an entry to both format lists (for conversion and reversion) in
471 \begin_inset Newline newline
475 \begin_inset Flex Code
478 \begin_layout Plain Layout
479 lib/lyx2lyx/lyx_2_3.py
485 Add a conversion routine if needed (e.
486 \begin_inset space \thinspace{}
489 g., a new header setting always needs a conversion that adds the new setting,
490 but a new document language does not need one).
491 Add a reversion routine if needed.
493 \begin_inset Newline newline
496 While the conversion routine is required to produce a document that is equivalen
497 t to the old version, the requirements of the reversion are not that strict.
498 If possible, try to produce a proper reversion, using ERT if needed, but
499 for some features this might be too complicated.
500 In this case, the minimum requirement of the reversion routine is that
501 it produces a valid document which can be read by an older \SpecialChar LyX
503 If absolutely needed, even data loss is allowed for the reversion.
504 (In that case, you might want to add a LyX comment that indicates what
505 you have had to do, so the user is at least warned).
508 \begin_layout Enumerate
509 Since tex2lyx has several implicit file format dependencies caused by sharing
510 code with \SpecialChar LyX
511 , updating the file format of .lyx files produced by tex2lyx at
512 the same time as updating the main .lyx file format is strongly recommended.
513 Therefore, a compiler warning will be issued if the \SpecialChar LyX
514 and tex2lyx .lyx file
515 format numbers differ.
516 In many cases the tex2lyx update requires only the first and last item
521 \begin_layout Enumerate
522 Update the tex2lyx file format number in
523 \begin_inset Flex Code
526 \begin_layout Plain Layout
535 \begin_layout Enumerate
536 If the lyx2lyx conversion from the old to the new format is empty, or if
537 tex2lyx does not yet output the changed feature, you do not need any further
539 Otherwise, search for the changed feature in tex2lyx, and adjust the output
540 according to the lyx2lyx changes.
543 \begin_layout Enumerate
544 Update the tex2lyx test references as described in
545 \begin_inset CommandInset ref
546 LatexCommand formatted
547 reference "sec:Updating-test-references"
555 \begin_layout Enumerate
556 If you did not implement full tex2lyx support for the new feature, add a
558 \begin_inset Flex Code
561 \begin_layout Plain Layout
567 describing the missing bits.
568 Note that it is perfectly fine if you do not add full tex2lyx support for
569 a new feature: The updating recommendation above is only issued for the
570 syntax of the produced .lyx file.
571 It is no problem if some features supported by \SpecialChar LyX
572 are still output as ERT
574 The problems in the past that resulted in the update recommendation were
575 related to mixed version syntax, not ERT.
578 \begin_layout Enumerate
579 It would be nice if you could create a .lyx test file which contains instances
580 of all changed or added features.
581 This could then be used to test lyx2lyx and tex2lyx.
582 Unfortunately, it has not yet been decided how to collect such examples,
583 so please ask on the development list if you want to create one.
586 \begin_layout Enumerate
587 \begin_inset CommandInset label
589 name "enu:updatefiles"
593 Test your lyx2lyx code by updating LyX's .lyx documentation files to the
595 The developer who makes the change knows best what changes to expect when
596 inspecting the resulting diff.
597 Because of this, you might be able to catch a bug in the lyx2lyx code that
598 updates the format just by taking a quick scan through the large diff that
600 \begin_inset Note Note
603 \begin_layout Plain Layout
604 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
605 see which layout update made an unexpected change by looking at the git
606 log of a .lyx file that suffers the problem.
611 To do this, first make sure that there are no changes to the git repository
612 that you will not want to commit (this is needed because it will be convenient
613 to commit with the command
614 \begin_inset Flex Code
617 \begin_layout Plain Layout
624 Then run the following command in the root folder of the source:
625 \begin_inset Flex Code
628 \begin_layout Plain Layout
629 python development/tools/updatedocs.py
635 Look at the resulting changes using the command
636 \begin_inset Flex Code
639 \begin_layout Plain Layout
646 If anything looks surprising, please investigate.
647 Keep in mind that the case of
648 \begin_inset Flex Code
651 \begin_layout Plain Layout
657 is special, because it is first generated with
658 \begin_inset Flex Code
661 \begin_layout Plain Layout
667 before being converted to the latest format.
668 \begin_inset Newline newline
672 \begin_inset Note Greyedout
675 \begin_layout Plain Layout
680 Only commit file format changes in the doc files if these files are using
681 the new feature of the new file format.
687 \begin_inset CommandInset ref
689 reference "enu:The-fileformat-of"
693 of the documentation policies described in sec.
698 \begin_inset CommandInset ref
700 reference "sec:Documentation-policies"
712 \begin_layout Enumerate
713 Finally, commit using
714 \begin_inset Flex Code
717 \begin_layout Plain Layout
726 \begin_layout Subsection
727 Updating the file format number of layout files
730 \begin_layout Standard
731 The procedure for updating the layout files is similar to that in step
732 \begin_inset CommandInset ref
734 reference "enu:updatefiles"
739 \begin_inset CommandInset ref
741 reference "subsec:update_lyx_files"
747 \begin_inset Flex Code
750 \begin_layout Plain Layout
751 python development/tools/updatelayouts.py
757 \begin_inset Flex Code
760 \begin_layout Plain Layout
769 \begin_layout Standard
770 Note that we do not automatically update any local layout used in the
771 \begin_inset Flex Code
774 \begin_layout Plain Layout
780 files shipped with \SpecialChar LyX
781 because users would then not be able to export to older
783 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
784 to open the file in \SpecialChar LyX
785 2.1.x, there would be an error because the file would
786 contain a local layout whose format is too new.
787 The root reason for this is that we do not support converting layouts to
788 older layout formats, as we do for the
789 \begin_inset Flex Code
792 \begin_layout Plain Layout
801 \begin_layout Subsection
802 Updating the file format number of bind/ui files
805 \begin_layout Standard
806 A change to the functionality of existing LFUNs can require a conversion
808 \begin_inset Flex Code
811 \begin_layout Plain Layout
818 \begin_inset Flex Code
821 \begin_layout Plain Layout
827 files, and therefore an increment of the LFUN format, as well as a conversion
829 \begin_inset Flex Code
832 \begin_layout Plain Layout
839 The latter cannot be done automatically and also requires an update of
843 \begin_inset space \space{}
846 of someone who might have made a set of \SpecialChar LyX
847 teaching manuals for use in their
852 \begin_layout Plain Layout
853 \begin_inset Flex URL
856 \begin_layout Plain Layout
858 http://www.lyx.org/trac/ticket/9794
871 \begin_layout Standard
872 To update the LFUN format:
875 \begin_layout Enumerate
876 Increment the LFUN file format number in
877 \begin_inset Flex Code
880 \begin_layout Plain Layout
889 \begin_layout Enumerate
890 Implement the LFUN conversion in
891 \begin_inset Flex Code
894 \begin_layout Plain Layout
895 lib/scripts/prefs2prefs_lfuns.py
903 \begin_layout Enumerate
905 \begin_inset CommandInset ref
907 reference "enu:updatefiles"
912 \begin_inset CommandInset ref
914 reference "subsec:update_lyx_files"
919 \begin_inset Flex Code
922 \begin_layout Plain Layout
928 command, use this command:
929 \begin_inset Flex Code
932 \begin_layout Plain Layout
933 bash development/tools/updatelfuns.sh
940 \begin_inset Note Note
943 \begin_layout Plain Layout
944 This file should really be converted to python.
952 \begin_layout Enumerate
953 Update Info insets in
954 \begin_inset Flex Code
957 \begin_layout Plain Layout
964 To do so, increment the \SpecialChar LyX
965 format and proceed as in
966 \begin_inset CommandInset ref
968 reference "subsec:update_lyx_files"
973 \begin_inset CommandInset ref
975 reference "enu:Describe_format"
980 \begin_inset CommandInset ref
982 reference "enu:updatefiles"
987 In the lyx2lyx implementation (step
988 \begin_inset CommandInset ref
990 reference "enu:Add-an-entry"
994 ), implement a conversion similar to the one in
995 \begin_inset Flex Code
998 \begin_layout Plain Layout
1004 above, as well as a corresponding reversion; for this one can use
1005 \begin_inset Flex Code
1008 \begin_layout Plain Layout
1015 \begin_inset Flex Code
1018 \begin_layout Plain Layout
1019 lib/lyx2lyx/lyx2lyx_tools.py
1028 \begin_layout Subsection
1029 Backporting new styles to the stable version
1030 \begin_inset CommandInset label
1032 name "subsec:Backporting-new-styles"
1039 \begin_layout Standard
1040 Starting with the stable \SpecialChar LyX
1041 2.1 branch, there is a mechanism in place to backport
1042 new styles to the stable version without the need to update the file format.
1043 The basic idea is that the new style definition is automatically copied
1044 to the document preamble so that it can even be used by older minor versions
1045 that did not yet include the style.
1046 To backport a new style to the stable version, the following steps are
1050 \begin_layout Enumerate
1052 \begin_inset Flex Code
1055 \begin_layout Plain Layout
1061 to the style definition in the development version.
1064 \begin_layout Enumerate
1065 Copy the style definition to the stable version, but use
1066 \begin_inset Flex Code
1069 \begin_layout Plain Layout
1076 If needed adjust the format to the one used by the stable version (see
1077 the customization manual for details of the layout file format).
1080 \begin_layout Enumerate
1081 For each update of the style in a later stable version, increase the argument
1083 \begin_inset Flex Code
1086 \begin_layout Plain Layout
1093 (In the stable version, the development version should not be touched.)
1096 \begin_layout Standard
1097 For details about the
1098 \begin_inset Flex Code
1101 \begin_layout Plain Layout
1107 flag see the customization manual.
1109 \begin_inset Flex Code
1112 \begin_layout Plain Layout
1118 support is needed for backported styles: Since the style of the development
1119 version has an infinite version number, it will always be used.
1120 Furthermore, since its version number is less than one, the style will
1121 not be written anymore to the document header for files saved by the new
1125 \begin_layout Section
1126 New layouts and modules
1129 \begin_layout Subsection
1130 \begin_inset CommandInset label
1132 name "subsec:New-layouts"
1139 \begin_layout Standard
1140 Adding a new layout file to the \SpecialChar LyX
1142 \begin_inset Quotes eld
1145 officially supported
1146 \begin_inset Quotes erd
1150 You should therefore think carefully about whether you really want to do
1151 this and discuss it on lyx-devel, since you will need to be prepared to
1152 update and fix the layout if necessary.
1153 If the layout is experimental or for a rarely used document class, then
1154 it may be better to add it to the relevant portion of the \SpecialChar LyX
1158 \begin_inset CommandInset href
1160 target "https://wiki.lyx.org/Layouts/Layouts"
1167 \begin_layout Standard
1168 In older versions of this document, it was stated that new layout files
1169 require a file format change.
1170 After some discussion, it was decided that this is not needed.
1174 \begin_layout Plain Layout
1176 \begin_inset CommandInset href
1178 name "the thread “Proposal for a guide on updating layouts”"
1179 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1192 For reference, here are the arguments on each side
1196 \begin_layout Description
1198 \begin_inset Quotes eld
1201 New layout files are a file format change
1202 \begin_inset Quotes erd
1208 \begin_layout Itemize
1209 All documents produced by 2.2.
1210 \begin_inset Formula $x$
1213 can always be edited and exported even if
1214 \begin_inset Formula $x$
1218 This is important for people using different machines, or exchanging work
1222 \begin_layout Description
1224 \begin_inset Quotes eld
1227 New layout files are not a file format change
1228 \begin_inset Quotes erd
1234 \begin_layout Itemize
1235 No new LaTeX classes can be supported in a stable version, and stable versions
1236 have a typical lifetime of 2–3 years.
1239 \begin_layout Itemize
1240 We have the same situation already with custom layout files: If a document
1241 using a custom layout file is moved between machines or people, then the
1242 layout file needs to be exchanged as well.
1243 If that is not done, then we have a fallback implemented so that such documents
1244 can still be edited, but not exported, and the user gets a warning.
1248 \begin_layout Itemize
1249 The lyx2lyx script cannot do anything useful in such a case.
1253 \begin_layout Standard
1254 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1256 then, you should do the following:
1259 \begin_layout Enumerate
1260 Put your new layout file in
1261 \begin_inset Flex Code
1264 \begin_layout Plain Layout
1271 \begin_inset Flex Code
1274 \begin_layout Plain Layout
1275 git add lib/layouts/newlayout.layout
1280 ) so that it will be committed.
1283 \begin_layout Enumerate
1285 \begin_inset Flex Code
1288 \begin_layout Plain Layout
1294 , so that the new layout actually gets installed.
1297 \begin_layout Enumerate
1299 \begin_inset Flex Code
1302 \begin_layout Plain Layout
1303 lib/doc/LaTeXConfig.lyx
1308 containing in particular a line like
1316 \begin_layout Standard
1317 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1318 \begin_inset Flex Code
1321 \begin_layout Plain Layout
1322 info-insert textclass <name>
1328 This inset will automatically display a boxed
1329 \begin_inset Quotes eld
1333 \begin_inset Quotes erd
1337 \begin_inset Quotes eld
1341 \begin_inset Quotes erd
1344 depending on the availability of the package.
1348 \begin_layout Enumerate
1349 A template or example is strongly encouraged (but not necessarily required).
1350 It is also possible to provide both.
1352 \begin_inset Flex Code
1355 \begin_layout Plain Layout
1362 \begin_inset Flex Code
1365 \begin_layout Plain Layout
1374 \begin_layout Enumerate
1375 Reconfigure \SpecialChar LyX
1379 \begin_layout Enumerate
1380 Ensure the autotests for the new layout pass (see
1381 \begin_inset CommandInset ref
1383 reference "par:when-to-run-an-export-test"
1390 \begin_layout Subsection
1394 \begin_layout Standard
1395 Adding a new module is very similar to adding a new layout.
1396 Therefore, the previous section applies to new modules as well, with two
1400 \begin_layout Enumerate
1401 You only need to add an entry to
1402 \begin_inset Flex Code
1405 \begin_layout Plain Layout
1406 lib/doc/LaTeXConfig.lyx
1411 if the module requires a LaTeX package.
1412 In that case, the command for entering the InsetInfo is:
1413 \begin_inset Flex Code
1416 \begin_layout Plain Layout
1417 \paragraph_spacing single
1418 info-insert package <name>
1426 \begin_layout Enumerate
1427 Modules do not need a template, only an example, which is strongly encouraged
1428 but not necessarily required.
1431 \begin_layout Subsection
1432 Layouts for document classes with incompatible versions
1435 \begin_layout Standard
1436 \begin_inset Note Greyedout
1439 \begin_layout Description
1440 Note: This section is currently only a proposal under discussion.
1441 Please correct/amend as suited.
1442 Remove this note once a consensus is found.
1445 \begin_layout Plain Layout
1447 \begin_inset Quotes eld
1450 Proposal for a guide on updating layouts
1451 \begin_inset Quotes erd
1454 for details and background
1457 \begin_layout Plain Layout
1458 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1466 \begin_layout Standard
1467 Every now and then, there are changes to LaTeX document classes that break
1468 backwards compatibility.
1472 \begin_layout Plain Layout
1473 Uwe has suggested we implement automatic detection of changes in class files.
1474 This could be done by running a script every month that checks if a document
1475 class was changed at CTAN and at the homepages of the scientific journals.
1476 If it reports a change, we can check if our template and layout file are
1477 still usable with the changed document class.
1478 (This is different from the autotests insofar, as this would also catch
1479 changes that do not result in compilation errors.)
1484 Reasons can be a new name for the
1485 \begin_inset Flex Code
1488 \begin_layout Plain Layout
1494 file, removed \SpecialChar LaTeX
1496 How should this best be handled in \SpecialChar LyX
1500 \begin_layout Standard
1501 The idea is to support the new version with a new \SpecialChar LyX
1505 \begin_layout Itemize
1506 Existing documents can still be opened in \SpecialChar LyX
1507 and will continue to work on
1508 systems where the old version is still installed.
1512 \begin_layout Itemize
1513 With differently named
1514 \begin_inset Flex Code
1517 \begin_layout Plain Layout
1523 files, \SpecialChar LyX
1524 can check for the availability of the particular version and reflect
1526 Different document class versions with the same file name are currently
1527 (2.2.x) not detected by the configuration script.
1528 This is planned for 2.3.
1532 \begin_layout Plain Layout
1533 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1536 \begin_layout Plain Layout
1537 However, what we really need is version detection for the configuration,
1538 so that the user can be warned if the required class file has the wrong
1540 (If the class file keeps the name over the version change, only one of
1541 the two layout files generates compilable documents.)
1544 \begin_layout Plain Layout
1545 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1554 \begin_layout Itemize
1555 The new layout can be added both to the master and the stable branches,
1556 in accord with the policy discussed in
1557 \begin_inset CommandInset ref
1558 LatexCommand formatted
1559 reference "subsec:New-layouts"
1564 No lyx2lyx conversion is then required when a new major version is released.
1567 \begin_layout Standard
1568 The user can move an existing document to the new version simply by selecting
1569 a new document class.
1570 This step is well supported by \SpecialChar LyX
1571 , with established methods for handling
1572 unsupported styles and other changes.
1573 This way, no lyx2lyx code is required.
1576 \begin_layout Standard
1577 The steps to support a new version of an existing document class are thus:
1580 \begin_layout Itemize
1581 Create a new layout file including the upstream version in the name (avoid
1582 special characters like spaces and dots), e.g.
1584 \begin_inset Flex Code
1587 \begin_layout Plain Layout
1588 acmsiggraph-v0-92.layout
1596 \begin_layout Itemize
1597 Include the name of the
1598 \begin_inset Flex Code
1601 \begin_layout Plain Layout
1607 file as an optional argument in the
1608 \begin_inset Flex Code
1611 \begin_layout Plain Layout
1619 line and include the version number in the GUI name:
1620 \begin_inset Newline newline
1624 \begin_inset Flex Code
1627 \begin_layout Plain Layout
1630 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1631 \begin_inset space ~
1642 \begin_layout Itemize
1643 Update the GUI name in the old layout file (whose name should not be changed),
1645 \begin_inset Newline newline
1649 \begin_inset Flex Code
1652 \begin_layout Plain Layout
1655 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1656 \begin_inset space ~
1667 \begin_layout Itemize
1668 To avoid duplicate definitions, the new layout can
1669 \begin_inset Flex Code
1672 \begin_layout Plain Layout
1678 the old layout file and add\SpecialChar breakableslash
1679 remove\SpecialChar breakableslash
1680 obsolete\SpecialChar breakableslash
1681 modify settings and styles (similar
1683 \begin_inset Flex Code
1686 \begin_layout Plain Layout
1696 \begin_layout Standard
1697 It may be tempting to let the new layout be the
1698 \begin_inset Quotes eld
1702 \begin_inset Quotes erd
1705 and have the old layout import it.
1706 However, this should not be done because any changes to the new layout
1707 would need undo steps in the importing old layout.
1711 \begin_layout Itemize
1712 If the new LaTeX document class obsoletes the old one, update the example
1713 and template files to use the new layout.
1714 Add a note about the changes (preferably with a pointer to the documentation
1719 \begin_layout Standard
1720 This way, new documents based on the template or example will use the up-to-date
1721 document class version.
1725 \begin_layout Standard
1726 \begin_inset Newpage newpage
1732 \begin_layout Section
1736 \begin_layout Standard
1737 Automated tests are an important tool to detect bugs and regressions in
1738 software development.
1739 Some projects like gcc even require each bug fix to be accompanied by a
1740 test case for the automatic test suite, that would detect this bug.
1741 Testing interactive features automatically is of course very hard, but
1742 core functionality like document import and export can be tested quite
1743 easily, and some tests of this kind exist.
1746 \begin_layout Subsection
1750 \begin_layout Standard
1751 There are attempts to set up a suite of unit tests for LyX.
1754 \begin_layout Standard
1755 TODO: describe what is done and what is still to do.
1758 \begin_layout Subsection
1762 \begin_layout Standard
1763 The tex2lyx tests are located in the
1764 \begin_inset Flex Code
1767 \begin_layout Plain Layout
1773 subfolder of the \SpecialChar LyX
1774 source code distribution.
1775 The actual testing is performed by the simple python script
1776 \begin_inset Flex Code
1779 \begin_layout Plain Layout
1780 src/tex2lyx/test/runtests.py
1786 Each test consists of two files:
1787 \begin_inset Flex Code
1790 \begin_layout Plain Layout
1796 contains the \SpecialChar LaTeX
1797 code that should be tested.
1799 \begin_inset Flex Code
1802 \begin_layout Plain Layout
1808 contains the expected output of tex2lyx.
1809 When a test is run, the actual produced output is compared with the stored
1811 The test passes if both are identical.
1812 The test machinery is also able to generate a file
1813 \begin_inset Flex Code
1816 \begin_layout Plain Layout
1822 by exporting the produced .lyx file with \SpecialChar LyX
1824 This may be useful for roundtrip comparisons.
1827 \begin_layout Subsubsection
1831 \begin_layout Standard
1832 The tex2lyx tests can be run in several ways.
1834 \begin_inset Flex Code
1837 \begin_layout Plain Layout
1843 subfolder of the build directory, the commands
1844 \begin_inset Flex Code
1847 \begin_layout Plain Layout
1853 (cmake, all platforms),
1854 \begin_inset Flex Code
1857 \begin_layout Plain Layout
1863 (cmake, when using a make based build system and not MSVC) or
1864 \begin_inset Flex Code
1867 \begin_layout Plain Layout
1873 (autotools) will run the tex2lyx tests.
1874 Alternatively, in the root of the build directory, the command
1875 \begin_inset Flex Code
1878 \begin_layout Plain Layout
1884 runs all tests whose names match the regex
1885 \begin_inset Quotes eld
1889 \begin_inset Quotes erd
1893 Another way to run the tex2lyx tests in the root build directory is to
1894 instead use the command
1895 \begin_inset Flex Code
1898 \begin_layout Plain Layout
1899 ctest -L '(cmplyx|roundtrip)'
1904 , which runs all tests categorized with the label
1905 \begin_inset Quotes eld
1909 \begin_inset Quotes erd
1913 \begin_inset Quotes eld
1917 \begin_inset Quotes erd
1921 If a test fails, the differences between the expected and actual results
1922 are output in unified diff format.
1925 \begin_layout Subsubsection
1926 Updating test references
1927 \begin_inset CommandInset label
1929 name "sec:Updating-test-references"
1936 \begin_layout Standard
1937 In some cases a changed tex2lyx output is not a test failure, but wanted,
1939 \begin_inset space \thinspace{}
1943 \begin_inset space \space{}
1946 if a tex2lyx bug was fixed, or a new feature was added.
1947 In these cases the stored references need to be updated.
1948 To do so if using autotools, call
1949 \begin_inset Flex Code
1952 \begin_layout Plain Layout
1959 \begin_inset Flex Code
1962 \begin_layout Plain Layout
1968 subdirectory of the build directory.
1969 If instead using CMake, call
1970 \begin_inset Flex Code
1973 \begin_layout Plain Layout
1974 make updatetex2lyxtests
1979 in the build directory or in the
1980 \begin_inset Flex Code
1983 \begin_layout Plain Layout
1989 subdirectory of the build directory.
1993 \begin_layout Plain Layout
1994 Note that this is a case where a make target in the build directory can
1995 affect the source directory, which might not be advisable.
2000 On Windows do the following:
2003 \begin_layout Itemize
2004 Assure that the path to the python.exe is in your system PATH variable.
2007 \begin_layout Itemize
2008 Double-click on the file
2009 \begin_inset Flex Code
2012 \begin_layout Plain Layout
2013 updatetex2lyxtests.vcxproj
2018 in the build directory or in the
2019 \begin_inset Flex Code
2022 \begin_layout Plain Layout
2028 subdirectory of your build directory.
2031 \begin_layout Itemize
2032 In the appearing MSVC program assure that you build the
2036 version, then right-click on the project
2040 in the project explorer and choose then
2043 \begin_inset space ~
2046 Only\SpecialChar menuseparator
2048 \begin_inset space ~
2056 \begin_layout Standard
2057 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2059 Please examine the changed output carefully before committing the changed
2060 files to the repository: Since the test machinery does not do a roundtrip
2062 \begin_inset Formula $\Rightarrow$
2066 \begin_inset Formula $\Rightarrow$
2069 .tex, and does not compare the produced dvi or pdf output, it assumes that
2070 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2072 There is only one chance to detect wrong output: before committing a new
2074 Once it is committed, it is quite difficult to verify whether it is correct.
2077 \begin_layout Standard
2082 update the test references by opening them with \SpecialChar LyX
2083 or directly running lyx2lyx
2085 This would not work, since lyx2lyx and \SpecialChar LyX
2086 produce slightly different files
2087 regarding insignificant whitespace and line breaks.
2090 \begin_layout Subsubsection
2094 \begin_layout Standard
2095 In many cases tests for new features may be added to one of the existing
2096 test files, but sometimes this is not possible or not wanted.
2097 Then a new test file needs to be added:
2100 \begin_layout Enumerate
2102 \begin_inset Flex Code
2105 \begin_layout Plain Layout
2106 src/tex2lyx/test/<test name>.tex
2111 and run tex2lyx in roundtrip mode to produce the file
2112 \begin_inset Flex Code
2115 \begin_layout Plain Layout
2116 src/tex2lyx/test/<test name>.lyx.lyx
2122 This file will be the new reference.
2125 \begin_layout Enumerate
2126 Once you confirmed that the tex2lyx output is correct, add the new files
2127 to the corresponding lists in
2128 \begin_inset Flex Code
2131 \begin_layout Plain Layout
2132 src/tex2lyx/test/runtests.py
2138 \begin_inset Flex Code
2141 \begin_layout Plain Layout
2142 src/tex2lyx/Makefile.am
2148 \begin_inset Flex Code
2151 \begin_layout Plain Layout
2152 src/tex2lyx/test/CMakeLists.txt
2160 \begin_layout Enumerate
2161 Commit the changes to the repository, or send a patch to the development
2162 list and ask for committing if you do not have commit rights.
2165 \begin_layout Subsection
2166 ctest automatic tests
2169 \begin_layout Standard
2170 Some tests are located in the
2171 \begin_inset Flex Code
2174 \begin_layout Plain Layout
2175 development/autotests/
2180 subfolder of the \SpecialChar LyX
2181 source code distribution.
2186 \begin_layout Plain Layout
2187 The README document in this folder only describes the
2188 \begin_inset Quotes eld
2192 \begin_inset Quotes erd
2195 subset of autotests!
2203 \begin_layout Standard
2204 These tests can be run by the commands
2205 \begin_inset Flex Code
2208 \begin_layout Plain Layout
2218 (all platforms) or (when using a make based build system and not MSVC)
2220 \begin_inset Flex Code
2223 \begin_layout Plain Layout
2230 \begin_inset Flex Code
2233 \begin_layout Plain Layout
2244 The test logs are written to the
2245 \begin_inset Flex Code
2248 \begin_layout Plain Layout
2262 \begin_layout Subsubsection
2266 \begin_layout Standard
2267 The export tests are integration tests.
2268 They take longer to run and are more likely to break than the tex2lyx tests.
2269 Nevertheless, they have caught many regressions and without a better alternativ
2270 e it is important to keep them up-to-date and understand how they work.
2273 \begin_layout Standard
2275 \begin_inset Quotes eld
2279 \begin_inset Quotes erd
2282 documentation, template, and example documents.
2283 In addition, there are a number of dedicated sample documents in the
2284 \begin_inset Flex Code
2287 \begin_layout Plain Layout
2293 subfolder of the \SpecialChar LyX
2294 source code distribution.
2295 All samples are (after copying and eventual processing by scripts) exported
2296 to various output formats via the
2297 \begin_inset Flex Code
2300 \begin_layout Plain Layout
2306 command line option.
2307 The tests checks for errors reported by LyX.
2308 (However, error-free export is no guarantee for an error-free output document.)
2311 \begin_layout Paragraph
2312 \begin_inset CommandInset label
2314 name "par:when-to-run-an-export-test"
2318 Expectations of LyX developers
2321 \begin_layout Standard
2322 Because the export tests are integration tests and take a long time to run,
2323 LyX developers are rarely expected to run all of the tests.
2324 Here are some good practices to follow by developers:
2327 \begin_layout Itemize
2328 When making a non-trivial change to a .layout file, run the export and layout
2329 tests corresponding with that .layout file.
2332 \begin_layout Itemize
2333 When making non-trivial changes to a .lyx file, run the export tests correspondin
2334 g to that .lyx file.
2339 \begin_layout Plain Layout
2340 This rule is due to revision.
2344 \begin_layout Plain Layout
2345 There is an objection from the documentation maintainer that working on
2346 the documentation must not be complicated by having to consider non-standard
2350 \begin_layout Itemize
2351 successful compiling/testing an edited documentation file with pdflatex
2352 suffices to ensure it can be commited, not tests with other exports are
2356 \begin_layout Plain Layout
2357 If sudden failures with other exports due to “half-tested” documentation
2358 updates are a problem for the test maintainer, the test suite should use
2362 \begin_layout Itemize
2363 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2366 \begin_layout Itemize
2367 updated regularely (but on a time chosen by the test suite maintainer) from
2368 the originals in lib/doc/
2371 \begin_layout Plain Layout
2375 \begin_layout Itemize
2376 no test will fail due to ongoing work on documentation,
2379 \begin_layout Itemize
2380 the documentation is still tested in full (with some delay),
2383 \begin_layout Itemize
2384 failures with non-default export can be examined and handled accordingly
2385 in one run with the cache update,
2388 \begin_layout Itemize
2389 “interesting failures” (like the nested-language+polyglossia problem in
2390 es/Customization can be separated and moved into dedicated test samples.
2398 \begin_layout Itemize
2399 When making non-trivial changes to LyX's \SpecialChar LaTeX
2401 touching the encoding code or package handling code that you expect will
2402 change the exported \SpecialChar LaTeX
2407 \begin_layout Standard
2408 \paragraph_spacing single
2409 Consider running all of the export tests before and after your change.
2410 If there are differences, please reconcile these (i.e.
2411 fix the bug or fix the tests)
2416 Ask for help if you're not sure what to.
2419 \begin_layout Standard
2420 If you do not want to run the tests,
2423 \begin_layout Itemize
2424 post the patch on the list and others will run the tests and eventually
2428 \begin_layout Itemize
2429 commit, but be prepared to fix eventually arising problems or to revert
2430 the commit if there is no easy fix.
2434 \begin_layout Itemize
2435 Understand how to interpret test failures.
2436 If your commit is found to have broken a test, you should be able to interpret
2437 the test results when made aware of them.
2439 \begin_inset CommandInset ref
2441 reference "subsec:Interpreting-export-tests"
2448 \begin_layout Paragraph
2449 \begin_inset CommandInset label
2451 name "par:export-test-output-formats"
2458 \begin_layout Standard
2459 The following output formats are currently tested for each sample document
2461 \begin_inset CommandInset ref
2463 reference "par:Export-test-filtering"
2470 \begin_layout Labeling
2471 \labelwidthstring 00.00.0000
2476 \begin_layout Labeling
2477 \labelwidthstring 00.00.0000
2478 lyx16 LyX 1.6 file format (lyx2lyx)
2481 \begin_layout Labeling
2482 \labelwidthstring 00.00.0000
2483 lyx21 LyX 2.1 file format (lyx2lyx)
2486 \begin_layout Labeling
2487 \labelwidthstring 00.00.0000
2488 xhtml LyXHTML (native LyX HTML export)
2492 \begin_layout Labeling
2493 \labelwidthstring 00.00.0000
2495 \begin_inset space ~
2499 \begin_inset space ~
2506 \begin_layout Labeling
2507 \labelwidthstring pdf5msystemFM
2508 dvi DVI (8-bit latex)
2511 \begin_layout Labeling
2512 \labelwidthstring pdf5msystemFM
2513 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2516 \begin_layout Labeling
2517 \labelwidthstring pdf5msystemFM
2518 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2521 \begin_layout Labeling
2522 \labelwidthstring pdf5msystemFM
2526 \begin_layout Labeling
2527 \labelwidthstring pdf5msystemFM
2528 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2531 \begin_layout Labeling
2532 \labelwidthstring pdf5msystemFM
2533 pdf4_systemF PDF (XeTeX with Unicode fonts)
2536 \begin_layout Labeling
2537 \labelwidthstring pdf5msystemFM
2538 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2541 \begin_layout Labeling
2542 \labelwidthstring pdf5msystemFM
2543 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2547 \begin_layout Labeling
2548 \labelwidthstring 00.00.0000
2550 \begin_inset space ~
2554 \begin_inset space ~
2558 \begin_inset space ~
2562 \begin_inset space ~
2569 \begin_layout Labeling
2570 \labelwidthstring pdf5msystemFM
2571 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2574 \begin_layout Labeling
2575 \labelwidthstring pdf5msystemFM
2576 pdf3 DVI -> PDF (dvipdfm)
2580 \begin_layout Labeling
2581 \labelwidthstring 00.00.0000
2583 \begin_inset space ~
2586 tested: (or only if set as default output format in the document source)
2590 \begin_layout Labeling
2591 \labelwidthstring pdf5msystemFM
2595 \begin_layout Labeling
2596 \labelwidthstring pdf5msystemFM
2597 luatex LaTeX (LuaTeX)
2600 \begin_layout Labeling
2601 \labelwidthstring pdf5msystemFM
2602 dviluatex LaTeX (dviluatex)
2605 \begin_layout Labeling
2606 \labelwidthstring pdf5msystemFM
2607 pdflatex LaTeX (pdflatex)
2610 \begin_layout Labeling
2611 \labelwidthstring pdf5msystemFM
2612 platex LaTeX (pLaTeX)
2615 \begin_layout Labeling
2616 \labelwidthstring pdf5msystemFM
2620 \begin_layout Labeling
2621 \labelwidthstring pdf5msystemFM
2622 eps3 EPS (encapsulated Postscript) (cropped)
2625 \begin_layout Labeling
2626 \labelwidthstring pdf5msystemFM
2627 ps DVI -> Postscript (dvips)
2630 \begin_layout Labeling
2631 \labelwidthstring pdf5msystemFM
2635 \begin_layout Labeling
2636 \labelwidthstring pdf5msystemFM
2637 text (nor text2, ..., text4)
2640 \begin_layout Labeling
2641 \labelwidthstring pdf5msystemFM
2645 \begin_layout Labeling
2646 \labelwidthstring pdf5msystemFM
2650 \begin_layout Labeling
2651 \labelwidthstring pdf5msystemFM
2655 \begin_layout Labeling
2656 \labelwidthstring pdf5msystemFM
2661 \begin_layout Paragraph
2662 \begin_inset CommandInset label
2664 name "par:Configuring-ctests"
2668 Configuring the tests
2671 \begin_layout Standard
2672 To enable the export autotests, add the
2673 \begin_inset Flex Code
2676 \begin_layout Plain Layout
2677 -DLYX_ENABLE_EXPORT_TESTS=ON
2686 \begin_layout Standard
2687 \begin_inset Flex Code
2690 \begin_layout Plain Layout
2691 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2699 \begin_layout Standard
2701 This flag will increase the time for the cmake command by several seconds,
2702 mainly because of the process of inverting tests (see Section
2703 \begin_inset CommandInset ref
2705 reference "subsec:Interpreting-export-tests"
2712 \begin_layout Paragraph
2713 \begin_inset CommandInset label
2715 name "par:ctest-options"
2722 \begin_layout Standard
2723 To run all tests, in the build directory simply run the command
2724 \begin_inset Flex Code
2727 \begin_layout Plain Layout
2734 A full, up-to-date TeXLive installation is recommended to run the tests.
2735 Otherwise, some tests will fail.
2736 Tests with additional requirements are labeled
2737 \begin_inset Quotes eld
2740 unreliable:nonstandard
2741 \begin_inset Quotes erd
2748 \begin_layout Standard
2749 To run only some of the tests, use command line options (see examples below):
2752 \begin_layout Labeling
2753 \labelwidthstring -R
2754 \begin_inset Flex Code
2757 \begin_layout Plain Layout
2763 Run only the tests whose names match the given regular expression.
2766 \begin_layout Labeling
2767 \labelwidthstring -R
2768 \begin_inset Flex Code
2771 \begin_layout Plain Layout
2777 Run only the tests whose labels match the given regular expression.
2778 A test may have more that one label.
2782 \begin_layout Labeling
2783 \labelwidthstring -R
2784 \begin_inset Flex Code
2787 \begin_layout Plain Layout
2793 Exclude the tests whose names match the given regular expression.
2796 \begin_layout Labeling
2797 \labelwidthstring -R
2798 \begin_inset Flex Code
2801 \begin_layout Plain Layout
2807 Exclude the tests whose labels match the given regular expression.
2808 Cannot be combined with
2809 \begin_inset Flex Code
2812 \begin_layout Plain Layout
2821 \begin_layout Standard
2822 The following options help to find good selection patterns:
2825 \begin_layout Labeling
2826 \labelwidthstring -R
2827 \begin_inset Flex Code
2830 \begin_layout Plain Layout
2836 List the tests that would be run but not actually run them.
2841 \begin_layout Standard
2842 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2843 to know how many tests there are or whether your
2844 \begin_inset Flex Code
2847 \begin_layout Plain Layout
2853 regular expression did what you expected.
2857 \begin_layout Labeling
2858 \labelwidthstring -R
2859 \begin_inset Flex Code
2862 \begin_layout Plain Layout
2863 \SpecialChar nobreakdash
2864 \SpecialChar nobreakdash
2870 print the list of all labels associated with the test set.
2871 Can also be combined with -R, -L, -E, ...
2875 \begin_layout Standard
2876 Other useful options are:
2879 \begin_layout Labeling
2880 \labelwidthstring -R
2881 \begin_inset Flex Code
2884 \begin_layout Plain Layout
2890 Run the tests in parallel using the given number of jobs.
2894 \begin_layout Standard
2895 We are still working on getting the tests to run in parallel.
2896 However, when running the tests in parallel, sometimes tests fail that
2897 pass when run sequentially.
2898 A reasonable approach is to first run the tests in parallel and then run
2899 the failed tests sequentially.
2902 \begin_layout Standard
2903 For example, to run 8 jobs at a time:
2906 \begin_layout Standard
2907 \begin_inset Flex Code
2910 \begin_layout Plain Layout
2919 \begin_layout Standard
2920 \begin_inset Flex Code
2923 \begin_layout Plain Layout
2924 ctest \SpecialChar nobreakdash
2925 \SpecialChar nobreakdash
2934 \begin_layout Standard
2935 When specifying a subset of the tests (e.g.
2937 \begin_inset Flex Code
2940 \begin_layout Plain Layout
2941 \SpecialChar nobreakdash
2947 ), the same subset must be specified when using the
2948 \begin_inset Flex Code
2951 \begin_layout Plain Layout
2952 \SpecialChar nobreakdash
2953 \SpecialChar nobreakdash
2959 option because it is the test numbers that are used to index which tests
2960 failed on the previous run.
2963 \begin_layout Standard
2965 Note that some tests cannot be run in parallel.
2966 These tests are marked in the code with the
2967 \begin_inset Flex Code
2970 \begin_layout Plain Layout
2981 \begin_layout Labeling
2982 \labelwidthstring -R
2983 \begin_inset Flex Code
2986 \begin_layout Plain Layout
2987 \SpecialChar nobreakdash
2988 \SpecialChar nobreakdash
2994 Set a global timeout on all tests that do not already have a timeout set
2999 \begin_layout Standard
3000 There have been bugs in LyX and in \SpecialChar LaTeX
3001 which cause compilation to hang, and
3002 without a timeout a test might never stop (in one case there was even a
3004 If a test times out, the
3005 \begin_inset Flex Code
3008 \begin_layout Plain Layout
3014 command exits with error, but you can distinguish between a timed out test
3015 and a failed test in the output reported at the end of the
3016 \begin_inset Flex Code
3019 \begin_layout Plain Layout
3029 \begin_layout Standard
3031 \begin_inset Flex Code
3034 \begin_layout Plain Layout
3040 ) the full list of command line options.
3043 \begin_layout Paragraph
3047 \begin_layout Itemize
3048 run only the export tests:
3049 \begin_inset Flex Code
3052 \begin_layout Plain Layout
3061 \begin_layout Itemize
3063 \begin_inset Flex Code
3066 \begin_layout Plain Layout
3067 ctest -L "inverted|suspended"
3075 \begin_layout Itemize
3076 list all export tests which match any of the labelling patterns:
3077 \begin_inset Flex Code
3080 \begin_layout Plain Layout
3091 \begin_layout Itemize
3092 exclude rarely used output formats and post-processing tests
3093 \begin_inset Flex Code
3096 \begin_layout Plain Layout
3097 ctest -L export -E "_(texF|dvi3|pdf3?)"
3105 \begin_layout Paragraph
3106 \begin_inset CommandInset label
3108 name "subsec:Interpreting-export-tests"
3112 Interpreting the export test results
3115 \begin_layout Standard
3116 A test can fail for several reasons, not all of them bad.
3119 \begin_layout Enumerate
3120 A new or edited sample document may be incompatible with some output formats.
3123 \begin_layout Enumerate
3124 A dependency is not met (e.g.
3125 the \SpecialChar LaTeX
3127 One hint that this is the case is that the corresponding
3128 \begin_inset Flex Code
3131 \begin_layout Plain Layout
3137 test will likely also fail.
3140 \begin_layout Enumerate
3141 An inverted test fails to fail (i.e.
3142 export that previously failed now works).
3145 \begin_layout Enumerate
3146 An external dependency was updated (e.g.
3151 \begin_layout Enumerate
3152 A recent code change introduced a bug.
3155 \begin_layout Enumerate
3156 \begin_inset CommandInset label
3162 A change in a document exposed a previously unknown bug or an incompatibility
3163 with an export format (e.g.
3164 Lua\SpecialChar LaTeX
3168 \begin_layout Standard
3169 Because the .lyx files are exported in several formats, it is not surprising
3170 that many of the exports fail.
3171 This expectation of failure is addressed by
3172 \begin_inset Quotes eld
3176 \begin_inset Quotes erd
3179 the tests, that is, by marking the test as
3180 \begin_inset Quotes eld
3184 \begin_inset Quotes erd
3187 if the export exits with error and as
3188 \begin_inset Quotes eld
3192 \begin_inset Quotes erd
3195 if the export succeeds
3200 It follows that these expected failures will not show up as failed tests
3201 in the test results and thus will not pollute the
3202 \begin_inset Quotes eld
3206 \begin_inset Quotes erd
3210 If the export actually succeeds, then the test will fail.
3211 The purpose of this failure is to get your attention—something has changed,
3212 possibly for the better.
3215 \begin_layout Standard
3216 We try to document why a test is inverted or ignored.
3217 See the comment (prefixed with
3218 \begin_inset Flex Code
3221 \begin_layout Plain Layout
3227 ) above the block in which the test is listed as inverted or ignored in
3229 \begin_inset Flex Code
3232 \begin_layout Plain Layout
3233 development/autotests/invertedTests
3239 \begin_inset Flex Code
3242 \begin_layout Plain Layout
3243 development/autotests/unreliableTests
3249 \begin_inset Flex Code
3252 \begin_layout Plain Layout
3253 development/autotests/ignoredTests
3262 \begin_layout Standard
3263 A good question is why do we enable the tests for non-default formats? The
3264 answer is that if a non-default route is broken it is often because a bug
3265 was introduced in LyX and not because a document-specific change was made
3266 that is not supported by the route.
3267 In other words, there is a high signal/noise ratio in the export tests
3268 for some non-default formats.
3272 \begin_layout Standard
3273 When a test or several tests fail, consider checking the files in the
3274 \begin_inset Flex Code
3277 \begin_layout Plain Layout
3283 subdirectory of your build directory.
3284 In this subdirectory are three files: the file
3285 \begin_inset Flex Code
3288 \begin_layout Plain Layout
3294 simply lists the tests that failed on your last
3295 \begin_inset Flex Code
3298 \begin_layout Plain Layout
3305 \begin_inset Flex Code
3308 \begin_layout Plain Layout
3314 file contains the output from the tests (and often has details explaining
3315 why a test failed); and the
3316 \begin_inset Flex Code
3319 \begin_layout Plain Layout
3325 file lists the times that it took to run the tests.
3328 \begin_layout Paragraph
3329 What action should you take if a test fails?
3332 \begin_layout Standard
3333 \paragraph_spacing single
3334 It is always good to check manually why something fails and if it passes
3335 if the PDF output is good.
3338 \begin_layout Itemize
3339 Generally, if a change breaks compilation for the target format (for the
3340 manuals pdf2) without solving some important other issue,
3342 fix or revert the commit
3344 that led to failure.
3347 \begin_layout Itemize
3348 If it is not possible to (immediately) fix the failure but there are reasons
3349 not to revert the commit (e.g.
3350 it fixes another more important issue),
3354 the failing test case (see
3355 \begin_inset CommandInset ref
3357 reference "par:Inverted-tests"
3364 \begin_layout Itemize
3369 test case fails because the export now works,
3373 the test by removing the pattern from the
3374 \begin_inset Quotes eld
3378 \begin_inset Quotes erd
3382 \begin_inset CommandInset ref
3384 reference "par:Inverted-tests"
3391 \begin_layout Itemize
3392 If the export did not fail previously but led to wrong output (PDF, say),
3396 \begin_layout Plain Layout
3397 Non-failing test with wrong output should be labeled as
3398 \begin_inset Quotes eld
3401 unreliable:wrong_output
3402 \begin_inset Quotes erd
3406 \begin_inset CommandInset ref
3408 reference "par:Unreliable-tests"
3417 it is in fact an improvement when the test now fails.
3422 the failing test case (see
3423 \begin_inset CommandInset ref
3425 reference "par:Inverted-tests"
3432 \begin_layout Itemize
3433 In case of tests failing due to missing requirements (tests labeled
3434 \begin_inset Quotes eld
3437 unreliable:nonstandard
3438 \begin_inset Quotes erd
3441 or testing on a system with only a subset of TeXLive installed), ignore
3442 the failure, ask for someone else to run the test, or install the missing
3443 resources and try again.
3446 \begin_layout Itemize
3447 Check the log file Testing/Temporary/LastTest.log.
3448 In case of latex-errors rerun the failing test with environment variable
3449 'LAX_DEBUG_LATEX' set to '1'.
3450 This will include latex messages in LastTest.log, so it should be easier
3451 to interpret the fail-reason.
3454 \begin_layout Paragraph
3455 \begin_inset CommandInset label
3457 name "par:Inverted-tests"
3464 \begin_layout Standard
3465 Test cases whose name matches a pattern in the file
3466 \begin_inset Flex Code
3469 \begin_layout Plain Layout
3470 development/autotests/invertedTests
3480 They get also the test property
3481 \begin_inset Flex Code
3484 \begin_layout Plain Layout
3491 they are reported as failing if the export works without error
3492 \begin_inset Flex URL
3495 \begin_layout Plain Layout
3497 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3505 \begin_layout Standard
3506 Add failing cases to this file, if they cannot be solved
3507 \begin_inset Quotes eld
3511 \begin_inset Quotes erd
3514 but it is expected that the export will work in a foreseeable future, e.g.
3515 low priority issues like failures to export to a non-target format (for
3516 the manuals everything except pdf2).
3519 \begin_layout Standard
3520 The following sublabels are currently present in
3521 \begin_inset Flex Code
3524 \begin_layout Plain Layout
3533 \begin_layout Description
3534 todo test failures that require attention:
3538 \begin_layout Itemize
3539 minor issues to explore and properly sort later,
3542 \begin_layout Itemize
3546 \begin_layout Itemize
3547 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3551 \begin_layout Description
3552 lyxbugs LyX bugs with a Trac number.
3555 \begin_layout Description
3556 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3560 \begin_layout Standard
3561 "Wontfix" if demonstrating correct use and OK in the default output format.
3565 \begin_layout Description
3566 texissues Export fails due to LaTeX limitations like non-ASCII characters
3567 in verbatim or listings, incompatible packages, ...
3571 \begin_layout Standard
3572 "Wontfix" if documents demonstrate correct use in the default output format:
3575 \begin_layout Itemize
3576 If the source can be made more robust without becoming "hackish", fix the
3580 \begin_layout Itemize
3581 if LyX could be enhanced to care for a permanent TeX limitation, file a
3582 ticket at trac and add a pattern under lyxbugs,
3585 \begin_layout Itemize
3586 otherwise, add a pattern here.
3590 \begin_layout Description
3591 attic Documents in the attic (kept for reference and format conversion test).
3593 \begin_inset Quotes eld
3597 \begin_inset Quotes erd
3603 \begin_layout Subparagraph
3607 \begin_layout Standard
3608 Test cases whose name additionally matches a pattern in the file
3609 \begin_inset Flex Code
3612 \begin_layout Plain Layout
3613 development/autotests/suspendedTests
3631 This means they are not executed using
3632 \begin_inset Flex Code
3635 \begin_layout Plain Layout
3642 \begin_inset Flex Code
3645 \begin_layout Plain Layout
3652 However, they also get the test property
3653 \begin_inset Flex Code
3656 \begin_layout Plain Layout
3663 they are reported as failing if the export works without error.
3664 From time to time they still have to be checked using
3665 \begin_inset Flex Code
3668 \begin_layout Plain Layout
3677 \begin_layout Standard
3678 These tests are suspended, because the export fails for known reasons which
3679 cannot ATM be resolved.
3680 But it is expected the reason might disappear in the future.
3681 Be it new TL or better handling in \SpecialChar LyX
3685 \begin_layout Standard
3686 For ctest commands without the
3687 \begin_inset Flex Code
3690 \begin_layout Plain Layout
3696 parameter nothing changes.
3697 Suspended or not, tests will be executed depending only on the selecting
3698 regular expression given to the ctest command (see
3699 \begin_inset CommandInset ref
3701 reference "par:ctest-options"
3708 \begin_layout Paragraph
3709 \begin_inset CommandInset label
3711 name "par:Unreliable-tests"
3718 \begin_layout Standard
3719 Test cases whose name matches a pattern in the file
3720 \begin_inset Flex Code
3723 \begin_layout Plain Layout
3724 development/autotests/unreliableTests
3736 \begin_layout Standard
3737 These tests are not executed using
3738 \begin_inset Flex Code
3741 \begin_layout Plain Layout
3748 \begin_inset Flex Code
3751 \begin_layout Plain Layout
3761 \begin_layout Standard
3762 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3763 or pass but should rather fail (wrong output).
3765 \begin_inset Note Note
3768 \begin_layout Plain Layout
3769 *invalid* tests (wrong output) are not *unreliable*.
3770 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3779 \begin_layout Standard
3780 The following sublabels are currently present in
3781 \begin_inset Flex Code
3784 \begin_layout Plain Layout
3793 \begin_layout Description
3794 nonstandard Documents with additional requirements, e.g.
3795 a class or package file not in TeXLive.
3797 \begin_inset Note Note
3800 \begin_layout Plain Layout
3802 \begin_inset Quotes eld
3806 \begin_inset Quotes erd
3810 \begin_inset Quotes eld
3814 \begin_inset Quotes erd
3825 \begin_layout Description
3826 erratic Tests depending on local configuration or the phase of the moon.
3830 \begin_layout Description
3831 varying_versions Tests depending on e.g.
3832 OS or version of a non-TeX-Live dependency.
3833 Note that a full, up-to-date TeX Live installation is required so this
3834 sublabel is about versions of other dependencies.
3837 \begin_layout Description
3839 \begin_inset space ~
3842 output Export does not fail but the resulting document has (undetected)
3847 \begin_layout Standard
3848 \paragraph_spacing single
3849 \begin_inset Note Note
3852 \begin_layout Plain Layout
3853 \paragraph_spacing single
3854 These tests are in a strict sense not unreliable but
3858 (not measuring what they should measure).
3867 \begin_layout Paragraph
3868 \begin_inset CommandInset label
3870 name "par:Export-test-filtering"
3874 Export test filtering
3877 \begin_layout Standard
3878 The assignment of a label to a test is controlled by a set of files with
3879 regular expressions that are matched against the test names.
3882 \begin_layout Description
3883 ignoredTests (small file)
3884 \begin_inset Newline newline
3887 Tests selected here are withdrawn in the configuration step (cf.
3889 \begin_inset CommandInset ref
3891 reference "par:Configuring-ctests"
3899 \begin_layout Labeling
3900 \labelwidthstring 00.00.0000
3901 Input Test of any export combination
3904 \begin_layout Labeling
3905 \labelwidthstring 00.00.0000
3906 Output Stop if tests not selected here
3910 \begin_layout Description
3911 unreliableTests: Tests selected pass or fail dependent on the system where
3913 Selected tests gain the label 'unreliable'.
3917 \begin_layout Labeling
3918 \labelwidthstring 00.00.0000
3919 Input Each test which passed 'ignoredTests'
3922 \begin_layout Labeling
3923 \labelwidthstring 00.00.0000
3924 Output Gain label 'unreliable', proceed with checking for 'inverted'.
3928 \begin_layout Description
3930 \begin_inset space \space{}
3937 \begin_layout Labeling
3938 \labelwidthstring 00.00.0000
3939 Input Each test which passed 'ignoredTests'
3942 \begin_layout Labeling
3943 \labelwidthstring 00.00.0000
3944 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3945 tests are reported as failing if the export works without error.) If no
3946 subselection applies, gain labels 'export' and 'inverted'.
3949 \begin_layout Standard
3950 The following filter perfoms a subselection of 'invertedTests':
3953 \begin_layout Description
3954 suspendedTests Tests selected here gain the label 'suspended' but _not_
3955 'export' or 'inverted', although in ctest they remain inverted.
3956 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3960 \begin_layout Labeling
3961 \labelwidthstring 00.00.0000
3962 Input Each test selected by 'invertedTests'
3965 \begin_layout Labeling
3966 \labelwidthstring 00.00.0000
3967 Output Selected test gains label 'suspended'.
3973 \begin_layout Standard
3974 The following table may clarify label assignement
3977 \begin_layout Standard
3978 \begin_inset space \hspace{}
3983 \begin_inset Tabular
3984 <lyxtabular version="3" rows="6" columns="8">
3985 <features tabularvalignment="middle">
3986 <column alignment="left" valignment="top" width="2cm">
3987 <column alignment="left" valignment="top" width="2.5cm">
3988 <column alignment="left" valignment="top" width="2cm">
3989 <column alignment="center" valignment="top" width="2.5cm">
3990 <column alignment="center" valignment="top">
3991 <column alignment="center" valignment="top">
3992 <column alignment="center" valignment="top">
3993 <column alignment="center" valignment="top">
3995 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3998 \begin_layout Plain Layout
3999 Test matching pattern in file:
4004 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4007 \begin_layout Plain Layout
4013 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4016 \begin_layout Plain Layout
4022 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4025 \begin_layout Plain Layout
4031 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4034 \begin_layout Plain Layout
4040 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4043 \begin_layout Plain Layout
4049 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4052 \begin_layout Plain Layout
4058 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4061 \begin_layout Plain Layout
4069 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4072 \begin_layout Plain Layout
4073 ignored\SpecialChar softhyphen
4079 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4082 \begin_layout Plain Layout
4083 unreliable\SpecialChar softhyphen
4089 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4092 \begin_layout Plain Layout
4093 inverted\SpecialChar softhyphen
4099 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4102 \begin_layout Plain Layout
4103 suspended\SpecialChar softhyphen
4109 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4112 \begin_layout Plain Layout
4118 <cell alignment="center" valignment="top" topline="true" usebox="none">
4121 \begin_layout Plain Layout
4127 <cell alignment="center" valignment="top" topline="true" usebox="none">
4130 \begin_layout Plain Layout
4136 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4139 \begin_layout Plain Layout
4147 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4150 \begin_layout Plain Layout
4156 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4159 \begin_layout Plain Layout
4165 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4168 \begin_layout Plain Layout
4174 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4177 \begin_layout Plain Layout
4183 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4186 \begin_layout Plain Layout
4192 <cell alignment="center" valignment="top" topline="true" usebox="none">
4195 \begin_layout Plain Layout
4201 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4204 \begin_layout Plain Layout
4210 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4213 \begin_layout Plain Layout
4221 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4224 \begin_layout Plain Layout
4230 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4233 \begin_layout Plain Layout
4235 \begin_inset Newline newline
4239 \begin_inset Newline newline
4247 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4250 \begin_layout Plain Layout
4256 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4259 \begin_layout Plain Layout
4265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4268 \begin_layout Plain Layout
4274 <cell alignment="center" valignment="top" topline="true" usebox="none">
4277 \begin_layout Plain Layout
4283 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4286 \begin_layout Plain Layout
4292 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4295 \begin_layout Plain Layout
4303 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4306 \begin_layout Plain Layout
4312 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4315 \begin_layout Plain Layout
4321 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4324 \begin_layout Plain Layout
4330 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4333 \begin_layout Plain Layout
4339 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4342 \begin_layout Plain Layout
4348 <cell alignment="center" valignment="top" topline="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
4366 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4369 \begin_layout Plain Layout
4377 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="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" bottomline="true" leftline="true" usebox="none">
4407 \begin_layout Plain Layout
4413 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4416 \begin_layout Plain Layout
4422 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4425 \begin_layout Plain Layout
4431 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4434 \begin_layout Plain Layout
4440 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4443 \begin_layout Plain Layout
4457 \begin_layout Standard
4458 \begin_inset Note Note
4461 \begin_layout Plain Layout
4463 \begin_inset Quotes eld
4467 \begin_inset Quotes erd
4470 filter, this would be far less complicated:
4473 \begin_layout Plain Layout
4474 \begin_inset Tabular
4475 <lyxtabular version="3" rows="6" columns="7">
4476 <features tabularvalignment="middle">
4477 <column alignment="left" valignment="top" width="0pt">
4478 <column alignment="left" valignment="top" width="0pt">
4479 <column alignment="left" valignment="top" width="0pt">
4480 <column alignment="center" valignment="top">
4481 <column alignment="center" valignment="top">
4482 <column alignment="center" valignment="top">
4483 <column alignment="center" valignment="top">
4485 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4488 \begin_layout Plain Layout
4489 Test matching pattern in file:
4494 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4497 \begin_layout Plain Layout
4503 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4506 \begin_layout Plain Layout
4512 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4515 \begin_layout Plain Layout
4521 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4524 \begin_layout Plain Layout
4530 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4533 \begin_layout Plain Layout
4539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4542 \begin_layout Plain Layout
4550 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4553 \begin_layout Plain Layout
4559 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4562 \begin_layout Plain Layout
4568 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4571 \begin_layout Plain Layout
4577 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4580 \begin_layout Plain Layout
4586 <cell alignment="center" valignment="top" topline="true" usebox="none">
4589 \begin_layout Plain Layout
4595 <cell alignment="center" valignment="top" topline="true" usebox="none">
4598 \begin_layout Plain Layout
4604 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4607 \begin_layout Plain Layout
4615 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4618 \begin_layout Plain Layout
4624 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4627 \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="center" valignment="top" topline="true" leftline="true" usebox="none">
4645 \begin_layout Plain Layout
4651 <cell alignment="center" valignment="top" topline="true" usebox="none">
4654 \begin_layout Plain Layout
4660 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4663 \begin_layout Plain Layout
4669 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4672 \begin_layout Plain Layout
4680 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4683 \begin_layout Plain Layout
4689 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4692 \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="center" valignment="top" topline="true" leftline="true" usebox="none">
4710 \begin_layout Plain Layout
4716 <cell alignment="center" valignment="top" topline="true" usebox="none">
4719 \begin_layout Plain Layout
4725 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4728 \begin_layout Plain Layout
4734 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4737 \begin_layout Plain Layout
4745 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4748 \begin_layout Plain Layout
4754 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4757 \begin_layout Plain Layout
4763 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4766 \begin_layout Plain Layout
4772 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4775 \begin_layout Plain Layout
4781 <cell alignment="center" valignment="top" topline="true" usebox="none">
4784 \begin_layout Plain Layout
4790 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4793 \begin_layout Plain Layout
4799 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4802 \begin_layout Plain Layout
4810 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4813 \begin_layout Plain Layout
4819 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4822 \begin_layout Plain Layout
4828 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4831 \begin_layout Plain Layout
4837 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4840 \begin_layout Plain Layout
4846 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4849 \begin_layout Plain Layout
4855 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4858 \begin_layout Plain Layout
4864 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4867 \begin_layout Plain Layout
4886 \begin_layout Subsubsection
4890 \begin_layout Standard
4891 These tests check whether a .lyx file loads without any terminal messages.
4892 They correspond to the manual operations of simply opening a .lyx file on
4893 the terminal, exiting LyX once the file is loaded, and then checking whether
4894 there is any output from the terminal.
4895 These tests are useful for catching malformed .lyx files and parsing bugs.
4896 They can also be used to find a .lyx file in which an instance of something
4898 To do this, compile LyX with a local patch that outputs something to the
4899 terminal when an instance is found, and then run the check_load tests to
4900 see if any fail, which would mean that the situation occurs in the LyX
4901 documentation files corresponding to the failed tests.
4902 These tests are expectedly fragile: any LyX diagnostic message, which is
4903 not necessarily an error, would cause the tests to fail.
4904 Similarly, any message output by a library (e.g.
4905 Qt) would also cause failure.
4906 There are some messages that the check_load tests are instructed to ignore,
4907 which are stored in the file
4908 \begin_inset Flex Code
4911 \begin_layout Plain Layout
4912 development/autotests/filterCheckWarnings
4920 \begin_layout Standard
4921 Under cmake, the tests are labeled as 'load'.
4924 \begin_layout Subsubsection
4928 \begin_layout Standard
4929 Automated tests based on the "MonKey Testing" keytest program are enabled
4930 if the necessary dependencies are found and if the CMake flag
4931 \begin_inset Flex Code
4934 \begin_layout Plain Layout
4935 -DLYX_ENABLE_KEYTESTS=ON
4941 They are documented in the README document in
4942 \begin_inset Flex Code
4945 \begin_layout Plain Layout
4946 development/autotests
4951 subfolder of the \SpecialChar LyX
4952 source code distribution.
4955 \begin_layout Subsubsection
4959 \begin_layout Standard
4960 These tests combine lyx2lyx tests with check_load tests.
4961 They fail if either fails.
4964 \begin_layout Subsubsection
4968 \begin_layout Standard
4969 The URL tests are enabled with the
4970 \begin_inset Flex Code
4973 \begin_layout Plain Layout
4974 -DLYX_ENABLE_URLTESTS=ON
4979 CMake flag and are useful for finding broken links in our documentation
4981 If a URL test fails, to see which link in particular was reported as broken,
4983 \begin_inset Flex Code
4986 \begin_layout Plain Layout
4993 These tests are extremely fragile (e.g.
4994 a test can depend on your Internet connection) and a failed URL test should
4995 not be taken too seriously.
4996 URL tests are labeled as
5001 \begin_layout Paragraph
5005 \begin_layout Standard
5006 cmake is required to run the \SpecialChar LyX
5007 tests, running them is not implemented for
5011 \begin_layout Standard
5012 The appropriate commands are:
5015 \begin_layout Itemize
5021 \begin_inset Newline newline
5024 runs all tests with label
5029 \begin_layout Itemize
5032 ctest -R 'check_.*urls'
5035 \begin_inset Newline newline
5038 runs the tests 'check_accessible_urls'
5041 \begin_layout Standard
5042 Associated test results can be examined in ctest-log directory in files
5043 of the form 'LastFailed.*URLS.log'
5046 \begin_layout Section
5047 Development policies
5050 \begin_layout Standard
5051 This chapter lists some guidelines that should be followed.
5052 This list is not complete, and many guidelines are in separate chapters,
5054 \begin_inset Quotes eld
5057 When is an update of the .lyx file format number needed?
5058 \begin_inset Quotes erd
5062 \begin_inset CommandInset ref
5064 reference "sec:When-is-an"
5071 \begin_layout Subsection
5072 When to set a fixed milestone?
5075 \begin_layout Standard
5076 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5080 \begin_layout Enumerate
5081 Somebody is actively working on a fix.
5084 \begin_layout Enumerate
5085 The bug is so severe that it would block the release if it is not fixed.
5088 \begin_layout Standard
5089 If a bug is important, but nobody is working on it, and it is no showstopper,
5090 use a milestone like 2.1.x or 2.2.x.
5091 For all other bugs, do not set a milestone at all.
5094 \begin_layout Subsection
5095 Can we add rc entries in stable branch?
5098 \begin_layout Standard
5100 We are supposed to increase the prefs2prefs version number with such things.
5103 \begin_layout Section
5104 \begin_inset CommandInset label
5106 name "sec:Documentation-policies"
5110 Documentation policies
5113 \begin_layout Subsection
5117 \begin_layout Standard
5119 \begin_inset space ~
5122 rules in editing the docs:
5125 \begin_layout Enumerate
5126 \begin_inset CommandInset label
5128 name "enu:If-you-are"
5132 If you are not the maintainer of a doc file or a chapter/section, you MUST
5133 use change tracking so that the maintainer could review your changes
5136 \begin_layout Enumerate
5137 Respect the formatting of the document.
5138 The different files use different formatting styles.
5139 That is OK and has historic reasons nobody fully knows ;-).
5140 But it is important to be consistent within one file.
5143 \begin_layout Enumerate
5144 All changes you make to a file in one language MUST also go the file in
5145 the other actively maintained languages.
5146 Normally the maintainer does this for you, if you are the maintainer, you
5147 must do this by copying or changing the changed or added text to the other
5148 files so that the translators sees the blue underlined text and know what
5149 they have to translate and what was changed.
5152 \begin_layout Enumerate
5153 You MUST assure that the document is compilable as
5154 \begin_inset Quotes eld
5158 \begin_inset Quotes erd
5161 or the document's default output format after your changes.
5164 \begin_layout Enumerate
5165 All fixes (typos, compilation fixes, updates info etc.) go at first into
5166 the current GIT branch because the user should benefit from all fixes with
5167 every minor release.
5168 Feel free to commit directly to branch as long as you follow rule
5169 \begin_inset space ~
5173 \begin_inset CommandInset ref
5175 reference "enu:If-you-are"
5180 You can immediately commit to master as well.
5183 \begin_layout Enumerate
5184 \begin_inset CommandInset label
5186 name "enu:The-fileformat-of"
5190 The fileformat of a file must not be changed unless you document a new feature
5191 in LyX that requires a new fileformat.
5192 The reason for this rule is to keep it easy for the doc maintainers to
5193 port/backport changes to from master/branch.
5196 \begin_layout Standard
5197 The main documentation consists of these files:
5200 \begin_layout Description
5201 splash.lyx it is the first file you see after an installation.
5202 We assume that a new user sees this.
5203 It is therefore designed to be as simple as possible.
5204 Therefore please don't add any new formatting, only fix typos etc.
5205 Splash.lyx is up to date for \SpecialChar LyX
5206 2.1.x, currently maintained by Uwe Stöhr.
5209 \begin_layout Description
5210 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5212 It therefore uses a limited set of formatting.
5213 For example a standard document class.
5214 Since new users will first learn about the formatting possibilities of
5216 please keep this file that simple.
5217 Intro.lyx is up to date for \SpecialChar LyX
5218 2.1.x, currently maintained by Uwe Stöhr.
5221 \begin_layout Description
5222 Tutorial.lyx our tutorial.
5223 It must be always up to date.
5224 Normally there is nothing to add since we don't want to overwhelm new users
5225 with too much details.
5226 The will learn these details while using \SpecialChar LyX
5227 and we have special manuals.
5228 Tutorial.lyx is up to date for \SpecialChar LyX
5229 2.1.x, currently maintained by Uwe Stöhr.
5232 \begin_layout Description
5233 UserGuide.lyx our main user guide.
5234 It covers a mixture of basic and detailed information.
5235 Some information is also in the Math and EmbeddedObjects manual so that
5236 the UserGuide refers to these files.
5237 UserGuide.lyx is up to date for \SpecialChar LyX
5238 2.1.x, currently maintained by Uwe Stöhr.
5241 \begin_layout Description
5242 EmbeddedObjects.lyx a special manual to explain things like tables floats
5245 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5246 2.1.x, currently maintained by Uwe
5250 \begin_layout Description
5251 Math.lyx a special manual to explain everything regarding math in all detail.
5252 Math.lyx is up to date for \SpecialChar LyX
5253 2.1.x, currently maintained by Uwe Stöhr.
5256 \begin_layout Description
5257 Additional.lyx this manual covers information that would be too much detail
5258 for the UserGuide or would make the UserGuide uncompilable or only compilable
5259 when installing a lot of special \SpecialChar LaTeX
5261 What should be in the UserGuide or better in Additional is a matter of
5263 it is up to you to decide that.
5264 Additional.lyx is not completely up to date for \SpecialChar LyX
5267 \begin_inset space ~
5270 8 is up to date and currently maintained by Uwe Stöhr.
5271 It certainly needs a rewrite and update.
5272 For example many info in chapter
5273 \begin_inset space ~
5276 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5280 \begin_layout Description
5281 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5283 output formats, operating systems, languages etc.
5284 It is currently completely out of date and needs a major rewrite and update.
5285 If you do this please assure that your information are given for all OSes
5286 and \SpecialChar LaTeX
5287 distributions (meaning be as objective as possible).