1 #LyX 2.3 created this file. For more info see http://www.lyx.org/
5 \save_transient_properties true
6 \origin /systemlyxdir/doc/
8 \options BCOR8mm,captions=tableheading
9 \use_default_options false
13 \maintain_unincluded_children false
15 \language_package default
18 \font_roman "lmodern" "default"
19 \font_sans "lmss" "default"
20 \font_typewriter "lmtt" "default"
21 \font_math "auto" "auto"
22 \font_default_family default
23 \use_non_tex_fonts false
26 \font_sf_scale 100 100
27 \font_tt_scale 100 100
30 \default_output_format pdf2
32 \bibtex_command default
33 \index_command default
37 \pdf_title "LyX's Development manual"
38 \pdf_author "LyX Team"
39 \pdf_subject "LyX's development documentation"
40 \pdf_keywords "LyX, Documentation, Development"
42 \pdf_bookmarksnumbered true
43 \pdf_bookmarksopen true
44 \pdf_bookmarksopenlevel 1
49 \pdf_pdfusetitle false
50 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
53 \use_package amsmath 1
54 \use_package amssymb 1
57 \use_package mathdots 1
58 \use_package mathtools 0
60 \use_package stackrel 0
61 \use_package stmaryrd 0
62 \use_package undertilde 0
64 \cite_engine_type default
68 \paperorientation portrait
72 \notefontcolor #0000ff
79 \paragraph_separation indent
80 \paragraph_indentation default
81 \quotes_language english
84 \paperpagestyle headings
85 \tracking_changes false
95 Developing \SpecialChar LyX
99 \begin_layout Subtitle
104 by the \SpecialChar LyX
109 \begin_layout Plain Layout
111 If you have comments or error corrections, please send them to the \SpecialChar LyX
114 \begin_inset Flex Code
117 \begin_layout Plain Layout
119 <lyx-docs@lists.lyx.org>
132 \begin_layout Standard
133 \begin_inset CommandInset toc
134 LatexCommand tableofcontents
141 \begin_layout Section
145 \begin_layout Standard
146 This manual documents some aspects of \SpecialChar LyX
148 It is currently rather incomplete, but will hopefully be extended in the
150 Meanwhile, additional information can be found in the
151 \begin_inset Flex Code
154 \begin_layout Plain Layout
160 subfolder of the \SpecialChar LyX
161 source code distribution.
162 This document is not translated, since the development language of \SpecialChar LyX
165 If you just want to use \SpecialChar LyX
166 , then you don't need to read this manual.
167 However, if you want to learn more about how \SpecialChar LyX
168 is developed, or even want
169 to participate in \SpecialChar LyX
170 development, you may find some interesting information
174 \begin_layout Section
178 \begin_layout Standard
180 uses several custom file formats for configuration files and documents.
181 This chapter contains some background concerning these file formats.
182 Several file formats are also described in detail in the regular user documenta
186 \begin_layout Subsection
190 \begin_layout Subsection
191 When is an update of the .lyx file format number needed?
192 \begin_inset CommandInset label
194 name "sec:When-is-an"
201 \begin_layout Standard
202 When you are working on a new feature you may ask yourself whether it needs
203 an update of the .lyx file format number.
204 Whether an update is needed or not is not always obvious.
209 Whenever there is the danger that a previous version of LyX cannot open
210 a file using the new feature, a file format update is needed.
213 \begin_layout Standard
214 The file format change allows lyx2lyx rules to implement backwards compatibility.
215 Below you can find a list of reasons for file format updates with explanations:
218 \begin_layout Description
227 setting Whenever you introduce a new setting that is stored in the document
228 header, a file format update is needed.
231 \begin_layout Description
240 setting If a certain setting becomes obsolete and gets removed, a file format
244 \begin_layout Description
270 \begin_inset space \thinspace{}
277 \begin_layout Description
278 \paragraph_spacing single
291 package The reason for this is that there is no true ERT inset for math
292 formulas: Each command is parsed, and if a user happens to define a local
293 command with the same name as a command that triggers an automatic load
294 of a package, they need to be able to switch off the automatic loading
296 This switch is stored by the
297 \begin_inset Flex Code
300 \begin_layout Plain Layout
309 \begin_layout Description
314 language that is stored in
315 \begin_inset Flex Code
318 \begin_layout Plain Layout
328 \begin_inset Note Note
331 \begin_layout Plain Layout
332 This requirement is under discussion.
341 \begin_layout Description
346 inset Of course a new inset requires a file format update.
349 \begin_layout Description
354 style If a new style or inset layout is added to any layout file or module
355 shipped with \SpecialChar LyX
356 , then a new file format is needed in the master (development)
358 It is possible to backport new styles to the stable version without a file
361 \begin_inset CommandInset ref
363 reference "subsec:Backporting-new-styles"
367 for more information.
370 \begin_layout Description
375 style If a style or inset layout is removed in any layout file or module
376 shipped with \SpecialChar LyX
377 , a new file format is required.
380 \begin_layout Standard
385 layouts and modules do
389 require a file format update (changed 03/16, see
390 \begin_inset CommandInset ref
392 reference "subsec:New-layouts"
400 \begin_layout Standard
401 If you are still unsure, please ask on the development list.
404 \begin_layout Subsection
405 \begin_inset CommandInset label
407 name "subsec:update_lyx_files"
411 How to update the file format number of .lyx files
414 \begin_layout Standard
415 Once you come to the conclusion that a file format update is needed, you
416 should use the following procedure to perform the update:
419 \begin_layout Enumerate
420 Implement and test the new feature, including the reading and writing of
422 Note that any file produced at this stage does not use a valid format,
423 so do not use this version of \SpecialChar LyX
424 for working on any important documents.
427 \begin_layout Enumerate
428 \begin_inset CommandInset label
430 name "enu:Describe_format"
434 Describe the new format in
435 \begin_inset Flex Code
438 \begin_layout Plain Layout
447 \begin_layout Enumerate
448 Update the \SpecialChar LyX
449 file format number in
450 \begin_inset Flex Code
453 \begin_layout Plain Layout
462 \begin_layout Enumerate
463 \begin_inset CommandInset label
465 name "enu:Add-an-entry"
469 Add an entry to both format lists (for conversion and reversion) in
470 \begin_inset Newline newline
474 \begin_inset Flex Code
477 \begin_layout Plain Layout
478 lib/lyx2lyx/lyx_2_3.py
484 Add a conversion routine if needed (e.
485 \begin_inset space \thinspace{}
488 g., a new header setting always needs a conversion that adds the new setting,
489 but a new document language does not need one).
490 Add a reversion routine if needed.
492 \begin_inset Newline newline
495 While the conversion routine is required to produce a document that is equivalen
496 t to the old version, the requirements of the reversion are not that strict.
497 If possible, try to produce a proper reversion, using ERT if needed, but
498 for some features this might be too complicated.
499 In this case, the minimum requirement of the reversion routine is that
500 it produces a valid document which can be read by an older \SpecialChar LyX
502 If absolutely needed, even data loss is allowed for the reversion.
503 (In that case, you might want to add a LyX comment that indicates what
504 you have had to do, so the user is at least warned).
507 \begin_layout Enumerate
508 Since tex2lyx has several implicit file format dependencies caused by sharing
509 code with \SpecialChar LyX
510 , updating the file format of .lyx files produced by tex2lyx at
511 the same time as updating the main .lyx file format is strongly recommended.
512 Therefore, a compiler warning will be issued if the \SpecialChar LyX
513 and tex2lyx .lyx file
514 format numbers differ.
515 In many cases the tex2lyx update requires only the first and last item
520 \begin_layout Enumerate
521 Update the tex2lyx file format number in
522 \begin_inset Flex Code
525 \begin_layout Plain Layout
534 \begin_layout Enumerate
535 If the lyx2lyx conversion from the old to the new format is empty, or if
536 tex2lyx does not yet output the changed feature, you do not need any further
538 Otherwise, search for the changed feature in tex2lyx, and adjust the output
539 according to the lyx2lyx changes.
542 \begin_layout Enumerate
543 Update the tex2lyx test references as described in
544 \begin_inset CommandInset ref
545 LatexCommand formatted
546 reference "sec:Updating-test-references"
554 \begin_layout Enumerate
555 If you did not implement full tex2lyx support for the new feature, add a
557 \begin_inset Flex Code
560 \begin_layout Plain Layout
566 describing the missing bits.
567 Note that it is perfectly fine if you do not add full tex2lyx support for
568 a new feature: The updating recommendation above is only issued for the
569 syntax of the produced .lyx file.
570 It is no problem if some features supported by \SpecialChar LyX
571 are still output as ERT
573 The problems in the past that resulted in the update recommendation were
574 related to mixed version syntax, not ERT.
577 \begin_layout Enumerate
578 It would be nice if you could create a .lyx test file which contains instances
579 of all changed or added features.
580 This could then be used to test lyx2lyx and tex2lyx.
581 Unfortunately, it has not yet been decided how to collect such examples,
582 so please ask on the development list if you want to create one.
585 \begin_layout Enumerate
586 \begin_inset CommandInset label
588 name "enu:updatefiles"
592 Test your lyx2lyx code by updating LyX's .lyx documentation files to the
594 The developer who makes the change knows best what changes to expect when
595 inspecting the resulting diff.
596 Because of this, you might be able to catch a bug in the lyx2lyx code that
597 updates the format just by taking a quick scan through the large diff that
599 \begin_inset Note Note
602 \begin_layout Plain Layout
603 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
604 see which layout update made an unexpected change by looking at the git
605 log of a .lyx file that suffers the problem.
610 To do this, first make sure that there are no changes to the git repository
611 that you will not want to commit (this is needed because it will be convenient
612 to commit with the command
613 \begin_inset Flex Code
616 \begin_layout Plain Layout
623 Then run the following command in the root folder of the source:
624 \begin_inset Flex Code
627 \begin_layout Plain Layout
628 python development/tools/updatedocs.py
634 Look at the resulting changes using the command
635 \begin_inset Flex Code
638 \begin_layout Plain Layout
645 If anything looks surprising, please investigate.
646 Keep in mind that the case of
647 \begin_inset Flex Code
650 \begin_layout Plain Layout
656 is special, because it is first generated with
657 \begin_inset Flex Code
660 \begin_layout Plain Layout
666 before being converted to the latest format.
667 \begin_inset Newline newline
671 \begin_inset Note Greyedout
674 \begin_layout Plain Layout
679 Only commit file format changes in the doc files if these files are using
680 the new feature of the new file format.
686 \begin_inset CommandInset ref
688 reference "enu:The-fileformat-of"
692 of the documentation policies described in sec.
697 \begin_inset CommandInset ref
699 reference "sec:Documentation-policies"
711 \begin_layout Enumerate
712 Finally, commit using
713 \begin_inset Flex Code
716 \begin_layout Plain Layout
725 \begin_layout Subsection
726 Updating the file format number of layout files
729 \begin_layout Standard
730 The procedure for updating the layout files is similar to that in step
731 \begin_inset CommandInset ref
733 reference "enu:updatefiles"
738 \begin_inset CommandInset ref
740 reference "subsec:update_lyx_files"
746 \begin_inset Flex Code
749 \begin_layout Plain Layout
750 python development/tools/updatelayouts.py
756 \begin_inset Flex Code
759 \begin_layout Plain Layout
768 \begin_layout Standard
769 Note that we do not automatically any local layout used in the
770 \begin_inset Flex Code
773 \begin_layout Plain Layout
779 files shipped with \SpecialChar LyX
780 because users would then not be able to export to older
782 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
783 to open the file in \SpecialChar LyX
784 2.1.x, there would be an error because the file would
785 contain a local layout whose format is too new.
786 The root reason for this is that we do not support converting layouts to
787 older layout formats, as we do for the
788 \begin_inset Flex Code
791 \begin_layout Plain Layout
800 \begin_layout Subsection
801 Updating the file format number of bind/ui files
804 \begin_layout Standard
805 A change to the functionality of existing LFUNs can require a conversion
807 \begin_inset Flex Code
810 \begin_layout Plain Layout
817 \begin_inset Flex Code
820 \begin_layout Plain Layout
826 files, and therefore an increment of the LFUN format, as well as a conversion
828 \begin_inset Flex Code
831 \begin_layout Plain Layout
838 The latter cannot be done automatically and also requires an update of
842 \begin_inset space \space{}
845 of someone who might have made a set of \SpecialChar LyX
846 teaching manuals for use in their
851 \begin_layout Plain Layout
852 \begin_inset Flex URL
855 \begin_layout Plain Layout
857 http://www.lyx.org/trac/ticket/9794
870 \begin_layout Standard
871 To update the LFUN format:
874 \begin_layout Enumerate
875 Increment the LFUN file format number in
876 \begin_inset Flex Code
879 \begin_layout Plain Layout
888 \begin_layout Enumerate
889 Implement the LFUN conversion in
890 \begin_inset Flex Code
893 \begin_layout Plain Layout
894 lib/scripts/prefs2prefs_lfuns.py
902 \begin_layout Enumerate
904 \begin_inset CommandInset ref
906 reference "enu:updatefiles"
911 \begin_inset CommandInset ref
913 reference "subsec:update_lyx_files"
918 \begin_inset Flex Code
921 \begin_layout Plain Layout
927 command, use this command:
928 \begin_inset Flex Code
931 \begin_layout Plain Layout
932 bash development/tools/updatelfuns.sh
939 \begin_inset Note Note
942 \begin_layout Plain Layout
943 This file should really be converted to python.
951 \begin_layout Enumerate
952 Update Info insets in
953 \begin_inset Flex Code
956 \begin_layout Plain Layout
963 To do so, increment the \SpecialChar LyX
964 format and proceed as in
965 \begin_inset CommandInset ref
967 reference "subsec:update_lyx_files"
972 \begin_inset CommandInset ref
974 reference "enu:Describe_format"
979 \begin_inset CommandInset ref
981 reference "enu:updatefiles"
986 In the lyx2lyx implementation (step
987 \begin_inset CommandInset ref
989 reference "enu:Add-an-entry"
993 ), implement a conversion similar to the one in
994 \begin_inset Flex Code
997 \begin_layout Plain Layout
1003 above, as well as a corresponding reversion; for this one can use
1004 \begin_inset Flex Code
1007 \begin_layout Plain Layout
1014 \begin_inset Flex Code
1017 \begin_layout Plain Layout
1018 lib/lyx2lyx/lyx2lyx_tools.py
1027 \begin_layout Subsection
1028 Backporting new styles to the stable version
1029 \begin_inset CommandInset label
1031 name "subsec:Backporting-new-styles"
1038 \begin_layout Standard
1039 Starting with the stable \SpecialChar LyX
1040 2.1 branch, there is a mechanism in place to backport
1041 new styles to the stable version without the need to update the file format.
1042 The basic idea is that the new style definition is automatically copied
1043 to the document preamble so that it can even be used by older minor versions
1044 that did not yet include the style.
1045 To backport a new style to the stable version, the following steps are
1049 \begin_layout Enumerate
1051 \begin_inset Flex Code
1054 \begin_layout Plain Layout
1060 to the style definition in the development version.
1063 \begin_layout Enumerate
1064 Copy the style definition to the stable version, but use
1065 \begin_inset Flex Code
1068 \begin_layout Plain Layout
1075 If needed adjust the format to the one used by the stable version (see
1076 the customization manual for details of the layout file format).
1079 \begin_layout Enumerate
1080 For each update of the style in a later stable version, increase the argument
1082 \begin_inset Flex Code
1085 \begin_layout Plain Layout
1092 (In the stable version, the development version should not be touched.)
1095 \begin_layout Standard
1096 For details about the
1097 \begin_inset Flex Code
1100 \begin_layout Plain Layout
1106 flag see the customization manual.
1108 \begin_inset Flex Code
1111 \begin_layout Plain Layout
1117 support is needed for backported styles: Since the style of the development
1118 version has an infinite version number, it will always be used.
1119 Furthermore, since its version number is less than one, the style will
1120 not be written anymore to the document header for files saved by the new
1124 \begin_layout Section
1125 New layouts and modules
1128 \begin_layout Subsection
1129 \begin_inset CommandInset label
1131 name "subsec:New-layouts"
1138 \begin_layout Standard
1139 Adding a new layout file to the \SpecialChar LyX
1141 \begin_inset Quotes eld
1144 officially supported
1145 \begin_inset Quotes erd
1149 You should therefore think carefully about whether you really want to do
1150 this and discuss it on lyx-devel, since you will need to be prepared to
1151 update and fix the layout if necessary.
1152 If the layout is experimental or for a rarely used document class, then
1153 it may be better to add it to the relevant portion of the \SpecialChar LyX
1157 \begin_inset CommandInset href
1159 target "https://wiki.lyx.org/Layouts/Layouts"
1166 \begin_layout Standard
1167 In older versions of this document, it was stated that new layout files
1168 require a file format change.
1169 After some discussion, it was decided that this is not needed.
1173 \begin_layout Plain Layout
1175 \begin_inset CommandInset href
1177 name "the thread “Proposal for a guide on updating layouts”"
1178 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1191 For reference, here are the arguments on each side
1195 \begin_layout Description
1197 \begin_inset Quotes eld
1200 New layout files are a file format change
1201 \begin_inset Quotes erd
1207 \begin_layout Itemize
1208 All documents produced by 2.2.
1209 \begin_inset Formula $x$
1212 can always be edited and exported even if
1213 \begin_inset Formula $x$
1217 This is important for people using different machines, or exchanging work
1221 \begin_layout Description
1223 \begin_inset Quotes eld
1226 New layout files are not a file format change
1227 \begin_inset Quotes erd
1233 \begin_layout Itemize
1234 No new LaTeX classes can be supported in a stable version, and stable versions
1235 have a typical lifetime of 2–3 years.
1238 \begin_layout Itemize
1239 We have the same situation already with custom layout files: If a document
1240 using a custom layout file is moved between machines or people, then the
1241 layout file needs to be exchanged as well.
1242 If that is not done, then we have a fallback implemented so that such documents
1243 can still be edited, but not exported, and the user gets a warning.
1247 \begin_layout Itemize
1248 The lyx2lyx script cannot do anything useful in such a case.
1252 \begin_layout Standard
1253 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1255 then, you should do the following:
1258 \begin_layout Enumerate
1259 Put your new layout file in
1260 \begin_inset Flex Code
1263 \begin_layout Plain Layout
1270 \begin_inset Flex Code
1273 \begin_layout Plain Layout
1274 git add lib/layouts/newlayout.layout
1279 ) so that it will be committed.
1282 \begin_layout Enumerate
1284 \begin_inset Flex Code
1287 \begin_layout Plain Layout
1293 , so that the new layout actually gets installed.
1296 \begin_layout Enumerate
1298 \begin_inset Flex Code
1301 \begin_layout Plain Layout
1302 lib/doc/LaTeXConfig.lyx
1307 containing in particular a line like
1315 \begin_layout Standard
1316 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1317 \begin_inset Flex Code
1320 \begin_layout Plain Layout
1321 info-insert textclass <name>
1327 This inset will automatically display a boxed
1328 \begin_inset Quotes eld
1332 \begin_inset Quotes erd
1336 \begin_inset Quotes eld
1340 \begin_inset Quotes erd
1343 depending on the availability of the package.
1347 \begin_layout Enumerate
1348 A template or example is strongly encouraged (but not necessarily required).
1349 It is also possible to provide both.
1351 \begin_inset Flex Code
1354 \begin_layout Plain Layout
1361 \begin_inset Flex Code
1364 \begin_layout Plain Layout
1373 \begin_layout Enumerate
1374 Reconfigure \SpecialChar LyX
1378 \begin_layout Enumerate
1379 Ensure the autotests for the new layout pass (see
1380 \begin_inset CommandInset ref
1382 reference "par:when-to-run-an-export-test"
1389 \begin_layout Subsection
1393 \begin_layout Standard
1394 Adding a new module is very similar to adding a new layout.
1395 Therefore, the previous section applies to new modules as well, with two
1399 \begin_layout Enumerate
1400 You only need to add an entry to
1401 \begin_inset Flex Code
1404 \begin_layout Plain Layout
1405 lib/doc/LaTeXConfig.lyx
1410 if the module requires a LaTeX package.
1411 In that case, the command for entering the InsetInfo is:
1412 \begin_inset Flex Code
1415 \begin_layout Plain Layout
1416 \paragraph_spacing single
1417 info-insert package <name>
1425 \begin_layout Enumerate
1426 Modules do not need a template, only an example, which is strongly encouraged
1427 but not necessarily required.
1430 \begin_layout Subsection
1431 Layouts for document classes with incompatible versions
1434 \begin_layout Standard
1435 \begin_inset Note Greyedout
1438 \begin_layout Description
1439 Note: This section is currently only a proposal under discussion.
1440 Please correct/amend as suited.
1441 Remove this note once a consensus is found.
1444 \begin_layout Plain Layout
1446 \begin_inset Quotes eld
1449 Proposal for a guide on updating layouts
1450 \begin_inset Quotes erd
1453 for details and background
1456 \begin_layout Plain Layout
1457 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1465 \begin_layout Standard
1466 Every now and then, there are changes to LaTeX document classes that break
1467 backwards compatibility.
1471 \begin_layout Plain Layout
1472 Uwe has suggested we implement automatic detection of changes in class files.
1473 This could be done by running a script every month that checks if a document
1474 class was changed at CTAN and at the homepages of the scientific journals.
1475 If it reports a change, we can check if our template and layout file are
1476 still usable with the changed document class.
1477 (This is different from the autotests insofar, as this would also catch
1478 changes that do not result in compilation errors.)
1483 Reasons can be a new name for the
1484 \begin_inset Flex Code
1487 \begin_layout Plain Layout
1493 file, removed \SpecialChar LaTeX
1495 How should this best be handled in \SpecialChar LyX
1499 \begin_layout Standard
1500 The idea is to support the new version with a new \SpecialChar LyX
1504 \begin_layout Itemize
1505 Existing documents can still be opened in \SpecialChar LyX
1506 and will continue to work on
1507 systems where the old version is still installed.
1511 \begin_layout Itemize
1512 With differently named
1513 \begin_inset Flex Code
1516 \begin_layout Plain Layout
1522 files, \SpecialChar LyX
1523 can check for the availability of the particular version and reflect
1525 Different document class versions with the same file name are currently
1526 (2.2.x) not detected by the configuration script.
1527 This is planned for 2.3.
1531 \begin_layout Plain Layout
1532 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1535 \begin_layout Plain Layout
1536 However, what we really need is version detection for the configuration,
1537 so that the user can be warned if the required class file has the wrong
1539 (If the class file keeps the name over the version change, only one of
1540 the two layout files generates compilable documents.)
1543 \begin_layout Plain Layout
1544 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1553 \begin_layout Itemize
1554 The new layout can be added both to the master and the stable branches,
1555 in accord with the policy discussed in
1556 \begin_inset CommandInset ref
1557 LatexCommand formatted
1558 reference "subsec:New-layouts"
1563 No lyx2lyx conversion is then required when a new major version is released.
1566 \begin_layout Standard
1567 The user can move an existing document to the new version simply by selecting
1568 a new document class.
1569 This step is well supported by \SpecialChar LyX
1570 , with established methods for handling
1571 unsupported styles and other changes.
1572 This way, no lyx2lyx code is required.
1575 \begin_layout Standard
1576 The steps to support a new version of an existing document class are thus:
1579 \begin_layout Itemize
1580 Create a new layout file including the upstream version in the name (avoid
1581 special characters like spaces and dots), e.g.
1583 \begin_inset Flex Code
1586 \begin_layout Plain Layout
1587 acmsiggraph-v0-92.layout
1595 \begin_layout Itemize
1596 Include the name of the
1597 \begin_inset Flex Code
1600 \begin_layout Plain Layout
1606 file as an optional argument in the
1607 \begin_inset Flex Code
1610 \begin_layout Plain Layout
1618 line and include the version number in the GUI name:
1619 \begin_inset Newline newline
1623 \begin_inset Flex Code
1626 \begin_layout Plain Layout
1629 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1630 \begin_inset space ~
1641 \begin_layout Itemize
1642 Update the GUI name in the old layout file (whose name should not be changed),
1644 \begin_inset Newline newline
1648 \begin_inset Flex Code
1651 \begin_layout Plain Layout
1654 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1655 \begin_inset space ~
1666 \begin_layout Itemize
1667 To avoid duplicate definitions, the new layout can
1668 \begin_inset Flex Code
1671 \begin_layout Plain Layout
1677 the old layout file and add\SpecialChar breakableslash
1678 remove\SpecialChar breakableslash
1679 obsolete\SpecialChar breakableslash
1680 modify settings and styles (similar
1682 \begin_inset Flex Code
1685 \begin_layout Plain Layout
1695 \begin_layout Standard
1696 It may be tempting to let the new layout be the
1697 \begin_inset Quotes eld
1701 \begin_inset Quotes erd
1704 and have the old layout import it.
1705 However, this should not be done because any changes to the new layout
1706 would need undo steps in the importing old layout.
1710 \begin_layout Itemize
1711 If the new LaTeX document class obsoletes the old one, update the example
1712 and template files to use the new layout.
1713 Add a note about the changes (preferably with a pointer to the documentation
1718 \begin_layout Standard
1719 This way, new documents based on the template or example will use the up-to-date
1720 document class version.
1724 \begin_layout Standard
1725 \begin_inset Newpage newpage
1731 \begin_layout Section
1735 \begin_layout Standard
1736 Automated tests are an important tool to detect bugs and regressions in
1737 software development.
1738 Some projects like gcc even require each bug fix to be accompanied by a
1739 test case for the automatic test suite, that would detect this bug.
1740 Testing interactive features automatically is of course very hard, but
1741 core functionality like document import and export can be tested quite
1742 easily, and some tests of this kind exist.
1745 \begin_layout Subsection
1749 \begin_layout Standard
1750 There are attempts to set up a suite of unit tests for LyX.
1753 \begin_layout Standard
1754 TODO: describe what is done and what is still to do.
1757 \begin_layout Subsection
1761 \begin_layout Standard
1762 The tex2lyx tests are located in the
1763 \begin_inset Flex Code
1766 \begin_layout Plain Layout
1772 subfolder of the \SpecialChar LyX
1773 source code distribution.
1774 The actual testing is performed by the simple python script
1775 \begin_inset Flex Code
1778 \begin_layout Plain Layout
1779 src/tex2lyx/test/runtests.py
1785 Each test consists of two files:
1786 \begin_inset Flex Code
1789 \begin_layout Plain Layout
1795 contains the \SpecialChar LaTeX
1796 code that should be tested.
1798 \begin_inset Flex Code
1801 \begin_layout Plain Layout
1807 contains the expected output of tex2lyx.
1808 When a test is run, the actual produced output is compared with the stored
1810 The test passes if both are identical.
1811 The test machinery is also able to generate a file
1812 \begin_inset Flex Code
1815 \begin_layout Plain Layout
1821 by exporting the produced .lyx file with \SpecialChar LyX
1823 This may be useful for roundtrip comparisons.
1826 \begin_layout Subsubsection
1830 \begin_layout Standard
1831 The tex2lyx tests can be run in several ways.
1833 \begin_inset Flex Code
1836 \begin_layout Plain Layout
1842 subfolder of the build directory, the commands
1843 \begin_inset Flex Code
1846 \begin_layout Plain Layout
1852 (cmake, all platforms),
1853 \begin_inset Flex Code
1856 \begin_layout Plain Layout
1862 (cmake, when using a make based build system and not MSVC) or
1863 \begin_inset Flex Code
1866 \begin_layout Plain Layout
1872 (autotools) will run the tex2lyx tests.
1873 Alternatively, in the root of the build directory, the command
1874 \begin_inset Flex Code
1877 \begin_layout Plain Layout
1883 runs all tests whose names match the regex
1884 \begin_inset Quotes eld
1888 \begin_inset Quotes erd
1892 Another way to run the tex2lyx tests in the root build directory is to
1893 instead use the command
1894 \begin_inset Flex Code
1897 \begin_layout Plain Layout
1898 ctest -L '(cmplyx|roundtrip)'
1903 , which runs all tests categorized with the label
1904 \begin_inset Quotes eld
1908 \begin_inset Quotes erd
1912 \begin_inset Quotes eld
1916 \begin_inset Quotes erd
1920 If a test fails, the differences between the expected and actual results
1921 are output in unified diff format.
1924 \begin_layout Subsubsection
1925 Updating test references
1926 \begin_inset CommandInset label
1928 name "sec:Updating-test-references"
1935 \begin_layout Standard
1936 In some cases a changed tex2lyx output is not a test failure, but wanted,
1938 \begin_inset space \thinspace{}
1942 \begin_inset space \space{}
1945 if a tex2lyx bug was fixed, or a new feature was added.
1946 In these cases the stored references need to be updated.
1947 To do so if using autotools, call
1948 \begin_inset Flex Code
1951 \begin_layout Plain Layout
1958 \begin_inset Flex Code
1961 \begin_layout Plain Layout
1967 subdirectory of the build directory.
1968 If instead using CMake, call
1969 \begin_inset Flex Code
1972 \begin_layout Plain Layout
1973 make updatetex2lyxtests
1978 in the build directory or in the
1979 \begin_inset Flex Code
1982 \begin_layout Plain Layout
1988 subdirectory of the build directory.
1992 \begin_layout Plain Layout
1993 Note that this is a case where a make target in the build directory can
1994 affect the source directory, which might not be advisable.
1999 On Windows do the following:
2002 \begin_layout Itemize
2003 Assure that the path to the python.exe is in your system PATH variable.
2006 \begin_layout Itemize
2007 Double-click on the file
2008 \begin_inset Flex Code
2011 \begin_layout Plain Layout
2012 updatetex2lyxtests.vcxproj
2017 in the build directory or in the
2018 \begin_inset Flex Code
2021 \begin_layout Plain Layout
2027 subdirectory of your build directory.
2030 \begin_layout Itemize
2031 In the appearing MSVC program assure that you build the
2035 version, then right-click on the project
2039 in the project explorer and choose then
2042 \begin_inset space ~
2045 Only\SpecialChar menuseparator
2047 \begin_inset space ~
2055 \begin_layout Standard
2056 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2058 Please examine the changed output carefully before committing the changed
2059 files to the repository: Since the test machinery does not do a roundtrip
2061 \begin_inset Formula $\Rightarrow$
2065 \begin_inset Formula $\Rightarrow$
2068 .tex, and does not compare the produced dvi or pdf output, it assumes that
2069 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2071 There is only one chance to detect wrong output: before committing a new
2073 Once it is committed, it is quite difficult to verify whether it is correct.
2076 \begin_layout Standard
2081 update the test references by opening them with \SpecialChar LyX
2082 or directly running lyx2lyx
2084 This would not work, since lyx2lyx and \SpecialChar LyX
2085 produce slightly different files
2086 regarding insignificant whitespace and line breaks.
2089 \begin_layout Subsubsection
2093 \begin_layout Standard
2094 In many cases tests for new features may be added to one of the existing
2095 test files, but sometimes this is not possible or not wanted.
2096 Then a new test file needs to be added:
2099 \begin_layout Enumerate
2101 \begin_inset Flex Code
2104 \begin_layout Plain Layout
2105 src/tex2lyx/test/<test name>.tex
2110 and run tex2lyx in roundtrip mode to produce the file
2111 \begin_inset Flex Code
2114 \begin_layout Plain Layout
2115 src/tex2lyx/test/<test name>.lyx.lyx
2121 This file will be the new reference.
2124 \begin_layout Enumerate
2125 Once you confirmed that the tex2lyx output is correct, add the new files
2126 to the corresponding lists in
2127 \begin_inset Flex Code
2130 \begin_layout Plain Layout
2131 src/tex2lyx/test/runtests.py
2137 \begin_inset Flex Code
2140 \begin_layout Plain Layout
2141 src/tex2lyx/Makefile.am
2147 \begin_inset Flex Code
2150 \begin_layout Plain Layout
2151 src/tex2lyx/test/CMakeLists.txt
2159 \begin_layout Enumerate
2160 Commit the changes to the repository, or send a patch to the development
2161 list and ask for committing if you do not have commit rights.
2164 \begin_layout Subsection
2165 ctest automatic tests
2168 \begin_layout Standard
2169 Some tests are located in the
2170 \begin_inset Flex Code
2173 \begin_layout Plain Layout
2174 development/autotests/
2179 subfolder of the \SpecialChar LyX
2180 source code distribution.
2185 \begin_layout Plain Layout
2186 The README document in this folder only describes the
2187 \begin_inset Quotes eld
2191 \begin_inset Quotes erd
2194 subset of autotests!
2202 \begin_layout Standard
2203 These tests can be run by the commands
2204 \begin_inset Flex Code
2207 \begin_layout Plain Layout
2217 (all platforms) or (when using a make based build system and not MSVC)
2219 \begin_inset Flex Code
2222 \begin_layout Plain Layout
2229 \begin_inset Flex Code
2232 \begin_layout Plain Layout
2243 The test logs are written to the
2244 \begin_inset Flex Code
2247 \begin_layout Plain Layout
2261 \begin_layout Subsubsection
2265 \begin_layout Standard
2266 The export tests are integration tests.
2267 They take longer to run and are more likely to break than the tex2lyx tests.
2268 Nevertheless, they have caught many regressions and without a better alternativ
2269 e it is important to keep them up-to-date and understand how they work.
2272 \begin_layout Standard
2274 \begin_inset Quotes eld
2278 \begin_inset Quotes erd
2281 documentation, template, and example documents.
2282 In addition, there are a number of dedicated sample documents in the
2283 \begin_inset Flex Code
2286 \begin_layout Plain Layout
2292 subfolder of the \SpecialChar LyX
2293 source code distribution.
2294 All samples are (after copying and eventual processing by scripts) exported
2295 to various output formats via the
2296 \begin_inset Flex Code
2299 \begin_layout Plain Layout
2305 command line option.
2306 The tests checks for errors reported by LyX.
2307 (However, error-free export is no guarantee for an error-free output document.)
2310 \begin_layout Paragraph
2311 \begin_inset CommandInset label
2313 name "par:when-to-run-an-export-test"
2317 Expectations of LyX developers
2320 \begin_layout Standard
2321 Because the export tests are integration tests and take a long time to run,
2322 LyX developers are rarely expected to run all of the tests.
2323 Here are some good practices to follow by developers:
2326 \begin_layout Itemize
2327 When making a non-trivial change to a .layout file, run the export and layout
2328 tests corresponding with that .layout file.
2331 \begin_layout Itemize
2332 When making non-trivial changes to a .lyx file, run the export tests correspondin
2333 g to that .lyx file.
2338 \begin_layout Plain Layout
2339 This rule is due to revision.
2343 \begin_layout Plain Layout
2344 There is an objection from the documentation maintainer that working on
2345 the documentation must not be complicated by having to consider non-standard
2349 \begin_layout Itemize
2350 successful compiling/testing an edited documentation file with pdflatex
2351 suffices to ensure it can be commited, not tests with other exports are
2355 \begin_layout Plain Layout
2356 If sudden failures with other exports due to “half-tested” documentation
2357 updates are a problem for the test maintainer, the test suite should use
2361 \begin_layout Itemize
2362 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2365 \begin_layout Itemize
2366 updated regularely (but on a time chosen by the test suite maintainer) from
2367 the originals in lib/doc/
2370 \begin_layout Plain Layout
2374 \begin_layout Itemize
2375 no test will fail due to ongoing work on documentation,
2378 \begin_layout Itemize
2379 the documentation is still tested in full (with some delay),
2382 \begin_layout Itemize
2383 failures with non-default export can be examined and handled accordingly
2384 in one run with the cache update,
2387 \begin_layout Itemize
2388 “interesting failures” (like the nested-language+polyglossia problem in
2389 es/Customization can be separated and moved into dedicated test samples.
2397 \begin_layout Itemize
2398 When making non-trivial changes to LyX's \SpecialChar LaTeX
2400 touching the encoding code or package handling code that you expect will
2401 change the exported \SpecialChar LaTeX
2406 \begin_layout Standard
2407 \paragraph_spacing single
2408 Consider running all of the export tests before and after your change.
2409 If there are differences, please reconcile these (i.e.
2410 fix the bug or fix the tests)
2415 Ask for help if you're not sure what to.
2418 \begin_layout Standard
2419 If you do not want to run the tests,
2422 \begin_layout Itemize
2423 post the patch on the list and others will run the tests and eventually
2427 \begin_layout Itemize
2428 commit, but be prepared to fix eventually arising problems or to revert
2429 the commit if there is no easy fix.
2433 \begin_layout Itemize
2434 Understand how to interpret test failures.
2435 If your commit is found to have broken a test, you should be able to interpret
2436 the test results when made aware of them.
2438 \begin_inset CommandInset ref
2440 reference "subsec:Interpreting-export-tests"
2447 \begin_layout Paragraph
2448 \begin_inset CommandInset label
2450 name "par:export-test-output-formats"
2457 \begin_layout Standard
2458 The following output formats are currently tested for each sample document
2460 \begin_inset CommandInset ref
2462 reference "par:Export-test-filtering"
2469 \begin_layout Labeling
2470 \labelwidthstring 00.00.0000
2475 \begin_layout Labeling
2476 \labelwidthstring 00.00.0000
2477 lyx16 LyX 1.6 file format (lyx2lyx)
2480 \begin_layout Labeling
2481 \labelwidthstring 00.00.0000
2482 lyx21 LyX 2.1 file format (lyx2lyx)
2485 \begin_layout Labeling
2486 \labelwidthstring 00.00.0000
2487 xhtml LyXHTML (native LyX HTML export)
2491 \begin_layout Labeling
2492 \labelwidthstring 00.00.0000
2494 \begin_inset space ~
2498 \begin_inset space ~
2505 \begin_layout Labeling
2506 \labelwidthstring pdf5msystemFM
2507 dvi DVI (8-bit latex)
2510 \begin_layout Labeling
2511 \labelwidthstring pdf5msystemFM
2512 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2515 \begin_layout Labeling
2516 \labelwidthstring pdf5msystemFM
2517 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2520 \begin_layout Labeling
2521 \labelwidthstring pdf5msystemFM
2525 \begin_layout Labeling
2526 \labelwidthstring pdf5msystemFM
2527 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2530 \begin_layout Labeling
2531 \labelwidthstring pdf5msystemFM
2532 pdf4_systemF PDF (XeTeX with Unicode fonts)
2535 \begin_layout Labeling
2536 \labelwidthstring pdf5msystemFM
2537 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2540 \begin_layout Labeling
2541 \labelwidthstring pdf5msystemFM
2542 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2546 \begin_layout Labeling
2547 \labelwidthstring 00.00.0000
2549 \begin_inset space ~
2553 \begin_inset space ~
2557 \begin_inset space ~
2561 \begin_inset space ~
2568 \begin_layout Labeling
2569 \labelwidthstring pdf5msystemFM
2570 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2573 \begin_layout Labeling
2574 \labelwidthstring pdf5msystemFM
2575 pdf3 DVI -> PDF (dvipdfm)
2579 \begin_layout Labeling
2580 \labelwidthstring 00.00.0000
2582 \begin_inset space ~
2585 tested: (or only if set as default output format in the document source)
2589 \begin_layout Labeling
2590 \labelwidthstring pdf5msystemFM
2594 \begin_layout Labeling
2595 \labelwidthstring pdf5msystemFM
2596 luatex LaTeX (LuaTeX)
2599 \begin_layout Labeling
2600 \labelwidthstring pdf5msystemFM
2601 dviluatex LaTeX (dviluatex)
2604 \begin_layout Labeling
2605 \labelwidthstring pdf5msystemFM
2606 pdflatex LaTeX (pdflatex)
2609 \begin_layout Labeling
2610 \labelwidthstring pdf5msystemFM
2611 platex LaTeX (pLaTeX)
2614 \begin_layout Labeling
2615 \labelwidthstring pdf5msystemFM
2619 \begin_layout Labeling
2620 \labelwidthstring pdf5msystemFM
2621 eps3 EPS (encapsulated Postscript) (cropped)
2624 \begin_layout Labeling
2625 \labelwidthstring pdf5msystemFM
2626 ps DVI -> Postscript (dvips)
2629 \begin_layout Labeling
2630 \labelwidthstring pdf5msystemFM
2634 \begin_layout Labeling
2635 \labelwidthstring pdf5msystemFM
2636 text (nor text2, ..., text4)
2639 \begin_layout Labeling
2640 \labelwidthstring pdf5msystemFM
2644 \begin_layout Labeling
2645 \labelwidthstring pdf5msystemFM
2649 \begin_layout Labeling
2650 \labelwidthstring pdf5msystemFM
2654 \begin_layout Labeling
2655 \labelwidthstring pdf5msystemFM
2660 \begin_layout Paragraph
2661 \begin_inset CommandInset label
2663 name "par:Configuring-ctests"
2667 Configuring the tests
2670 \begin_layout Standard
2671 To enable the export autotests, add the
2672 \begin_inset Flex Code
2675 \begin_layout Plain Layout
2676 -DLYX_ENABLE_EXPORT_TESTS=ON
2685 \begin_layout Standard
2686 \begin_inset Flex Code
2689 \begin_layout Plain Layout
2690 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2698 \begin_layout Standard
2700 This flag will increase the time for the cmake command by several seconds,
2701 mainly because of the process of inverting tests (see Section
2702 \begin_inset CommandInset ref
2704 reference "subsec:Interpreting-export-tests"
2711 \begin_layout Paragraph
2712 \begin_inset CommandInset label
2714 name "par:ctest-options"
2721 \begin_layout Standard
2722 To run all tests, in the build directory simply run the command
2723 \begin_inset Flex Code
2726 \begin_layout Plain Layout
2733 A full, up-to-date TeXLive installation is recommended to run the tests.
2734 Otherwise, some tests will fail.
2735 Tests with additional requirements are labeled
2736 \begin_inset Quotes eld
2739 unreliable:nonstandard
2740 \begin_inset Quotes erd
2747 \begin_layout Standard
2748 To run only some of the tests, use command line options (see examples below):
2751 \begin_layout Labeling
2752 \labelwidthstring -R
2753 \begin_inset Flex Code
2756 \begin_layout Plain Layout
2762 Run only the tests whose names match the given regular expression.
2765 \begin_layout Labeling
2766 \labelwidthstring -R
2767 \begin_inset Flex Code
2770 \begin_layout Plain Layout
2776 Run only the tests whose labels match the given regular expression.
2777 A test may have more that one label.
2781 \begin_layout Labeling
2782 \labelwidthstring -R
2783 \begin_inset Flex Code
2786 \begin_layout Plain Layout
2792 Exclude the tests whose names match the given regular expression.
2795 \begin_layout Labeling
2796 \labelwidthstring -R
2797 \begin_inset Flex Code
2800 \begin_layout Plain Layout
2806 Exclude the tests whose labels match the given regular expression.
2807 Cannot be combined with
2808 \begin_inset Flex Code
2811 \begin_layout Plain Layout
2820 \begin_layout Standard
2821 The following options help to find good selection patterns:
2824 \begin_layout Labeling
2825 \labelwidthstring -R
2826 \begin_inset Flex Code
2829 \begin_layout Plain Layout
2835 List the tests that would be run but not actually run them.
2840 \begin_layout Standard
2841 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2842 to know how many tests there are or whether your
2843 \begin_inset Flex Code
2846 \begin_layout Plain Layout
2852 regular expression did what you expected.
2856 \begin_layout Labeling
2857 \labelwidthstring -R
2858 \begin_inset Flex Code
2861 \begin_layout Plain Layout
2862 \SpecialChar nobreakdash
2863 \SpecialChar nobreakdash
2869 print the list of all labels associated with the test set.
2870 Can also be combined with -R, -L, -E, ...
2874 \begin_layout Standard
2875 Other useful options are:
2878 \begin_layout Labeling
2879 \labelwidthstring -R
2880 \begin_inset Flex Code
2883 \begin_layout Plain Layout
2889 Run the tests in parallel using the given number of jobs.
2893 \begin_layout Standard
2894 We are still working on getting the tests to run in parallel.
2895 However, when running the tests in parallel, sometimes tests fail that
2896 pass when run sequentially.
2897 A reasonable approach is to first run the tests in parallel and then run
2898 the failed tests sequentially.
2901 \begin_layout Standard
2902 For example, to run 8 jobs at a time:
2905 \begin_layout Standard
2906 \begin_inset Flex Code
2909 \begin_layout Plain Layout
2918 \begin_layout Standard
2919 \begin_inset Flex Code
2922 \begin_layout Plain Layout
2923 ctest \SpecialChar nobreakdash
2924 \SpecialChar nobreakdash
2933 \begin_layout Standard
2934 When specifying a subset of the tests (e.g.
2936 \begin_inset Flex Code
2939 \begin_layout Plain Layout
2940 \SpecialChar nobreakdash
2946 ), the same subset must be specified when using the
2947 \begin_inset Flex Code
2950 \begin_layout Plain Layout
2951 \SpecialChar nobreakdash
2952 \SpecialChar nobreakdash
2958 option because it is the test numbers that are used to index which tests
2959 failed on the previous run.
2962 \begin_layout Standard
2964 Note that some tests cannot be run in parallel.
2965 These tests are marked in the code with the
2966 \begin_inset Flex Code
2969 \begin_layout Plain Layout
2980 \begin_layout Labeling
2981 \labelwidthstring -R
2982 \begin_inset Flex Code
2985 \begin_layout Plain Layout
2986 \SpecialChar nobreakdash
2987 \SpecialChar nobreakdash
2993 Set a global timeout on all tests that do not already have a timeout set
2998 \begin_layout Standard
2999 There have been bugs in LyX and in \SpecialChar LaTeX
3000 which cause compilation to hang, and
3001 without a timeout a test might never stop (in one case there was even a
3003 If a test times out, the
3004 \begin_inset Flex Code
3007 \begin_layout Plain Layout
3013 command exits with error, but you can distinguish between a timed out test
3014 and a failed test in the output reported at the end of the
3015 \begin_inset Flex Code
3018 \begin_layout Plain Layout
3028 \begin_layout Standard
3030 \begin_inset Flex Code
3033 \begin_layout Plain Layout
3039 ) the full list of command line options.
3042 \begin_layout Paragraph
3046 \begin_layout Itemize
3047 run only the export tests:
3048 \begin_inset Flex Code
3051 \begin_layout Plain Layout
3060 \begin_layout Itemize
3062 \begin_inset Flex Code
3065 \begin_layout Plain Layout
3066 ctest -L "inverted|suspended"
3074 \begin_layout Itemize
3075 list all export tests which match any of the labelling patterns:
3076 \begin_inset Flex Code
3079 \begin_layout Plain Layout
3090 \begin_layout Itemize
3091 exclude rarely used output formats and post-processing tests
3092 \begin_inset Flex Code
3095 \begin_layout Plain Layout
3096 ctest -L export -E "_(texF|dvi3|pdf3?)"
3104 \begin_layout Paragraph
3105 \begin_inset CommandInset label
3107 name "subsec:Interpreting-export-tests"
3111 Interpreting the export test results
3114 \begin_layout Standard
3115 A test can fail for several reasons, not all of them bad.
3118 \begin_layout Enumerate
3119 A new or edited sample document may be incompatible with some output formats.
3122 \begin_layout Enumerate
3123 A dependency is not met (e.g.
3124 the \SpecialChar LaTeX
3126 One hint that this is the case is that the corresponding
3127 \begin_inset Flex Code
3130 \begin_layout Plain Layout
3136 test will likely also fail.
3139 \begin_layout Enumerate
3140 An inverted test fails to fail (i.e.
3141 export that previously failed now works).
3144 \begin_layout Enumerate
3145 An external dependency was updated (e.g.
3150 \begin_layout Enumerate
3151 A recent code change introduced a bug.
3154 \begin_layout Enumerate
3155 \begin_inset CommandInset label
3161 A change in a document exposed a previously unknown bug or an incompatibility
3162 with an export format (e.g.
3163 Lua\SpecialChar LaTeX
3167 \begin_layout Standard
3168 Because the .lyx files are exported in several formats, it is not surprising
3169 that many of the exports fail.
3170 This expectation of failure is addressed by
3171 \begin_inset Quotes eld
3175 \begin_inset Quotes erd
3178 the tests, that is, by marking the test as
3179 \begin_inset Quotes eld
3183 \begin_inset Quotes erd
3186 if the export exits with error and as
3187 \begin_inset Quotes eld
3191 \begin_inset Quotes erd
3194 if the export succeeds
3199 It follows that these expected failures will not show up as failed tests
3200 in the test results and thus will not pollute the
3201 \begin_inset Quotes eld
3205 \begin_inset Quotes erd
3209 If the export actually succeeds, then the test will fail.
3210 The purpose of this failure is to get your attention—something has changed,
3211 possibly for the better.
3214 \begin_layout Standard
3215 We try to document why a test is inverted or ignored.
3216 See the comment (prefixed with
3217 \begin_inset Flex Code
3220 \begin_layout Plain Layout
3226 ) above the block in which the test is listed as inverted or ignored in
3228 \begin_inset Flex Code
3231 \begin_layout Plain Layout
3232 development/autotests/invertedTests
3238 \begin_inset Flex Code
3241 \begin_layout Plain Layout
3242 development/autotests/unreliableTests
3248 \begin_inset Flex Code
3251 \begin_layout Plain Layout
3252 development/autotests/ignoredTests
3261 \begin_layout Standard
3262 A good question is why do we enable the tests for non-default formats? The
3263 answer is that if a non-default route is broken it is often because a bug
3264 was introduced in LyX and not because a document-specific change was made
3265 that is not supported by the route.
3266 In other words, there is a high signal/noise ratio in the export tests
3267 for some non-default formats.
3271 \begin_layout Standard
3272 When a test or several tests fail, consider checking the files in the
3273 \begin_inset Flex Code
3276 \begin_layout Plain Layout
3282 subdirectory of your build directory.
3283 In this subdirectory are three files: the file
3284 \begin_inset Flex Code
3287 \begin_layout Plain Layout
3293 simply lists the tests that failed on your last
3294 \begin_inset Flex Code
3297 \begin_layout Plain Layout
3304 \begin_inset Flex Code
3307 \begin_layout Plain Layout
3313 file contains the output from the tests (and often has details explaining
3314 why a test failed); and the
3315 \begin_inset Flex Code
3318 \begin_layout Plain Layout
3324 file lists the times that it took to run the tests.
3327 \begin_layout Paragraph
3328 What action should you take if a test fails?
3331 \begin_layout Standard
3332 \paragraph_spacing single
3333 It is always good to check manually why something fails and if it passes
3334 if the PDF output is good.
3337 \begin_layout Itemize
3338 Generally, if a change breaks compilation for the target format (for the
3339 manuals pdf2) without solving some important other issue,
3341 fix or revert the commit
3343 that led to failure.
3346 \begin_layout Itemize
3347 If it is not possible to (immediately) fix the failure but there are reasons
3348 not to revert the commit (e.g.
3349 it fixes another more important issue),
3353 the failing test case (see
3354 \begin_inset CommandInset ref
3356 reference "par:Inverted-tests"
3363 \begin_layout Itemize
3368 test case fails because the export now works,
3372 the test by removing the pattern from the
3373 \begin_inset Quotes eld
3377 \begin_inset Quotes erd
3381 \begin_inset CommandInset ref
3383 reference "par:Inverted-tests"
3390 \begin_layout Itemize
3391 If the export did not fail previously but led to wrong output (PDF, say),
3395 \begin_layout Plain Layout
3396 Non-failing test with wrong output should be labeled as
3397 \begin_inset Quotes eld
3400 unreliable:wrong_output
3401 \begin_inset Quotes erd
3405 \begin_inset CommandInset ref
3407 reference "par:Unreliable-tests"
3416 it is in fact an improvement when the test now fails.
3421 the failing test case (see
3422 \begin_inset CommandInset ref
3424 reference "par:Inverted-tests"
3431 \begin_layout Itemize
3432 In case of tests failing due to missing requirements (tests labeled
3433 \begin_inset Quotes eld
3436 unreliable:nonstandard
3437 \begin_inset Quotes erd
3440 or testing on a system with only a subset of TeXLive installed), ignore
3441 the failure, ask for someone else to run the test, or install the missing
3442 resources and try again.
3445 \begin_layout Itemize
3446 Check the log file Testing/Temporary/LastTest.log.
3447 In case of latex-errors rerun the failing test with environment variable
3448 'LAX_DEBUG_LATEX' set to '1'.
3449 This will include latex messages in LastTest.log, so it should be easier
3450 to interpret the fail-reason.
3453 \begin_layout Paragraph
3454 \begin_inset CommandInset label
3456 name "par:Inverted-tests"
3463 \begin_layout Standard
3464 Test cases whose name matches a pattern in the file
3465 \begin_inset Flex Code
3468 \begin_layout Plain Layout
3469 development/autotests/invertedTests
3479 They get also the test property
3480 \begin_inset Flex Code
3483 \begin_layout Plain Layout
3490 they are reported as failing if the export works without error
3491 \begin_inset Flex URL
3494 \begin_layout Plain Layout
3496 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3504 \begin_layout Standard
3505 Add failing cases to this file, if they cannot be solved
3506 \begin_inset Quotes eld
3510 \begin_inset Quotes erd
3513 but it is expected that the export will work in a foreseeable future, e.g.
3514 low priority issues like failures to export to a non-target format (for
3515 the manuals everything except pdf2).
3518 \begin_layout Standard
3519 The following sublabels are currently present in
3520 \begin_inset Flex Code
3523 \begin_layout Plain Layout
3532 \begin_layout Description
3533 todo test failures that require attention:
3537 \begin_layout Itemize
3538 minor issues to explore and properly sort later,
3541 \begin_layout Itemize
3545 \begin_layout Itemize
3546 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3550 \begin_layout Description
3551 lyxbugs LyX bugs with a Trac number.
3554 \begin_layout Description
3555 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3559 \begin_layout Standard
3560 "Wontfix" if demonstrating correct use and OK in the default output format.
3564 \begin_layout Description
3565 texissues Export fails due to LaTeX limitations like non-ASCII characters
3566 in verbatim or listings, incompatible packages, ...
3570 \begin_layout Standard
3571 "Wontfix" if documents demonstrate correct use in the default output format:
3574 \begin_layout Itemize
3575 If the source can be made more robust without becoming "hackish", fix the
3579 \begin_layout Itemize
3580 if LyX could be enhanced to care for a permanent TeX limitation, file a
3581 ticket at trac and add a pattern under lyxbugs,
3584 \begin_layout Itemize
3585 otherwise, add a pattern here.
3589 \begin_layout Description
3590 attic Documents in the attic (kept for reference and format conversion test).
3592 \begin_inset Quotes eld
3596 \begin_inset Quotes erd
3602 \begin_layout Subparagraph
3606 \begin_layout Standard
3607 Test cases whose name additionally matches a pattern in the file
3608 \begin_inset Flex Code
3611 \begin_layout Plain Layout
3612 development/autotests/suspendedTests
3630 This means they are not executed using
3631 \begin_inset Flex Code
3634 \begin_layout Plain Layout
3641 \begin_inset Flex Code
3644 \begin_layout Plain Layout
3651 However, they also get the test property
3652 \begin_inset Flex Code
3655 \begin_layout Plain Layout
3662 they are reported as failing if the export works without error.
3663 From time to time they still have to be checked using
3664 \begin_inset Flex Code
3667 \begin_layout Plain Layout
3676 \begin_layout Standard
3677 These tests are suspended, because the export fails for known reasons which
3678 cannot ATM be resolved.
3679 But it is expected the reason might disappear in the future.
3680 Be it new TL or better handling in \SpecialChar LyX
3684 \begin_layout Standard
3685 For ctest commands without the
3686 \begin_inset Flex Code
3689 \begin_layout Plain Layout
3695 parameter nothing changes.
3696 Suspended or not, tests will be executed depending only on the selecting
3697 regular expression given to the ctest command (see
3698 \begin_inset CommandInset ref
3700 reference "par:ctest-options"
3707 \begin_layout Paragraph
3708 \begin_inset CommandInset label
3710 name "par:Unreliable-tests"
3717 \begin_layout Standard
3718 Test cases whose name matches a pattern in the file
3719 \begin_inset Flex Code
3722 \begin_layout Plain Layout
3723 development/autotests/unreliableTests
3735 \begin_layout Standard
3736 These tests are not executed using
3737 \begin_inset Flex Code
3740 \begin_layout Plain Layout
3747 \begin_inset Flex Code
3750 \begin_layout Plain Layout
3760 \begin_layout Standard
3761 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3762 or pass but should rather fail (wrong output).
3764 \begin_inset Note Note
3767 \begin_layout Plain Layout
3768 *invalid* tests (wrong output) are not *unreliable*.
3769 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3778 \begin_layout Standard
3779 The following sublabels are currently present in
3780 \begin_inset Flex Code
3783 \begin_layout Plain Layout
3792 \begin_layout Description
3793 nonstandard Documents with additional requirements, e.g.
3794 a class or package file not in TeXLive.
3796 \begin_inset Note Note
3799 \begin_layout Plain Layout
3801 \begin_inset Quotes eld
3805 \begin_inset Quotes erd
3809 \begin_inset Quotes eld
3813 \begin_inset Quotes erd
3824 \begin_layout Description
3825 erratic Tests depending on local configuration or the phase of the moon.
3829 \begin_layout Description
3830 varying_versions Tests depending on e.g.
3831 OS or version of a non-TeX-Live dependency.
3832 Note that a full, up-to-date TeX Live installation is required so this
3833 sublabel is about versions of other dependencies.
3836 \begin_layout Description
3838 \begin_inset space ~
3841 output Export does not fail but the resulting document has (undetected)
3846 \begin_layout Standard
3847 \paragraph_spacing single
3848 \begin_inset Note Note
3851 \begin_layout Plain Layout
3852 \paragraph_spacing single
3853 These tests are in a strict sense not unreliable but
3857 (not measuring what they should measure).
3866 \begin_layout Paragraph
3867 \begin_inset CommandInset label
3869 name "par:Export-test-filtering"
3873 Export test filtering
3876 \begin_layout Standard
3877 The assignment of a label to a test is controlled by a set of files with
3878 regular expressions that are matched against the test names.
3881 \begin_layout Description
3882 ignoredTests (small file)
3883 \begin_inset Newline newline
3886 Tests selected here are withdrawn in the configuration step (cf.
3888 \begin_inset CommandInset ref
3890 reference "par:Configuring-ctests"
3898 \begin_layout Labeling
3899 \labelwidthstring 00.00.0000
3900 Input Test of any export combination
3903 \begin_layout Labeling
3904 \labelwidthstring 00.00.0000
3905 Output Stop if tests not selected here
3909 \begin_layout Description
3910 unreliableTests: Tests selected pass or fail dependent on the system where
3912 Selected tests gain the label 'unreliable'.
3916 \begin_layout Labeling
3917 \labelwidthstring 00.00.0000
3918 Input Each test which passed 'ignoredTests'
3921 \begin_layout Labeling
3922 \labelwidthstring 00.00.0000
3923 Output Gain label 'unreliable', proceed with checking for 'inverted'.
3927 \begin_layout Description
3929 \begin_inset space \space{}
3936 \begin_layout Labeling
3937 \labelwidthstring 00.00.0000
3938 Input Each test which passed 'ignoredTests'
3941 \begin_layout Labeling
3942 \labelwidthstring 00.00.0000
3943 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3944 tests are reported as failing if the export works without error.) If no
3945 subselection applies, gain labels 'export' and 'inverted'.
3948 \begin_layout Standard
3949 The following filter perfoms a subselection of 'invertedTests':
3952 \begin_layout Description
3953 suspendedTests Tests selected here gain the label 'suspended' but _not_
3954 'export' or 'inverted', although in ctest they remain inverted.
3955 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3959 \begin_layout Labeling
3960 \labelwidthstring 00.00.0000
3961 Input Each test selected by 'invertedTests'
3964 \begin_layout Labeling
3965 \labelwidthstring 00.00.0000
3966 Output Selected test gains label 'suspended'.
3972 \begin_layout Standard
3973 The following table may clarify label assignement
3976 \begin_layout Standard
3977 \begin_inset space \hspace{}
3982 \begin_inset Tabular
3983 <lyxtabular version="3" rows="6" columns="8">
3984 <features tabularvalignment="middle">
3985 <column alignment="left" valignment="top" width="2cm">
3986 <column alignment="left" valignment="top" width="2.5cm">
3987 <column alignment="left" valignment="top" width="2cm">
3988 <column alignment="center" valignment="top" width="2.5cm">
3989 <column alignment="center" valignment="top">
3990 <column alignment="center" valignment="top">
3991 <column alignment="center" valignment="top">
3992 <column alignment="center" valignment="top">
3994 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3997 \begin_layout Plain Layout
3998 Test matching pattern in file:
4003 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4006 \begin_layout Plain Layout
4012 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4015 \begin_layout Plain Layout
4021 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4024 \begin_layout Plain Layout
4030 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4033 \begin_layout Plain Layout
4039 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4042 \begin_layout Plain Layout
4048 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4051 \begin_layout Plain Layout
4057 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4060 \begin_layout Plain Layout
4068 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4071 \begin_layout Plain Layout
4072 ignored\SpecialChar softhyphen
4078 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4081 \begin_layout Plain Layout
4082 unreliable\SpecialChar softhyphen
4088 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4091 \begin_layout Plain Layout
4092 inverted\SpecialChar softhyphen
4098 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4101 \begin_layout Plain Layout
4102 suspended\SpecialChar softhyphen
4108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4111 \begin_layout Plain Layout
4117 <cell alignment="center" valignment="top" topline="true" usebox="none">
4120 \begin_layout Plain Layout
4126 <cell alignment="center" valignment="top" topline="true" usebox="none">
4129 \begin_layout Plain Layout
4135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4138 \begin_layout Plain Layout
4146 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4149 \begin_layout Plain Layout
4155 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4158 \begin_layout Plain Layout
4164 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4167 \begin_layout Plain Layout
4173 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4176 \begin_layout Plain Layout
4182 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4185 \begin_layout Plain Layout
4191 <cell alignment="center" valignment="top" topline="true" usebox="none">
4194 \begin_layout Plain Layout
4200 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4203 \begin_layout Plain Layout
4209 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4212 \begin_layout Plain Layout
4220 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4223 \begin_layout Plain Layout
4229 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4232 \begin_layout Plain Layout
4234 \begin_inset Newline newline
4238 \begin_inset Newline newline
4246 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4249 \begin_layout Plain Layout
4255 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4258 \begin_layout Plain Layout
4264 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4267 \begin_layout Plain Layout
4273 <cell alignment="center" valignment="top" topline="true" usebox="none">
4276 \begin_layout Plain Layout
4282 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4285 \begin_layout Plain Layout
4291 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4294 \begin_layout Plain Layout
4302 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4305 \begin_layout Plain Layout
4311 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4314 \begin_layout Plain Layout
4320 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4323 \begin_layout Plain Layout
4329 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4332 \begin_layout Plain Layout
4338 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4341 \begin_layout Plain Layout
4347 <cell alignment="center" valignment="top" topline="true" usebox="none">
4350 \begin_layout Plain Layout
4356 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4359 \begin_layout Plain Layout
4365 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4368 \begin_layout Plain Layout
4376 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4379 \begin_layout Plain Layout
4385 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4388 \begin_layout Plain Layout
4394 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4397 \begin_layout Plain Layout
4403 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4406 \begin_layout Plain Layout
4412 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4415 \begin_layout Plain Layout
4421 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4424 \begin_layout Plain Layout
4430 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4433 \begin_layout Plain Layout
4439 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4442 \begin_layout Plain Layout
4456 \begin_layout Standard
4457 \begin_inset Note Note
4460 \begin_layout Plain Layout
4462 \begin_inset Quotes eld
4466 \begin_inset Quotes erd
4469 filter, this would be far less complicated:
4472 \begin_layout Plain Layout
4473 \begin_inset Tabular
4474 <lyxtabular version="3" rows="6" columns="7">
4475 <features tabularvalignment="middle">
4476 <column alignment="left" valignment="top" width="0pt">
4477 <column alignment="left" valignment="top" width="0pt">
4478 <column alignment="left" valignment="top" width="0pt">
4479 <column alignment="center" valignment="top">
4480 <column alignment="center" valignment="top">
4481 <column alignment="center" valignment="top">
4482 <column alignment="center" valignment="top">
4484 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4487 \begin_layout Plain Layout
4488 Test matching pattern in file:
4493 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4496 \begin_layout Plain Layout
4502 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4505 \begin_layout Plain Layout
4511 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4514 \begin_layout Plain Layout
4520 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4523 \begin_layout Plain Layout
4529 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4532 \begin_layout Plain Layout
4538 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4541 \begin_layout Plain Layout
4549 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4552 \begin_layout Plain Layout
4558 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4561 \begin_layout Plain Layout
4567 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4570 \begin_layout Plain Layout
4576 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4579 \begin_layout Plain Layout
4585 <cell alignment="center" valignment="top" topline="true" usebox="none">
4588 \begin_layout Plain Layout
4594 <cell alignment="center" valignment="top" topline="true" usebox="none">
4597 \begin_layout Plain Layout
4603 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4606 \begin_layout Plain Layout
4614 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4617 \begin_layout Plain Layout
4623 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4626 \begin_layout Plain Layout
4632 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4635 \begin_layout Plain Layout
4641 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4644 \begin_layout Plain Layout
4650 <cell alignment="center" valignment="top" topline="true" usebox="none">
4653 \begin_layout Plain Layout
4659 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4662 \begin_layout Plain Layout
4668 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4671 \begin_layout Plain Layout
4679 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4682 \begin_layout Plain Layout
4688 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4691 \begin_layout Plain Layout
4697 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4700 \begin_layout Plain Layout
4706 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4709 \begin_layout Plain Layout
4715 <cell alignment="center" valignment="top" topline="true" usebox="none">
4718 \begin_layout Plain Layout
4724 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4727 \begin_layout Plain Layout
4733 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4736 \begin_layout Plain Layout
4744 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4747 \begin_layout Plain Layout
4753 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4756 \begin_layout Plain Layout
4762 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4765 \begin_layout Plain Layout
4771 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4774 \begin_layout Plain Layout
4780 <cell alignment="center" valignment="top" topline="true" usebox="none">
4783 \begin_layout Plain Layout
4789 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4792 \begin_layout Plain Layout
4798 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4801 \begin_layout Plain Layout
4809 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4812 \begin_layout Plain Layout
4818 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4821 \begin_layout Plain Layout
4827 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4830 \begin_layout Plain Layout
4836 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4839 \begin_layout Plain Layout
4845 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4848 \begin_layout Plain Layout
4854 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4857 \begin_layout Plain Layout
4863 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4866 \begin_layout Plain Layout
4885 \begin_layout Subsubsection
4889 \begin_layout Standard
4890 These tests check whether a .lyx file loads without any terminal messages.
4891 They correspond to the manual operations of simply opening a .lyx file on
4892 the terminal, exiting LyX once the file is loaded, and then checking whether
4893 there is any output from the terminal.
4894 These tests are useful for catching malformed .lyx files and parsing bugs.
4895 They can also be used to find a .lyx file in which an instance of something
4897 To do this, compile LyX with a local patch that outputs something to the
4898 terminal when an instance is found, and then run the check_load tests to
4899 see if any fail, which would mean that the situation occurs in the LyX
4900 documentation files corresponding to the failed tests.
4901 These tests are expectedly fragile: any LyX diagnostic message, which is
4902 not necessarily an error, would cause the tests to fail.
4903 Similarly, any message output by a library (e.g.
4904 Qt) would also cause failure.
4905 There are some messages that the check_load tests are instructed to ignore,
4906 which are stored in the file
4907 \begin_inset Flex Code
4910 \begin_layout Plain Layout
4911 development/autotests/filterCheckWarnings
4919 \begin_layout Standard
4920 Under cmake, the tests are labeled as 'load'.
4923 \begin_layout Subsubsection
4927 \begin_layout Standard
4928 Automated tests based on the "MonKey Testing" keytest program are enabled
4929 if the necessary dependencies are found and if the CMake flag
4930 \begin_inset Flex Code
4933 \begin_layout Plain Layout
4934 -DLYX_ENABLE_KEYTESTS=ON
4940 They are documented in the README document in
4941 \begin_inset Flex Code
4944 \begin_layout Plain Layout
4945 development/autotests
4950 subfolder of the \SpecialChar LyX
4951 source code distribution.
4954 \begin_layout Subsubsection
4958 \begin_layout Standard
4959 These tests combine lyx2lyx tests with check_load tests.
4960 They fail if either fails.
4963 \begin_layout Subsubsection
4967 \begin_layout Standard
4968 The URL tests are enabled with the
4969 \begin_inset Flex Code
4972 \begin_layout Plain Layout
4973 -DLYX_ENABLE_URLTESTS=ON
4978 CMake flag and are useful for finding broken links in our documentation
4980 If a URL test fails, to see which link in particular was reported as broken,
4982 \begin_inset Flex Code
4985 \begin_layout Plain Layout
4992 These tests are extremely fragile (e.g.
4993 a test can depend on your Internet connection) and a failed URL test should
4994 not be taken too seriously.
4995 URL tests are labeled as
5000 \begin_layout Paragraph
5004 \begin_layout Standard
5005 cmake is required to run the \SpecialChar LyX
5006 tests, running them is not implemented for
5010 \begin_layout Standard
5011 The appropriate commands are:
5014 \begin_layout Itemize
5020 \begin_inset Newline newline
5023 runs all tests with label
5028 \begin_layout Itemize
5031 ctest -R 'check_.*urls'
5034 \begin_inset Newline newline
5037 runs the tests 'check_accessible_urls'
5040 \begin_layout Standard
5041 Associated test results can be examined in ctest-log directory in files
5042 of the form 'LastFailed.*URLS.log'
5045 \begin_layout Section
5046 Development policies
5049 \begin_layout Standard
5050 This chapter lists some guidelines that should be followed.
5051 This list is not complete, and many guidelines are in separate chapters,
5053 \begin_inset Quotes eld
5056 When is an update of the .lyx file format number needed?
5057 \begin_inset Quotes erd
5061 \begin_inset CommandInset ref
5063 reference "sec:When-is-an"
5070 \begin_layout Subsection
5071 When to set a fixed milestone?
5074 \begin_layout Standard
5075 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5079 \begin_layout Enumerate
5080 Somebody is actively working on a fix.
5083 \begin_layout Enumerate
5084 The bug is so severe that it would block the release if it is not fixed.
5087 \begin_layout Standard
5088 If a bug is important, but nobody is working on it, and it is no showstopper,
5089 use a milestone like 2.1.x or 2.2.x.
5090 For all other bugs, do not set a milestone at all.
5093 \begin_layout Subsection
5094 Can we add rc entries in stable branch?
5097 \begin_layout Standard
5099 We are supposed to increase the prefs2prefs version number with such things.
5102 \begin_layout Section
5103 \begin_inset CommandInset label
5105 name "sec:Documentation-policies"
5109 Documentation policies
5112 \begin_layout Subsection
5116 \begin_layout Standard
5118 \begin_inset space ~
5121 rules in editing the docs:
5124 \begin_layout Enumerate
5125 \begin_inset CommandInset label
5127 name "enu:If-you-are"
5131 If you are not the maintainer of a doc file or a chapter/section, you MUST
5132 use change tracking so that the maintainer could review your changes
5135 \begin_layout Enumerate
5136 Respect the formatting of the document.
5137 The different files use different formatting styles.
5138 That is OK and has historic reasons nobody fully knows ;-).
5139 But it is important to be consistent within one file.
5142 \begin_layout Enumerate
5143 All changes you make to a file in one language MUST also go the file in
5144 the other actively maintained languages.
5145 Normally the maintainer does this for you, if you are the maintainer, you
5146 must do this by copying or changing the changed or added text to the other
5147 files so that the translators sees the blue underlined text and know what
5148 they have to translate and what was changed.
5151 \begin_layout Enumerate
5152 You MUST assure that the document is compilable as
5153 \begin_inset Quotes eld
5157 \begin_inset Quotes erd
5160 or the document's default output format after your changes.
5163 \begin_layout Enumerate
5164 All fixes (typos, compilation fixes, updates info etc.) go at first into
5165 the current GIT branch because the user should benefit from all fixes with
5166 every minor release.
5167 Feel free to commit directly to branch as long as you follow rule
5168 \begin_inset space ~
5172 \begin_inset CommandInset ref
5174 reference "enu:If-you-are"
5179 You can immediately commit to master as well.
5182 \begin_layout Enumerate
5183 \begin_inset CommandInset label
5185 name "enu:The-fileformat-of"
5189 The fileformat of a file must not be changed unless you document a new feature
5190 in LyX that requires a new fileformat.
5191 The reason for this rule is to keep it easy for the doc maintainers to
5192 port/backport changes to from master/branch.
5195 \begin_layout Standard
5196 The main documentation consists of these files:
5199 \begin_layout Description
5200 splash.lyx it is the first file you see after an installation.
5201 We assume that a new user sees this.
5202 It is therefore designed to be as simple as possible.
5203 Therefore please don't add any new formatting, only fix typos etc.
5204 Splash.lyx is up to date for \SpecialChar LyX
5205 2.1.x, currently maintained by Uwe Stöhr.
5208 \begin_layout Description
5209 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5211 It therefore uses a limited set of formatting.
5212 For example a standard document class.
5213 Since new users will first learn about the formatting possibilities of
5215 please keep this file that simple.
5216 Intro.lyx is up to date for \SpecialChar LyX
5217 2.1.x, currently maintained by Uwe Stöhr.
5220 \begin_layout Description
5221 Tutorial.lyx our tutorial.
5222 It must be always up to date.
5223 Normally there is nothing to add since we don't want to overwhelm new users
5224 with too much details.
5225 The will learn these details while using \SpecialChar LyX
5226 and we have special manuals.
5227 Tutorial.lyx is up to date for \SpecialChar LyX
5228 2.1.x, currently maintained by Uwe Stöhr.
5231 \begin_layout Description
5232 UserGuide.lyx our main user guide.
5233 It covers a mixture of basic and detailed information.
5234 Some information is also in the Math and EmbeddedObjects manual so that
5235 the UserGuide refers to these files.
5236 UserGuide.lyx is up to date for \SpecialChar LyX
5237 2.1.x, currently maintained by Uwe Stöhr.
5240 \begin_layout Description
5241 EmbeddedObjects.lyx a special manual to explain things like tables floats
5244 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5245 2.1.x, currently maintained by Uwe
5249 \begin_layout Description
5250 Math.lyx a special manual to explain everything regarding math in all detail.
5251 Math.lyx is up to date for \SpecialChar LyX
5252 2.1.x, currently maintained by Uwe Stöhr.
5255 \begin_layout Description
5256 Additional.lyx this manual covers information that would be too much detail
5257 for the UserGuide or would make the UserGuide uncompilable or only compilable
5258 when installing a lot of special \SpecialChar LaTeX
5260 What should be in the UserGuide or better in Additional is a matter of
5262 it is up to you to decide that.
5263 Additional.lyx is not completely up to date for \SpecialChar LyX
5266 \begin_inset space ~
5269 8 is up to date and currently maintained by Uwe Stöhr.
5270 It certainly needs a rewrite and update.
5271 For example many info in chapter
5272 \begin_inset space ~
5275 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5279 \begin_layout Description
5280 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5282 output formats, operating systems, languages etc.
5283 It is currently completely out of date and needs a major rewrite and update.
5284 If you do this please assure that your information are given for all OSes
5285 and \SpecialChar LaTeX
5286 distributions (meaning be as objective as possible).