1 #LyX 2.4 created this file. For more info see https://www.lyx.org/
5 \save_transient_properties true
6 \origin /systemlyxdir/doc/
8 \options BCOR8mm,captions=tableheading
9 \use_default_options false
13 \maintain_unincluded_children false
15 \language_package default
18 \font_roman "lmodern" "default"
19 \font_sans "lmss" "default"
20 \font_typewriter "lmtt" "default"
21 \font_math "auto" "auto"
22 \font_default_family default
23 \use_non_tex_fonts false
26 \font_sf_scale 100 100
27 \font_tt_scale 100 100
29 \use_dash_ligatures true
31 \default_output_format pdf2
33 \bibtex_command default
34 \index_command default
38 \pdf_title "LyX's Development manual"
39 \pdf_author "LyX Team"
40 \pdf_subject "LyX's development documentation"
41 \pdf_keywords "LyX, Documentation, Development"
43 \pdf_bookmarksnumbered true
44 \pdf_bookmarksopen true
45 \pdf_bookmarksopenlevel 1
50 \pdf_pdfusetitle false
51 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
54 \use_package amsmath 1
55 \use_package amssymb 1
58 \use_package mathdots 1
59 \use_package mathtools 1
61 \use_package stackrel 1
62 \use_package stmaryrd 1
63 \use_package undertilde 1
65 \cite_engine_type default
69 \paperorientation portrait
74 \notefontcolor #0000ff
81 \paragraph_separation indent
82 \paragraph_indentation default
84 \math_numbering_side default
89 \paperpagestyle headings
91 \tracking_changes false
101 Developing \SpecialChar LyX
105 \begin_layout Subtitle
110 by the \SpecialChar LyX
115 \begin_layout Plain Layout
117 If you have comments or error corrections, please send them to the \SpecialChar LyX
120 \begin_inset Flex Code
123 \begin_layout Plain Layout
124 <lyx-docs@lists.lyx.org>
137 \begin_layout Standard
138 \begin_inset CommandInset toc
139 LatexCommand tableofcontents
146 \begin_layout Section
150 \begin_layout Standard
151 This manual documents some aspects of \SpecialChar LyX
153 It is currently rather incomplete, but will hopefully be extended in the
155 Meanwhile, additional information can be found in the
156 \begin_inset Flex Code
159 \begin_layout Plain Layout
165 subfolder of the \SpecialChar LyX
166 source code distribution.
167 This document is not translated, since the development language of \SpecialChar LyX
170 If you just want to use \SpecialChar LyX
171 , then you don't need to read this manual.
172 However, if you want to learn more about how \SpecialChar LyX
173 is developed, or even want
174 to participate in \SpecialChar LyX
175 development, you may find some interesting information
179 \begin_layout Section
183 \begin_layout Standard
185 uses several custom file formats for configuration files and documents.
186 This chapter contains some background concerning these file formats.
187 Several file formats are also described in detail in the regular user documenta
191 \begin_layout Subsection
195 \begin_layout Subsection
196 When is an update of the .lyx file format number needed?
197 \begin_inset CommandInset label
199 name "sec:When-is-an"
206 \begin_layout Standard
207 When you are working on a new feature you may ask yourself whether it needs
208 an update of the .lyx file format number.
209 Whether an update is needed or not is not always obvious.
214 Whenever there is the danger that a previous version of LyX cannot open
215 a file using the new feature, a file format update is needed.
218 \begin_layout Standard
219 The file format change allows lyx2lyx rules to implement backwards compatibility.
220 Below you can find a list of reasons for file format updates with explanations:
223 \begin_layout Description
232 setting Whenever you introduce a new setting that is stored in the document
233 header, a file format update is needed.
236 \begin_layout Description
245 setting If a certain setting becomes obsolete and gets removed, a file format
249 \begin_layout Description
275 \begin_inset space \thinspace{}
282 \begin_layout Description
283 \paragraph_spacing single
296 package The reason for this is that there is no true ERT inset for math
297 formulas: Each command is parsed, and if a user happens to define a local
298 command with the same name as a command that triggers an automatic load
299 of a package, they need to be able to switch off the automatic loading
301 This switch is stored by the
302 \begin_inset Flex Code
305 \begin_layout Plain Layout
314 \begin_layout Description
319 language that is stored in
320 \begin_inset Flex Code
323 \begin_layout Plain Layout
333 \begin_inset Note Note
336 \begin_layout Plain Layout
337 This requirement is under discussion.
346 \begin_layout Description
351 inset Of course a new inset requires a file format update.
354 \begin_layout Description
359 style If a new style or inset layout is added to any layout file or module
360 shipped with \SpecialChar LyX
361 , then a new file format is needed in the master (development)
363 It is possible to backport new styles to the stable version without a file
366 \begin_inset CommandInset ref
368 reference "subsec:Backporting-new-styles"
372 for more information.
375 \begin_layout Description
380 style If a style or inset layout is removed in any layout file or module
381 shipped with \SpecialChar LyX
382 , a new file format is required.
385 \begin_layout Standard
390 layouts and modules do
394 require a file format update (changed 03/16, see
395 \begin_inset CommandInset ref
397 reference "subsec:New-layouts"
405 \begin_layout Standard
406 If you are still unsure, please ask on the development list.
409 \begin_layout Subsection
410 \begin_inset CommandInset label
412 name "subsec:update_lyx_files"
416 How to update the file format number of .lyx files
419 \begin_layout Standard
420 Once you come to the conclusion that a file format update is needed, you
421 should use the following procedure to perform the update:
424 \begin_layout Enumerate
425 Implement and test the new feature, including the reading and writing of
427 Note that any file produced at this stage does not use a valid format,
428 so do not use this version of \SpecialChar LyX
429 for working on any important documents.
432 \begin_layout Enumerate
433 \begin_inset CommandInset label
435 name "enu:Describe_format"
439 Describe the new format in
440 \begin_inset Flex Code
443 \begin_layout Plain Layout
452 \begin_layout Enumerate
453 Update the \SpecialChar LyX
454 file format number in
455 \begin_inset Flex Code
458 \begin_layout Plain Layout
467 \begin_layout Enumerate
468 \begin_inset CommandInset label
470 name "enu:Add-an-entry"
474 Add an entry to both format lists (for conversion and reversion) in
475 \begin_inset Newline newline
479 \begin_inset Flex Code
482 \begin_layout Plain Layout
483 lib/lyx2lyx/lyx_2_4.py
489 Add a conversion routine if needed (e.
490 \begin_inset space \thinspace{}
493 g., a new header setting always needs a conversion that adds the new setting,
494 but a new document language does not need one).
495 Add a reversion routine if needed.
497 \begin_inset Newline newline
500 While the conversion routine is required to produce a document that is equivalen
501 t to the old version, the requirements of the reversion are not that strict.
502 If possible, try to produce a proper reversion, using ERT if needed, but
503 for some features this might be too complicated.
504 In this case, the minimum requirement of the reversion routine is that
505 it produces a valid document which can be read by an older \SpecialChar LyX
507 If absolutely needed, even data loss is allowed for the reversion.
508 (In that case, you might want to add a LyX comment that indicates what
509 you have had to do, so the user is at least warned).
512 \begin_layout Enumerate
513 Since tex2lyx has several implicit file format dependencies caused by sharing
514 code with \SpecialChar LyX
515 , updating the file format of .lyx files produced by tex2lyx at
516 the same time as updating the main .lyx file format is strongly recommended.
517 Therefore, a compiler warning will be issued if the \SpecialChar LyX
518 and tex2lyx .lyx file
519 format numbers differ.
520 In many cases the tex2lyx update requires only the first and last item
525 \begin_layout Enumerate
526 Update the tex2lyx file format number in
527 \begin_inset Flex Code
530 \begin_layout Plain Layout
539 \begin_layout Enumerate
540 If the lyx2lyx conversion from the old to the new format is empty, or if
541 tex2lyx does not yet output the changed feature, you do not need any further
543 Otherwise, search for the changed feature in tex2lyx, and adjust the output
544 according to the lyx2lyx changes.
547 \begin_layout Enumerate
548 Update the tex2lyx test references as described in
549 \begin_inset CommandInset ref
550 LatexCommand formatted
551 reference "sec:Updating-test-references"
559 \begin_layout Enumerate
560 If you did not implement full tex2lyx support for the new feature, add a
562 \begin_inset Flex Code
565 \begin_layout Plain Layout
571 describing the missing bits.
572 Note that it is perfectly fine if you do not add full tex2lyx support for
573 a new feature: The updating recommendation above is only issued for the
574 syntax of the produced .lyx file.
575 It is no problem if some features supported by \SpecialChar LyX
576 are still output as ERT
578 The problems in the past that resulted in the update recommendation were
579 related to mixed version syntax, not ERT.
582 \begin_layout Enumerate
583 It would be nice if you could create a .lyx test file which contains instances
584 of all changed or added features.
585 This could then be used to test lyx2lyx and tex2lyx.
586 Test samples are collected under the corresponding subdirectories of
593 \begin_layout Enumerate
594 \begin_inset CommandInset label
596 name "enu:updatefiles"
600 Test your lyx2lyx code by updating LyX's .lyx documentation files to the
602 The developer who makes the change knows best what changes to expect when
603 inspecting the resulting diff.
604 Because of this, you might be able to catch a bug in the lyx2lyx code that
605 updates the format just by taking a quick scan through the large diff that
607 \begin_inset Note Note
610 \begin_layout Plain Layout
611 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
612 see which layout update made an unexpected change by looking at the git
613 log of a .lyx file that suffers the problem.
618 To do this, first make sure that there are no changes to the git repository
619 that you will not want to commit (this is needed because it will be convenient
620 to commit with the command
621 \begin_inset Flex Code
624 \begin_layout Plain Layout
631 Then run the following command in the root folder of the source:
632 \begin_inset Flex Code
635 \begin_layout Plain Layout
636 python development/tools/updatedocs.py
642 Look at the resulting changes using the command
643 \begin_inset Flex Code
646 \begin_layout Plain Layout
653 If anything looks surprising, please investigate.
654 Keep in mind that the case of
655 \begin_inset Flex Code
658 \begin_layout Plain Layout
664 is special, because it is first generated with
665 \begin_inset Flex Code
668 \begin_layout Plain Layout
674 before being converted to the latest format.
675 \begin_inset Newline newline
679 \begin_inset Note Greyedout
682 \begin_layout Plain Layout
687 Only commit file format changes in the doc files if these files are using
688 the new feature of the new file format.
694 \begin_inset CommandInset ref
696 reference "enu:The-fileformat-of"
700 of the documentation policies described in sec.
705 \begin_inset CommandInset ref
707 reference "sec:Documentation-policies"
719 \begin_layout Enumerate
720 Finally, commit using
721 \begin_inset Flex Code
724 \begin_layout Plain Layout
733 \begin_layout Subsection
734 Updating the file format number of layout files
737 \begin_layout Standard
738 The procedure for updating the layout files is similar to that in step
739 \begin_inset CommandInset ref
741 reference "enu:updatefiles"
746 \begin_inset CommandInset ref
748 reference "subsec:update_lyx_files"
754 \begin_inset Flex Code
757 \begin_layout Plain Layout
758 python development/tools/updatelayouts.py
764 \begin_inset Flex Code
767 \begin_layout Plain Layout
776 \begin_layout Standard
777 Note that we do not automatically update any local layout used in the
778 \begin_inset Flex Code
781 \begin_layout Plain Layout
787 files shipped with \SpecialChar LyX
788 because users would then not be able to export to older
790 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
791 to open the file in \SpecialChar LyX
792 2.1.x, there would be an error because the file would
793 contain a local layout whose format is too new.
794 The root reason for this is that we do not support converting layouts to
795 older layout formats, as we do for the
796 \begin_inset Flex Code
799 \begin_layout Plain Layout
808 \begin_layout Subsection
809 Updating the file format number of bind/ui files
812 \begin_layout Standard
813 A change to the functionality of existing LFUNs can require a conversion
815 \begin_inset Flex Code
818 \begin_layout Plain Layout
825 \begin_inset Flex Code
828 \begin_layout Plain Layout
834 files, and therefore an increment of the LFUN format, as well as a conversion
836 \begin_inset Flex Code
839 \begin_layout Plain Layout
846 The latter cannot be done automatically and also requires an update of
850 \begin_inset space \space{}
853 of someone who might have made a set of \SpecialChar LyX
854 teaching manuals for use in their
859 \begin_layout Plain Layout
860 \begin_inset Flex URL
863 \begin_layout Plain Layout
865 https://www.lyx.org/trac/ticket/9794
878 \begin_layout Standard
879 To update the LFUN format:
882 \begin_layout Enumerate
883 Increment the LFUN file format number in
884 \begin_inset Flex Code
887 \begin_layout Plain Layout
896 \begin_layout Enumerate
897 Implement the LFUN conversion in
898 \begin_inset Flex Code
901 \begin_layout Plain Layout
902 lib/scripts/prefs2prefs_lfuns.py
910 \begin_layout Enumerate
912 \begin_inset CommandInset ref
914 reference "enu:updatefiles"
919 \begin_inset CommandInset ref
921 reference "subsec:update_lyx_files"
926 \begin_inset Flex Code
929 \begin_layout Plain Layout
935 command, use this command:
936 \begin_inset Flex Code
939 \begin_layout Plain Layout
940 bash development/tools/updatelfuns.sh
947 \begin_inset Note Note
950 \begin_layout Plain Layout
951 This file should really be converted to python.
959 \begin_layout Enumerate
960 Update Info insets in
961 \begin_inset Flex Code
964 \begin_layout Plain Layout
971 To do so, increment the \SpecialChar LyX
972 format and proceed as in
973 \begin_inset CommandInset ref
975 reference "subsec:update_lyx_files"
980 \begin_inset CommandInset ref
982 reference "enu:Describe_format"
987 \begin_inset CommandInset ref
989 reference "enu:updatefiles"
994 In the lyx2lyx implementation (step
995 \begin_inset CommandInset ref
997 reference "enu:Add-an-entry"
1001 ), implement a conversion similar to the one in
1002 \begin_inset Flex Code
1005 \begin_layout Plain Layout
1006 prefs2prefs_lfuns.py
1011 above, as well as a corresponding reversion; for this one can use
1012 \begin_inset Flex Code
1015 \begin_layout Plain Layout
1022 \begin_inset Flex Code
1025 \begin_layout Plain Layout
1026 lib/lyx2lyx/lyx2lyx_tools.py
1035 \begin_layout Subsection
1036 Backporting new styles to the stable version
1037 \begin_inset CommandInset label
1039 name "subsec:Backporting-new-styles"
1046 \begin_layout Standard
1047 Starting with the stable \SpecialChar LyX
1048 2.1 branch, there is a mechanism in place to backport
1049 new styles to the stable version without the need to update the file format.
1050 The basic idea is that the new style definition is automatically copied
1051 to the document preamble so that it can even be used by older minor versions
1052 that did not yet include the style.
1053 To backport a new style to the stable version, the following steps are
1057 \begin_layout Enumerate
1059 \begin_inset Flex Code
1062 \begin_layout Plain Layout
1068 to the style definition in the development version.
1071 \begin_layout Enumerate
1072 Copy the style definition to the stable version, but use
1073 \begin_inset Flex Code
1076 \begin_layout Plain Layout
1083 If needed adjust the format to the one used by the stable version (see
1084 the customization manual for details of the layout file format).
1087 \begin_layout Enumerate
1088 For each update of the style in a later stable version, increase the argument
1090 \begin_inset Flex Code
1093 \begin_layout Plain Layout
1100 (In the stable version, the development version should not be touched.)
1103 \begin_layout Standard
1104 For details about the
1105 \begin_inset Flex Code
1108 \begin_layout Plain Layout
1114 flag see the customization manual.
1116 \begin_inset Flex Code
1119 \begin_layout Plain Layout
1125 support is needed for backported styles: Since the style of the development
1126 version has an infinite version number, it will always be used.
1127 Furthermore, since its version number is less than one, the style will
1128 not be written anymore to the document header for files saved by the new
1132 \begin_layout Section
1133 New layouts and modules
1136 \begin_layout Subsection
1137 \begin_inset CommandInset label
1139 name "subsec:New-layouts"
1146 \begin_layout Standard
1147 Adding a new layout file to the \SpecialChar LyX
1149 \begin_inset Quotes eld
1152 officially supported
1153 \begin_inset Quotes erd
1157 You should therefore think carefully about whether you really want to do
1158 this and discuss it on lyx-devel, since you will need to be prepared to
1159 update and fix the layout if necessary.
1160 If the layout is experimental or for a rarely used document class, then
1161 it may be better to add it to the relevant portion of the \SpecialChar LyX
1165 \begin_inset CommandInset href
1167 target "https://wiki.lyx.org/Layouts/Layouts"
1175 \begin_layout Standard
1176 In older versions of this document, it was stated that new layout files
1177 require a file format change.
1178 After some discussion, it was decided that this is not needed.
1182 \begin_layout Plain Layout
1184 \begin_inset CommandInset href
1186 name "the thread “Proposal for a guide on updating layouts”"
1187 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1201 For reference, here are the arguments on each side
1205 \begin_layout Description
1207 \begin_inset Quotes eld
1210 New layout files are a file format change
1211 \begin_inset Quotes erd
1217 \begin_layout Itemize
1218 All documents produced by 2.2.
1219 \begin_inset Formula $x$
1222 can always be edited and exported even if
1223 \begin_inset Formula $x$
1227 This is important for people using different machines, or exchanging work
1231 \begin_layout Description
1233 \begin_inset Quotes eld
1236 New layout files are not a file format change
1237 \begin_inset Quotes erd
1243 \begin_layout Itemize
1244 No new LaTeX classes can be supported in a stable version, and stable versions
1245 have a typical lifetime of 2–3 years.
1248 \begin_layout Itemize
1249 We have the same situation already with custom layout files: If a document
1250 using a custom layout file is moved between machines or people, then the
1251 layout file needs to be exchanged as well.
1252 If that is not done, then we have a fallback implemented so that such documents
1253 can still be edited, but not exported, and the user gets a warning.
1257 \begin_layout Itemize
1258 The lyx2lyx script cannot do anything useful in such a case.
1262 \begin_layout Standard
1263 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1265 then, you should do the following:
1268 \begin_layout Enumerate
1269 Put your new layout file in
1270 \begin_inset Flex Code
1273 \begin_layout Plain Layout
1280 \begin_inset Flex Code
1283 \begin_layout Plain Layout
1284 git add lib/layouts/newlayout.layout
1289 ) so that it will be committed.
1292 \begin_layout Enumerate
1294 \begin_inset Flex Code
1297 \begin_layout Plain Layout
1303 , so that the new layout actually gets installed.
1306 \begin_layout Enumerate
1308 \begin_inset Flex Code
1311 \begin_layout Plain Layout
1312 lib/doc/LaTeXConfig.lyx
1317 containing in particular a line like
1325 \begin_layout Standard
1326 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1327 \begin_inset Flex Code
1330 \begin_layout Plain Layout
1331 info-insert textclass <name>
1337 This inset will automatically display a boxed
1338 \begin_inset Quotes eld
1342 \begin_inset Quotes erd
1346 \begin_inset Quotes eld
1350 \begin_inset Quotes erd
1353 depending on the availability of the package.
1357 \begin_layout Enumerate
1358 A template or example is strongly encouraged (but not necessarily required).
1359 It is also possible to provide both.
1361 \begin_inset Flex Code
1364 \begin_layout Plain Layout
1371 \begin_inset Flex Code
1374 \begin_layout Plain Layout
1383 \begin_layout Enumerate
1384 Reconfigure \SpecialChar LyX
1388 \begin_layout Enumerate
1389 Ensure the autotests for the new layout pass (see
1390 \begin_inset CommandInset ref
1392 reference "par:when-to-run-an-export-test"
1399 \begin_layout Subsection
1403 \begin_layout Standard
1404 Adding a new module is very similar to adding a new layout.
1405 Therefore, the previous section applies to new modules as well, with two
1409 \begin_layout Enumerate
1410 You only need to add an entry to
1411 \begin_inset Flex Code
1414 \begin_layout Plain Layout
1415 lib/doc/LaTeXConfig.lyx
1420 if the module requires a LaTeX package.
1421 In that case, the command for entering the InsetInfo is:
1422 \begin_inset Flex Code
1425 \begin_layout Plain Layout
1426 info-insert package <name>
1434 \begin_layout Enumerate
1435 Modules do not need a template, only an example, which is strongly encouraged
1436 but not necessarily required.
1439 \begin_layout Subsection
1440 Layouts for document classes with incompatible versions
1443 \begin_layout Standard
1444 \begin_inset Note Greyedout
1447 \begin_layout Description
1448 Note: This section is currently only a proposal under discussion.
1449 Please correct/amend as suited.
1450 Remove this note once a consensus is found.
1453 \begin_layout Plain Layout
1455 \begin_inset Quotes eld
1458 Proposal for a guide on updating layouts
1459 \begin_inset Quotes erd
1462 for details and background
1465 \begin_layout Plain Layout
1466 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1474 \begin_layout Standard
1475 Every now and then, there are changes to LaTeX document classes that break
1476 backwards compatibility.
1480 \begin_layout Plain Layout
1481 Uwe has suggested we implement automatic detection of changes in class files.
1482 This could be done by running a script every month that checks if a document
1483 class was changed at CTAN and at the homepages of the scientific journals.
1484 If it reports a change, we can check if our template and layout file are
1485 still usable with the changed document class.
1486 (This is different from the autotests insofar, as this would also catch
1487 changes that do not result in compilation errors.)
1492 Reasons can be a new name for the
1493 \begin_inset Flex Code
1496 \begin_layout Plain Layout
1502 file, removed \SpecialChar LaTeX
1504 How should this best be handled in \SpecialChar LyX
1508 \begin_layout Standard
1509 The idea is to support the new version with a new \SpecialChar LyX
1513 \begin_layout Itemize
1514 Existing documents can still be opened in \SpecialChar LyX
1515 and will continue to work on
1516 systems where the old version is still installed.
1520 \begin_layout Itemize
1521 With differently named
1522 \begin_inset Flex Code
1525 \begin_layout Plain Layout
1531 files, \SpecialChar LyX
1532 can check for the availability of the particular version and reflect
1534 Different document class versions with the same file name are currently
1535 (2.2.x) not detected by the configuration script.
1536 This is planned for 2.3.
1540 \begin_layout Plain Layout
1541 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1544 \begin_layout Plain Layout
1545 However, what we really need is version detection for the configuration,
1546 so that the user can be warned if the required class file has the wrong
1548 (If the class file keeps the name over the version change, only one of
1549 the two layout files generates compilable documents.)
1552 \begin_layout Plain Layout
1553 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1562 \begin_layout Itemize
1563 The new layout can be added both to the master and the stable branches,
1564 in accord with the policy discussed in
1565 \begin_inset CommandInset ref
1566 LatexCommand formatted
1567 reference "subsec:New-layouts"
1572 No lyx2lyx conversion is then required when a new major version is released.
1575 \begin_layout Standard
1576 The user can move an existing document to the new version simply by selecting
1577 a new document class.
1578 This step is well supported by \SpecialChar LyX
1579 , with established methods for handling
1580 unsupported styles and other changes.
1581 This way, no lyx2lyx code is required.
1584 \begin_layout Standard
1585 The steps to support a new version of an existing document class are thus:
1588 \begin_layout Itemize
1589 Create a new layout file including the upstream version in the name (avoid
1590 special characters like spaces and dots), e.g.
1592 \begin_inset Flex Code
1595 \begin_layout Plain Layout
1596 acmsiggraph-v0-92.layout
1604 \begin_layout Itemize
1605 Include the name of the
1606 \begin_inset Flex Code
1609 \begin_layout Plain Layout
1615 file as an optional argument in the
1616 \begin_inset Flex Code
1619 \begin_layout Plain Layout
1627 line and include the version number in the GUI name:
1628 \begin_inset Newline newline
1632 \begin_inset Flex Code
1635 \begin_layout Plain Layout
1638 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1639 \begin_inset space ~
1650 \begin_layout Itemize
1651 Update the GUI name in the old layout file (whose name should not be changed),
1653 \begin_inset Newline newline
1657 \begin_inset Flex Code
1660 \begin_layout Plain Layout
1663 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1664 \begin_inset space ~
1675 \begin_layout Itemize
1676 To avoid duplicate definitions, the new layout can
1677 \begin_inset Flex Code
1680 \begin_layout Plain Layout
1686 the old layout file and add\SpecialChar breakableslash
1687 remove\SpecialChar breakableslash
1688 obsolete\SpecialChar breakableslash
1689 modify settings and styles (similar
1691 \begin_inset Flex Code
1694 \begin_layout Plain Layout
1704 \begin_layout Standard
1705 It may be tempting to let the new layout be the
1706 \begin_inset Quotes eld
1710 \begin_inset Quotes erd
1713 and have the old layout import it.
1714 However, this should not be done because any changes to the new layout
1715 would need undo steps in the importing old layout.
1719 \begin_layout Itemize
1720 If the new LaTeX document class obsoletes the old one, update the example
1721 and template files to use the new layout.
1722 Add a note about the changes (preferably with a pointer to the documentation
1727 \begin_layout Standard
1728 This way, new documents based on the template or example will use the up-to-date
1729 document class version.
1733 \begin_layout Standard
1734 \begin_inset Newpage newpage
1740 \begin_layout Section
1744 \begin_layout Standard
1745 Automated tests are an important tool to detect bugs and regressions in
1746 software development.
1747 Some projects like gcc even require each bug fix to be accompanied by a
1748 test case for the automatic test suite, that would detect this bug.
1749 Testing interactive features automatically is of course very hard, but
1750 core functionality like document import and export can be tested quite
1751 easily, and some tests of this kind exist.
1754 \begin_layout Subsection
1758 \begin_layout Standard
1759 There are attempts to set up a suite of unit tests for LyX.
1762 \begin_layout Standard
1763 TODO: describe what is done and what is still to do.
1766 \begin_layout Subsection
1770 \begin_layout Standard
1771 The tex2lyx tests are located in the
1772 \begin_inset Flex Code
1775 \begin_layout Plain Layout
1781 subfolder of the \SpecialChar LyX
1782 source code distribution.
1783 The actual testing is performed by the simple python script
1784 \begin_inset Flex Code
1787 \begin_layout Plain Layout
1788 src/tex2lyx/test/runtests.py
1794 Each test consists of two files:
1795 \begin_inset Flex Code
1798 \begin_layout Plain Layout
1804 contains the \SpecialChar LaTeX
1805 code that should be tested.
1807 \begin_inset Flex Code
1810 \begin_layout Plain Layout
1816 contains the expected output of tex2lyx.
1817 When a test is run, the actual produced output is compared with the stored
1819 The test passes if both are identical.
1820 The test machinery is also able to generate a file
1821 \begin_inset Flex Code
1824 \begin_layout Plain Layout
1830 by exporting the produced .lyx file with \SpecialChar LyX
1832 This may be useful for roundtrip comparisons.
1835 \begin_layout Subsubsection
1839 \begin_layout Standard
1840 The tex2lyx tests can be run in several ways.
1842 \begin_inset Flex Code
1845 \begin_layout Plain Layout
1851 subfolder of the build directory, the commands
1852 \begin_inset Flex Code
1855 \begin_layout Plain Layout
1861 (cmake, all platforms),
1862 \begin_inset Flex Code
1865 \begin_layout Plain Layout
1871 (cmake, when using a make based build system and not MSVC) or
1872 \begin_inset Flex Code
1875 \begin_layout Plain Layout
1881 (autotools) will run the tex2lyx tests.
1882 Alternatively, in the root of the build directory, the command
1883 \begin_inset Flex Code
1886 \begin_layout Plain Layout
1892 runs all tests whose names match the regex
1893 \begin_inset Quotes eld
1897 \begin_inset Quotes erd
1901 Another way to run the tex2lyx tests in the root build directory is to
1902 instead use the command
1903 \begin_inset Flex Code
1906 \begin_layout Plain Layout
1907 ctest -L '(cmplyx|roundtrip)'
1912 , which runs all tests categorized with the label
1913 \begin_inset Quotes eld
1917 \begin_inset Quotes erd
1921 \begin_inset Quotes eld
1925 \begin_inset Quotes erd
1929 If a test fails, the differences between the expected and actual results
1930 are output in unified diff format.
1933 \begin_layout Subsubsection
1934 Updating test references
1935 \begin_inset CommandInset label
1937 name "sec:Updating-test-references"
1944 \begin_layout Standard
1945 In some cases a changed tex2lyx output is not a test failure, but wanted,
1947 \begin_inset space \thinspace{}
1951 \begin_inset space \space{}
1954 if a tex2lyx bug was fixed, or a new feature was added.
1955 In these cases the stored references need to be updated.
1956 To do so if using autotools, call
1957 \begin_inset Flex Code
1960 \begin_layout Plain Layout
1967 \begin_inset Flex Code
1970 \begin_layout Plain Layout
1976 subdirectory of the build directory.
1977 If instead using CMake, call
1978 \begin_inset Flex Code
1981 \begin_layout Plain Layout
1982 make updatetex2lyxtests
1987 in the build directory or in the
1988 \begin_inset Flex Code
1991 \begin_layout Plain Layout
1997 subdirectory of the build directory.
2001 \begin_layout Plain Layout
2002 Note that this is a case where a make target in the build directory can
2003 affect the source directory, which might not be advisable.
2008 On Windows do the following:
2011 \begin_layout Itemize
2012 Assure that the path to the python.exe is in your system PATH variable.
2015 \begin_layout Itemize
2016 Double-click on the file
2017 \begin_inset Flex Code
2020 \begin_layout Plain Layout
2021 updatetex2lyxtests.vcxproj
2026 in the build directory or in the
2027 \begin_inset Flex Code
2030 \begin_layout Plain Layout
2036 subdirectory of your build directory.
2039 \begin_layout Itemize
2040 In the appearing MSVC program assure that you build the
2044 version, then right-click on the project
2048 in the project explorer and choose then
2051 \begin_inset space ~
2054 Only\SpecialChar menuseparator
2056 \begin_inset space ~
2064 \begin_layout Standard
2065 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2067 Please examine the changed output carefully before committing the changed
2068 files to the repository: Since the test machinery does not do a roundtrip
2070 \begin_inset Formula $\Rightarrow$
2074 \begin_inset Formula $\Rightarrow$
2077 .tex, and does not compare the produced dvi or pdf output, it assumes that
2078 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2080 There is only one chance to detect wrong output: before committing a new
2082 Once it is committed, it is quite difficult to verify whether it is correct.
2085 \begin_layout Standard
2090 update the test references by opening them with \SpecialChar LyX
2091 or directly running lyx2lyx
2093 This would not work, since lyx2lyx and \SpecialChar LyX
2094 produce slightly different files
2095 regarding insignificant whitespace and line breaks.
2098 \begin_layout Subsubsection
2102 \begin_layout Standard
2103 In many cases tests for new features may be added to one of the existing
2104 test files, but sometimes this is not possible or not wanted.
2105 Then a new test file needs to be added:
2108 \begin_layout Enumerate
2110 \begin_inset Flex Code
2113 \begin_layout Plain Layout
2114 src/tex2lyx/test/<test name>.tex
2119 and run tex2lyx in roundtrip mode to produce the file
2120 \begin_inset Flex Code
2123 \begin_layout Plain Layout
2124 src/tex2lyx/test/<test name>.lyx.lyx
2130 This file will be the new reference.
2133 \begin_layout Enumerate
2134 Once you confirmed that the tex2lyx output is correct, add the new files
2135 to the corresponding lists in
2136 \begin_inset Flex Code
2139 \begin_layout Plain Layout
2140 src/tex2lyx/test/runtests.py
2146 \begin_inset Flex Code
2149 \begin_layout Plain Layout
2150 src/tex2lyx/Makefile.am
2156 \begin_inset Flex Code
2159 \begin_layout Plain Layout
2160 src/tex2lyx/test/CMakeLists.txt
2168 \begin_layout Enumerate
2169 Commit the changes to the repository, or send a patch to the development
2170 list and ask for committing if you do not have commit rights.
2173 \begin_layout Subsection
2174 ctest automatic tests
2177 \begin_layout Standard
2178 Some tests are located in the
2179 \begin_inset Flex Code
2182 \begin_layout Plain Layout
2183 development/autotests/
2188 subfolder of the \SpecialChar LyX
2189 source code distribution.
2194 \begin_layout Plain Layout
2195 The README document in this folder only describes the
2196 \begin_inset Quotes eld
2200 \begin_inset Quotes erd
2203 subset of autotests!
2211 \begin_layout Standard
2212 These tests can be run by the commands
2213 \begin_inset Flex Code
2216 \begin_layout Plain Layout
2226 (all platforms) or (when using a make based build system and not MSVC)
2228 \begin_inset Flex Code
2231 \begin_layout Plain Layout
2238 \begin_inset Flex Code
2241 \begin_layout Plain Layout
2252 The test logs are written to the
2253 \begin_inset Flex Code
2256 \begin_layout Plain Layout
2270 \begin_layout Subsubsection
2274 \begin_layout Standard
2275 The export tests are integration tests.
2276 They take longer to run and are more likely to break than the tex2lyx tests.
2277 Nevertheless, they have caught many regressions and without a better alternativ
2278 e it is important to keep them up-to-date and understand how they work.
2281 \begin_layout Standard
2283 \begin_inset Quotes eld
2287 \begin_inset Quotes erd
2290 documentation, template, and example documents.
2291 In addition, there are a number of dedicated sample documents in the
2292 \begin_inset Flex Code
2295 \begin_layout Plain Layout
2301 subfolder of the \SpecialChar LyX
2302 source code distribution.
2303 All samples are (after copying and eventual processing by scripts) exported
2304 to various output formats via the
2305 \begin_inset Flex Code
2308 \begin_layout Plain Layout
2314 command line option.
2315 The tests checks for errors reported by LyX.
2316 (However, error-free export is no guarantee for an error-free output document.)
2319 \begin_layout Paragraph
2320 \begin_inset CommandInset label
2322 name "par:when-to-run-an-export-test"
2326 Expectations of LyX developers
2329 \begin_layout Standard
2330 Because the export tests are integration tests and take a long time to run,
2331 LyX developers are rarely expected to run all of the tests.
2332 Here are some good practices to follow by developers:
2335 \begin_layout Itemize
2336 When making a non-trivial change to a .layout file, run the export and layout
2337 tests corresponding with that .layout file.
2340 \begin_layout Itemize
2341 When making non-trivial changes to a .lyx file, run the export tests correspondin
2342 g to that .lyx file.
2347 \begin_layout Plain Layout
2348 This rule is due to revision.
2352 \begin_layout Plain Layout
2353 There is an objection from the documentation maintainer that working on
2354 the documentation must not be complicated by having to consider non-standard
2358 \begin_layout Itemize
2359 successful compiling/testing an edited documentation file with pdflatex
2360 suffices to ensure it can be commited, not tests with other exports are
2364 \begin_layout Plain Layout
2365 If sudden failures with other exports due to “half-tested” documentation
2366 updates are a problem for the test maintainer, the test suite should use
2370 \begin_layout Itemize
2371 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2374 \begin_layout Itemize
2375 updated regularely (but on a time chosen by the test suite maintainer) from
2376 the originals in lib/doc/
2379 \begin_layout Plain Layout
2383 \begin_layout Itemize
2384 no test will fail due to ongoing work on documentation,
2387 \begin_layout Itemize
2388 the documentation is still tested in full (with some delay),
2391 \begin_layout Itemize
2392 failures with non-default export can be examined and handled accordingly
2393 in one run with the cache update,
2396 \begin_layout Itemize
2397 “interesting failures” (like the nested-language+polyglossia problem in
2398 es/Customization can be separated and moved into dedicated test samples.
2406 \begin_layout Itemize
2407 When making non-trivial changes to LyX's \SpecialChar LaTeX
2409 touching the encoding code or package handling code that you expect will
2410 change the exported \SpecialChar LaTeX
2415 \begin_layout Standard
2416 \paragraph_spacing single
2417 Consider running all of the export tests before and after your change.
2418 If there are differences, please reconcile these (i.e.
2419 fix the bug or fix the tests)
2424 Ask for help if you're not sure what to.
2427 \begin_layout Standard
2428 If you do not want to run the tests,
2431 \begin_layout Itemize
2432 post the patch on the list and others will run the tests and eventually
2436 \begin_layout Itemize
2437 commit, but be prepared to fix eventually arising problems or to revert
2438 the commit if there is no easy fix.
2442 \begin_layout Itemize
2443 Understand how to interpret test failures.
2444 If your commit is found to have broken a test, you should be able to interpret
2445 the test results when made aware of them.
2447 \begin_inset CommandInset ref
2449 reference "subsec:Interpreting-export-tests"
2456 \begin_layout Paragraph
2457 \begin_inset CommandInset label
2459 name "par:export-test-output-formats"
2466 \begin_layout Standard
2467 The following output formats are currently tested for each sample document
2469 \begin_inset CommandInset ref
2471 reference "par:Export-test-filtering"
2478 \begin_layout Labeling
2479 \labelwidthstring 00.00.0000
2484 \begin_layout Labeling
2485 \labelwidthstring 00.00.0000
2486 lyx16 LyX 1.6 file format (lyx2lyx)
2489 \begin_layout Labeling
2490 \labelwidthstring 00.00.0000
2491 lyx21 LyX 2.1 file format (lyx2lyx)
2494 \begin_layout Labeling
2495 \labelwidthstring 00.00.0000
2496 xhtml LyXHTML (native LyX HTML export)
2500 \begin_layout Labeling
2501 \labelwidthstring 00.00.0000
2503 \begin_inset space ~
2507 \begin_inset space ~
2514 \begin_layout Labeling
2515 \labelwidthstring pdf5msystemFM
2516 dvi DVI (8-bit latex)
2519 \begin_layout Labeling
2520 \labelwidthstring pdf5msystemFM
2521 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2524 \begin_layout Labeling
2525 \labelwidthstring pdf5msystemFM
2526 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2529 \begin_layout Labeling
2530 \labelwidthstring pdf5msystemFM
2534 \begin_layout Labeling
2535 \labelwidthstring pdf5msystemFM
2536 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2539 \begin_layout Labeling
2540 \labelwidthstring pdf5msystemFM
2541 pdf4_systemF PDF (XeTeX with Unicode fonts)
2544 \begin_layout Labeling
2545 \labelwidthstring pdf5msystemFM
2546 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2549 \begin_layout Labeling
2550 \labelwidthstring pdf5msystemFM
2551 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2555 \begin_layout Labeling
2556 \labelwidthstring 00.00.0000
2558 \begin_inset space ~
2562 \begin_inset space ~
2566 \begin_inset space ~
2570 \begin_inset space ~
2577 \begin_layout Labeling
2578 \labelwidthstring pdf5msystemFM
2579 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2582 \begin_layout Labeling
2583 \labelwidthstring pdf5msystemFM
2584 pdf3 DVI -> PDF (dvipdfm)
2588 \begin_layout Labeling
2589 \labelwidthstring 00.00.0000
2591 \begin_inset space ~
2594 tested: (or only if set as default output format in the document source)
2598 \begin_layout Labeling
2599 \labelwidthstring pdf5msystemFM
2603 \begin_layout Labeling
2604 \labelwidthstring pdf5msystemFM
2605 luatex LaTeX (LuaTeX)
2608 \begin_layout Labeling
2609 \labelwidthstring pdf5msystemFM
2610 dviluatex LaTeX (dviluatex)
2613 \begin_layout Labeling
2614 \labelwidthstring pdf5msystemFM
2615 pdflatex LaTeX (pdflatex)
2618 \begin_layout Labeling
2619 \labelwidthstring pdf5msystemFM
2620 platex LaTeX (pLaTeX)
2623 \begin_layout Labeling
2624 \labelwidthstring pdf5msystemFM
2628 \begin_layout Labeling
2629 \labelwidthstring pdf5msystemFM
2630 eps3 EPS (encapsulated Postscript) (cropped)
2633 \begin_layout Labeling
2634 \labelwidthstring pdf5msystemFM
2635 ps DVI -> Postscript (dvips)
2638 \begin_layout Labeling
2639 \labelwidthstring pdf5msystemFM
2643 \begin_layout Labeling
2644 \labelwidthstring pdf5msystemFM
2645 text (nor text2, ..., text4)
2648 \begin_layout Labeling
2649 \labelwidthstring pdf5msystemFM
2653 \begin_layout Labeling
2654 \labelwidthstring pdf5msystemFM
2658 \begin_layout Labeling
2659 \labelwidthstring pdf5msystemFM
2663 \begin_layout Labeling
2664 \labelwidthstring pdf5msystemFM
2669 \begin_layout Paragraph
2670 \begin_inset CommandInset label
2672 name "par:Configuring-ctests"
2676 Configuring the tests
2679 \begin_layout Standard
2680 To enable the export autotests, add the
2681 \begin_inset Flex Code
2684 \begin_layout Plain Layout
2685 -DLYX_ENABLE_EXPORT_TESTS=ON
2694 \begin_layout Standard
2695 \begin_inset Flex Code
2698 \begin_layout Plain Layout
2699 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2707 \begin_layout Standard
2709 This flag will increase the time for the cmake command by several seconds,
2710 mainly because of the process of inverting tests (see Section
2711 \begin_inset CommandInset ref
2713 reference "subsec:Interpreting-export-tests"
2720 \begin_layout Paragraph
2721 \begin_inset CommandInset label
2723 name "par:ctest-options"
2730 \begin_layout Standard
2731 To run all tests, in the build directory simply run the command
2732 \begin_inset Flex Code
2735 \begin_layout Plain Layout
2742 A full, up-to-date TeXLive installation is recommended to run the tests.
2743 Otherwise, some tests will fail.
2744 Tests with additional requirements are labeled
2745 \begin_inset Quotes eld
2748 unreliable:nonstandard
2749 \begin_inset Quotes erd
2756 \begin_layout Standard
2757 To run only some of the tests, use command line options (see examples below):
2760 \begin_layout Labeling
2761 \labelwidthstring -R
2762 \begin_inset Flex Code
2765 \begin_layout Plain Layout
2771 Run only the tests whose names match the given regular expression.
2774 \begin_layout Labeling
2775 \labelwidthstring -R
2776 \begin_inset Flex Code
2779 \begin_layout Plain Layout
2785 Run only the tests whose labels match the given regular expression.
2786 A test may have more that one label.
2790 \begin_layout Labeling
2791 \labelwidthstring -R
2792 \begin_inset Flex Code
2795 \begin_layout Plain Layout
2801 Exclude the tests whose names match the given regular expression.
2804 \begin_layout Labeling
2805 \labelwidthstring -R
2806 \begin_inset Flex Code
2809 \begin_layout Plain Layout
2815 Exclude the tests whose labels match the given regular expression.
2816 Cannot be combined with
2817 \begin_inset Flex Code
2820 \begin_layout Plain Layout
2829 \begin_layout Standard
2830 The following options help to find good selection patterns:
2833 \begin_layout Labeling
2834 \labelwidthstring -R
2835 \begin_inset Flex Code
2838 \begin_layout Plain Layout
2844 List the tests that would be run but not actually run them.
2849 \begin_layout Standard
2850 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2851 to know how many tests there are or whether your
2852 \begin_inset Flex Code
2855 \begin_layout Plain Layout
2861 regular expression did what you expected.
2865 \begin_layout Labeling
2866 \labelwidthstring -R
2867 \begin_inset Flex Code
2870 \begin_layout Plain Layout
2871 \SpecialChar nobreakdash
2872 \SpecialChar nobreakdash
2878 print the list of all labels associated with the test set.
2879 Can also be combined with -R, -L, -E, ...
2883 \begin_layout Standard
2884 Other useful options are:
2887 \begin_layout Labeling
2888 \labelwidthstring -R
2889 \begin_inset Flex Code
2892 \begin_layout Plain Layout
2898 Run the tests in parallel using the given number of jobs.
2902 \begin_layout Standard
2903 We are still working on getting the tests to run in parallel.
2904 However, when running the tests in parallel, sometimes tests fail that
2905 pass when run sequentially.
2906 A reasonable approach is to first run the tests in parallel and then run
2907 the failed tests sequentially.
2910 \begin_layout Standard
2911 For example, to run 8 jobs at a time:
2914 \begin_layout Standard
2915 \begin_inset Flex Code
2918 \begin_layout Plain Layout
2927 \begin_layout Standard
2928 \begin_inset Flex Code
2931 \begin_layout Plain Layout
2932 ctest \SpecialChar nobreakdash
2933 \SpecialChar nobreakdash
2942 \begin_layout Standard
2943 When specifying a subset of the tests (e.g.
2945 \begin_inset Flex Code
2948 \begin_layout Plain Layout
2949 \SpecialChar nobreakdash
2955 ), the same subset must be specified when using the
2956 \begin_inset Flex Code
2959 \begin_layout Plain Layout
2960 \SpecialChar nobreakdash
2961 \SpecialChar nobreakdash
2967 option because it is the test numbers that are used to index which tests
2968 failed on the previous run.
2971 \begin_layout Standard
2973 Note that some tests cannot be run in parallel.
2974 These tests are marked in the code with the
2975 \begin_inset Flex Code
2978 \begin_layout Plain Layout
2988 \begin_layout Labeling
2989 \labelwidthstring -R
2990 \begin_inset Flex Code
2993 \begin_layout Plain Layout
2994 \SpecialChar nobreakdash
2995 \SpecialChar nobreakdash
3001 Set a global timeout on all tests that do not already have a timeout set
3006 \begin_layout Standard
3007 There have been bugs in LyX and in \SpecialChar LaTeX
3008 which cause compilation to hang, and
3009 without a timeout a test might never stop (in one case there was even a
3011 If a test times out, the
3012 \begin_inset Flex Code
3015 \begin_layout Plain Layout
3021 command exits with error, but you can distinguish between a timed out test
3022 and a failed test in the output reported at the end of the
3023 \begin_inset Flex Code
3026 \begin_layout Plain Layout
3036 \begin_layout Standard
3038 \begin_inset Flex Code
3041 \begin_layout Plain Layout
3047 ) the full list of command line options.
3050 \begin_layout Paragraph
3054 \begin_layout Itemize
3055 run only the export tests:
3056 \begin_inset Flex Code
3059 \begin_layout Plain Layout
3068 \begin_layout Itemize
3070 \begin_inset Flex Code
3073 \begin_layout Plain Layout
3074 ctest -L "inverted|suspended"
3082 \begin_layout Itemize
3083 list all export tests which match any of the labelling patterns:
3084 \begin_inset Flex Code
3087 \begin_layout Plain Layout
3098 \begin_layout Itemize
3099 exclude rarely used output formats and post-processing tests
3100 \begin_inset Flex Code
3103 \begin_layout Plain Layout
3104 ctest -L export -E "_(texF|dvi3|pdf3?)"
3112 \begin_layout Paragraph
3113 \begin_inset CommandInset label
3115 name "subsec:Interpreting-export-tests"
3119 Interpreting the export test results
3122 \begin_layout Standard
3123 A test can fail for several reasons, not all of them bad.
3126 \begin_layout Enumerate
3127 A new or edited sample document may be incompatible with some output formats.
3130 \begin_layout Enumerate
3131 A dependency is not met (e.g.
3132 the \SpecialChar LaTeX
3134 One hint that this is the case is that the corresponding
3135 \begin_inset Flex Code
3138 \begin_layout Plain Layout
3144 test will likely also fail.
3147 \begin_layout Enumerate
3148 An inverted test fails to fail (i.e.
3149 export that previously failed now works).
3152 \begin_layout Enumerate
3153 An external dependency was updated (e.g.
3158 \begin_layout Enumerate
3159 A recent code change introduced a bug.
3162 \begin_layout Enumerate
3163 \begin_inset CommandInset label
3169 A change in a document exposed a previously unknown bug or an incompatibility
3170 with an export format (e.g.
3171 Lua\SpecialChar LaTeX
3175 \begin_layout Standard
3176 Because the .lyx files are exported in several formats, it is not surprising
3177 that many of the exports fail.
3178 This expectation of failure is addressed by
3179 \begin_inset Quotes eld
3183 \begin_inset Quotes erd
3186 the tests, that is, by marking the test as
3187 \begin_inset Quotes eld
3191 \begin_inset Quotes erd
3194 if the export exits with error and as
3195 \begin_inset Quotes eld
3199 \begin_inset Quotes erd
3202 if the export succeeds
3207 It follows that these expected failures will not show up as failed tests
3208 in the test results and thus will not pollute the
3209 \begin_inset Quotes eld
3213 \begin_inset Quotes erd
3217 If the export actually succeeds, then the test will fail.
3218 The purpose of this failure is to get your attention—something has changed,
3219 possibly for the better.
3222 \begin_layout Standard
3223 We try to document why a test is inverted or ignored.
3224 See the comment (prefixed with
3225 \begin_inset Flex Code
3228 \begin_layout Plain Layout
3234 ) above the block in which the test is listed as inverted or ignored in
3236 \begin_inset Flex Code
3239 \begin_layout Plain Layout
3240 development/autotests/invertedTests
3246 \begin_inset Flex Code
3249 \begin_layout Plain Layout
3250 development/autotests/unreliableTests
3256 \begin_inset Flex Code
3259 \begin_layout Plain Layout
3260 development/autotests/ignoredTests
3269 \begin_layout Standard
3270 A good question is why do we enable the tests for non-default formats? The
3271 answer is that if a non-default route is broken it is often because a bug
3272 was introduced in LyX and not because a document-specific change was made
3273 that is not supported by the route.
3274 In other words, there is a high signal/noise ratio in the export tests
3275 for some non-default formats.
3279 \begin_layout Standard
3280 When a test or several tests fail, consider checking the files in the
3281 \begin_inset Flex Code
3284 \begin_layout Plain Layout
3290 subdirectory of your build directory.
3291 In this subdirectory are three files: the file
3292 \begin_inset Flex Code
3295 \begin_layout Plain Layout
3301 simply lists the tests that failed on your last
3302 \begin_inset Flex Code
3305 \begin_layout Plain Layout
3312 \begin_inset Flex Code
3315 \begin_layout Plain Layout
3321 file contains the output from the tests (and often has details explaining
3322 why a test failed); and the
3323 \begin_inset Flex Code
3326 \begin_layout Plain Layout
3332 file lists the times that it took to run the tests.
3335 \begin_layout Paragraph
3336 What action should you take if a test fails?
3339 \begin_layout Standard
3340 \paragraph_spacing single
3341 It is always good to check manually why something fails and if it passes
3342 if the PDF output is good.
3345 \begin_layout Itemize
3346 Generally, if a change breaks compilation for the target format (for the
3347 manuals pdf2) without solving some important other issue,
3349 fix or revert the commit
3351 that led to failure.
3354 \begin_layout Itemize
3355 If it is not possible to (immediately) fix the failure but there are reasons
3356 not to revert the commit (e.g.
3357 it fixes another more important issue),
3361 the failing test case (see
3362 \begin_inset CommandInset ref
3364 reference "par:Inverted-tests"
3371 \begin_layout Itemize
3376 test case fails because the export now works, first confirm that the output
3377 of the corresponding export looks good (e.g., not garbled text).
3382 the test by removing the pattern from the
3383 \begin_inset Quotes eld
3387 \begin_inset Quotes erd
3391 \begin_inset CommandInset ref
3393 reference "par:Inverted-tests"
3400 \begin_layout Itemize
3401 If the export did not fail previously but led to wrong output (PDF, say),
3405 \begin_layout Plain Layout
3406 Non-failing test with wrong output should be labeled as
3407 \begin_inset Quotes eld
3410 unreliable:wrong_output
3411 \begin_inset Quotes erd
3415 \begin_inset CommandInset ref
3417 reference "par:Unreliable-tests"
3426 it is in fact an improvement when the test now fails.
3431 the failing test case (see
3432 \begin_inset CommandInset ref
3434 reference "par:Inverted-tests"
3441 \begin_layout Itemize
3442 In case of tests failing due to missing requirements (tests labeled
3443 \begin_inset Quotes eld
3446 unreliable:nonstandard
3447 \begin_inset Quotes erd
3450 or testing on a system with only a subset of TeXLive installed), ignore
3451 the failure, ask for someone else to run the test, or install the missing
3452 resources and try again.
3455 \begin_layout Itemize
3456 Check the log file Testing/Temporary/LastTest.log.
3457 In case of latex-errors rerun the failing test with environment variable
3458 'LYX_DEBUG_LATEX' set to '1'.
3459 This will include latex messages in LastTest.log, so it should be easier
3460 to interpret the fail-reason.
3463 \begin_layout Paragraph
3464 \begin_inset CommandInset label
3466 name "par:Inverted-tests"
3473 \begin_layout Standard
3474 Test cases whose name matches a pattern in the file
3475 \begin_inset Flex Code
3478 \begin_layout Plain Layout
3479 development/autotests/invertedTests
3489 They get also the test property
3490 \begin_inset Flex Code
3493 \begin_layout Plain Layout
3500 they are reported as failing if the export works without error
3501 \begin_inset Flex URL
3504 \begin_layout Plain Layout
3506 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3514 \begin_layout Standard
3515 Add failing cases to this file, if they cannot be solved
3516 \begin_inset Quotes eld
3520 \begin_inset Quotes erd
3523 but it is expected that the export will work in a foreseeable future, e.g.
3524 low priority issues like failures to export to a non-target format (for
3525 the manuals everything except pdf2).
3528 \begin_layout Standard
3529 The following sublabels are currently present in
3530 \begin_inset Flex Code
3533 \begin_layout Plain Layout
3542 \begin_layout Description
3543 todo test failures that require attention:
3547 \begin_layout Itemize
3548 minor issues to explore and properly sort later,
3551 \begin_layout Itemize
3555 \begin_layout Itemize
3556 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3560 \begin_layout Description
3561 lyxbugs LyX bugs with a Trac number.
3564 \begin_layout Description
3565 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3569 \begin_layout Standard
3570 "Wontfix" if demonstrating correct use and OK in the default output format.
3574 \begin_layout Description
3575 texissues Export fails due to LaTeX limitations like non-ASCII characters
3576 in verbatim or listings, incompatible packages, ...
3580 \begin_layout Standard
3581 "Wontfix" if documents demonstrate correct use in the default output format:
3584 \begin_layout Itemize
3585 If the source can be made more robust without becoming "hackish", fix the
3589 \begin_layout Itemize
3590 if LyX could be enhanced to care for a permanent TeX limitation, file a
3591 ticket at trac and add a pattern under lyxbugs,
3594 \begin_layout Itemize
3595 otherwise, add a pattern here.
3599 \begin_layout Description
3600 attic Documents in the attic (kept for reference and format conversion test).
3602 \begin_inset Quotes eld
3606 \begin_inset Quotes erd
3612 \begin_layout Subparagraph
3616 \begin_layout Standard
3617 Test cases whose name additionally matches a pattern in the file
3618 \begin_inset Flex Code
3621 \begin_layout Plain Layout
3622 development/autotests/suspendedTests
3640 This means they are not executed using
3641 \begin_inset Flex Code
3644 \begin_layout Plain Layout
3651 \begin_inset Flex Code
3654 \begin_layout Plain Layout
3661 However, they also get the test property
3662 \begin_inset Flex Code
3665 \begin_layout Plain Layout
3672 they are reported as failing if the export works without error.
3673 From time to time they still have to be checked using
3674 \begin_inset Flex Code
3677 \begin_layout Plain Layout
3686 \begin_layout Standard
3687 These tests are suspended, because the export fails for known reasons which
3688 cannot ATM be resolved.
3689 But it is expected the reason might disappear in the future.
3690 Be it new TL or better handling in \SpecialChar LyX
3694 \begin_layout Standard
3695 For ctest commands without the
3696 \begin_inset Flex Code
3699 \begin_layout Plain Layout
3705 parameter nothing changes.
3706 Suspended or not, tests will be executed depending only on the selecting
3707 regular expression given to the ctest command (see
3708 \begin_inset CommandInset ref
3710 reference "par:ctest-options"
3717 \begin_layout Paragraph
3718 \begin_inset CommandInset label
3720 name "par:Unreliable-tests"
3727 \begin_layout Standard
3728 Test cases whose name matches a pattern in the file
3729 \begin_inset Flex Code
3732 \begin_layout Plain Layout
3733 development/autotests/unreliableTests
3745 \begin_layout Standard
3746 These tests are not executed using
3747 \begin_inset Flex Code
3750 \begin_layout Plain Layout
3757 \begin_inset Flex Code
3760 \begin_layout Plain Layout
3770 \begin_layout Standard
3771 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3772 or pass but should rather fail (wrong output).
3774 \begin_inset Note Note
3777 \begin_layout Plain Layout
3778 *invalid* tests (wrong output) are not *unreliable*.
3779 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3788 \begin_layout Standard
3789 The following sublabels are currently present in
3790 \begin_inset Flex Code
3793 \begin_layout Plain Layout
3802 \begin_layout Description
3803 nonstandard Documents with additional requirements, e.g.
3804 a class or package file not in TeXLive.
3806 \begin_inset Note Note
3809 \begin_layout Plain Layout
3811 \begin_inset Quotes eld
3815 \begin_inset Quotes erd
3819 \begin_inset Quotes eld
3823 \begin_inset Quotes erd
3834 \begin_layout Description
3835 erratic Tests depending on local configuration or the phase of the moon.
3839 \begin_layout Description
3840 varying_versions Tests depending on e.g.
3841 OS or version of a non-TeX-Live dependency.
3842 Note that a full, up-to-date TeX Live installation is required so this
3843 sublabel is about versions of other dependencies.
3846 \begin_layout Description
3848 \begin_inset space ~
3851 output Export does not fail but the resulting document has (undetected)
3856 \begin_layout Standard
3857 \paragraph_spacing single
3858 \begin_inset Note Note
3861 \begin_layout Plain Layout
3862 \paragraph_spacing single
3863 These tests are in a strict sense not unreliable but
3867 (not measuring what they should measure).
3876 \begin_layout Paragraph
3877 \begin_inset CommandInset label
3879 name "par:Export-test-filtering"
3883 Export test filtering
3886 \begin_layout Standard
3887 The assignment of a label to a test is controlled by a set of files with
3888 regular expressions that are matched against the test names.
3891 \begin_layout Description
3892 ignoredTests (small file)
3893 \begin_inset Newline newline
3896 Tests selected here are withdrawn in the configuration step (cf.
3898 \begin_inset CommandInset ref
3900 reference "par:Configuring-ctests"
3908 \begin_layout Labeling
3909 \labelwidthstring 00.00.0000
3910 Input Test of any export combination
3913 \begin_layout Labeling
3914 \labelwidthstring 00.00.0000
3915 Output Stop if tests not selected here
3919 \begin_layout Description
3920 unreliableTests: Tests selected pass or fail dependent on the system where
3922 Selected tests gain the label 'unreliable'.
3926 \begin_layout Labeling
3927 \labelwidthstring 00.00.0000
3928 Input Each test which passed 'ignoredTests'
3931 \begin_layout Labeling
3932 \labelwidthstring 00.00.0000
3933 Output Gain label 'unreliable', proceed with checking for 'inverted'.
3937 \begin_layout Description
3939 \begin_inset space \space{}
3946 \begin_layout Labeling
3947 \labelwidthstring 00.00.0000
3948 Input Each test which passed 'ignoredTests'
3951 \begin_layout Labeling
3952 \labelwidthstring 00.00.0000
3953 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3954 tests are reported as failing if the export works without error.) If no
3955 subselection applies, gain labels 'export' and 'inverted'.
3958 \begin_layout Standard
3959 The following filter perfoms a subselection of 'invertedTests':
3962 \begin_layout Description
3963 suspendedTests Tests selected here gain the label 'suspended' but _not_
3964 'export' or 'inverted', although in ctest they remain inverted.
3965 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3969 \begin_layout Labeling
3970 \labelwidthstring 00.00.0000
3971 Input Each test selected by 'invertedTests'
3974 \begin_layout Labeling
3975 \labelwidthstring 00.00.0000
3976 Output Selected test gains label 'suspended'.
3982 \begin_layout Standard
3983 The following table may clarify label assignement
3986 \begin_layout Standard
3987 \begin_inset space \hspace{}
3992 \begin_inset Tabular
3993 <lyxtabular version="3" rows="6" columns="8">
3994 <features tabularvalignment="middle">
3995 <column alignment="left" valignment="top" width="2cm">
3996 <column alignment="left" valignment="top" width="2.5cm">
3997 <column alignment="left" valignment="top" width="2cm">
3998 <column alignment="center" valignment="top" width="2.5cm">
3999 <column alignment="center" valignment="top">
4000 <column alignment="center" valignment="top">
4001 <column alignment="center" valignment="top">
4002 <column alignment="center" valignment="top">
4004 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4007 \begin_layout Plain Layout
4008 Test matching pattern in file:
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="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4034 \begin_layout Plain Layout
4040 <cell multicolumn="1" 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" leftline="true" usebox="none">
4052 \begin_layout Plain Layout
4058 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4061 \begin_layout Plain Layout
4067 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4070 \begin_layout Plain Layout
4078 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4081 \begin_layout Plain Layout
4082 ignored\SpecialChar softhyphen
4088 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4091 \begin_layout Plain Layout
4092 unreliable\SpecialChar softhyphen
4098 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4101 \begin_layout Plain Layout
4102 inverted\SpecialChar softhyphen
4108 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4111 \begin_layout Plain Layout
4112 suspended\SpecialChar softhyphen
4118 <cell alignment="center" valignment="top" topline="true" leftline="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" usebox="none">
4139 \begin_layout Plain Layout
4145 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4148 \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="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4177 \begin_layout Plain Layout
4183 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4186 \begin_layout Plain Layout
4192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4195 \begin_layout Plain Layout
4201 <cell alignment="center" valignment="top" topline="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
4219 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4222 \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
4239 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4242 \begin_layout Plain Layout
4244 \begin_inset Newline newline
4248 \begin_inset Newline newline
4256 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4259 \begin_layout Plain Layout
4265 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4268 \begin_layout Plain Layout
4274 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4277 \begin_layout Plain Layout
4283 <cell alignment="center" valignment="top" topline="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
4301 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4304 \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" leftline="true" usebox="none">
4324 \begin_layout Plain Layout
4330 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4333 \begin_layout Plain Layout
4339 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4342 \begin_layout Plain Layout
4348 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4351 \begin_layout Plain Layout
4357 <cell alignment="center" valignment="top" topline="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
4375 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4378 \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 multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4398 \begin_layout Plain Layout
4404 <cell alignment="left" 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" leftline="true" usebox="none">
4425 \begin_layout Plain Layout
4431 <cell alignment="center" valignment="top" topline="true" bottomline="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
4449 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4452 \begin_layout Plain Layout
4466 \begin_layout Standard
4467 \begin_inset Note Note
4470 \begin_layout Plain Layout
4472 \begin_inset Quotes eld
4476 \begin_inset Quotes erd
4479 filter, this would be far less complicated:
4482 \begin_layout Plain Layout
4483 \begin_inset Tabular
4484 <lyxtabular version="3" rows="6" columns="7">
4485 <features tabularvalignment="middle">
4486 <column alignment="left" valignment="top" width="0pt">
4487 <column alignment="left" valignment="top" width="0pt">
4488 <column alignment="left" valignment="top" width="0pt">
4489 <column alignment="center" valignment="top">
4490 <column alignment="center" valignment="top">
4491 <column alignment="center" valignment="top">
4492 <column alignment="center" valignment="top">
4494 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4497 \begin_layout Plain Layout
4498 Test matching pattern in file:
4503 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4506 \begin_layout Plain Layout
4512 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4515 \begin_layout Plain Layout
4521 <cell multicolumn="1" 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 multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4542 \begin_layout Plain Layout
4548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4551 \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="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4580 \begin_layout Plain Layout
4586 <cell alignment="center" valignment="top" topline="true" leftline="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" usebox="none">
4607 \begin_layout Plain Layout
4613 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4616 \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="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4645 \begin_layout Plain Layout
4651 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4654 \begin_layout Plain Layout
4660 <cell alignment="center" valignment="top" topline="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
4678 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4681 \begin_layout Plain Layout
4689 <cell multirow="3" alignment="left" valignment="middle" 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="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4710 \begin_layout Plain Layout
4716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4719 \begin_layout Plain Layout
4725 <cell alignment="center" valignment="top" topline="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
4743 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4746 \begin_layout Plain Layout
4754 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4757 \begin_layout Plain Layout
4763 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4766 \begin_layout Plain Layout
4772 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4775 \begin_layout Plain Layout
4781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4784 \begin_layout Plain Layout
4790 <cell alignment="center" valignment="top" topline="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
4808 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4811 \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 multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4831 \begin_layout Plain Layout
4837 <cell alignment="left" 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" leftline="true" usebox="none">
4849 \begin_layout Plain Layout
4855 <cell alignment="center" valignment="top" topline="true" bottomline="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
4873 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4876 \begin_layout Plain Layout
4895 \begin_layout Subsubsection
4899 \begin_layout Standard
4900 These tests check whether a .lyx file loads without any terminal messages.
4901 They correspond to the manual operations of simply opening a .lyx file on
4902 the terminal, exiting LyX once the file is loaded, and then checking whether
4903 there is any output from the terminal.
4904 These tests are useful for catching malformed .lyx files and parsing bugs.
4905 They can also be used to find a .lyx file in which an instance of something
4907 To do this, compile LyX with a local patch that outputs something to the
4908 terminal when an instance is found, and then run the check_load tests to
4909 see if any fail, which would mean that the situation occurs in the LyX
4910 documentation files corresponding to the failed tests.
4911 These tests are expectedly fragile: any LyX diagnostic message, which is
4912 not necessarily an error, would cause the tests to fail.
4913 Similarly, any message output by a library (e.g.
4914 Qt) would also cause failure.
4915 There are some messages that the check_load tests are instructed to ignore,
4916 which are stored in the file
4917 \begin_inset Flex Code
4920 \begin_layout Plain Layout
4921 development/autotests/filterCheckWarnings
4929 \begin_layout Standard
4930 Under cmake, the tests are labeled as 'load'.
4933 \begin_layout Subsubsection
4937 \begin_layout Standard
4938 Automated tests based on the "MonKey Testing" keytest program are enabled
4939 if the necessary dependencies are found and if the CMake flag
4940 \begin_inset Flex Code
4943 \begin_layout Plain Layout
4944 -DLYX_ENABLE_KEYTESTS=ON
4950 They are documented in the README document in
4951 \begin_inset Flex Code
4954 \begin_layout Plain Layout
4955 development/autotests
4960 subfolder of the \SpecialChar LyX
4961 source code distribution.
4964 \begin_layout Subsubsection
4968 \begin_layout Standard
4969 These tests combine lyx2lyx tests with check_load tests.
4970 They fail if either fails.
4973 \begin_layout Subsubsection
4977 \begin_layout Standard
4978 The URL tests are enabled with the
4979 \begin_inset Flex Code
4982 \begin_layout Plain Layout
4983 -DLYX_ENABLE_URLTESTS=ON
4988 CMake flag and are useful for finding broken links in our documentation
4990 If a URL test fails, to see which link in particular was reported as broken,
4992 \begin_inset Flex Code
4995 \begin_layout Plain Layout
5002 These tests are extremely fragile (e.g.
5003 a test can depend on your Internet connection) and a failed URL test should
5004 not be taken too seriously.
5005 URL tests are labeled as
5010 \begin_layout Paragraph
5014 \begin_layout Standard
5015 cmake is required to run the \SpecialChar LyX
5016 tests, running them is not implemented for
5020 \begin_layout Standard
5021 The appropriate commands are:
5024 \begin_layout Itemize
5030 \begin_inset Newline newline
5033 runs all tests with label
5038 \begin_layout Itemize
5041 ctest -R 'check_.*urls'
5044 \begin_inset Newline newline
5047 runs the tests 'check_accessible_urls'
5050 \begin_layout Standard
5051 Associated test results can be examined in ctest-log directory in files
5052 of the form 'LastFailed.*URLS.log'
5055 \begin_layout Section
5056 Development policies
5059 \begin_layout Standard
5060 This chapter lists some guidelines that should be followed.
5061 This list is not complete, and many guidelines are in separate chapters,
5063 \begin_inset Quotes eld
5066 When is an update of the .lyx file format number needed?
5067 \begin_inset Quotes erd
5071 \begin_inset CommandInset ref
5073 reference "sec:When-is-an"
5080 \begin_layout Subsection
5081 When to set a fixed milestone?
5084 \begin_layout Standard
5085 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5089 \begin_layout Enumerate
5090 Somebody is actively working on a fix.
5093 \begin_layout Enumerate
5094 The bug is so severe that it would block the release if it is not fixed.
5097 \begin_layout Standard
5098 If a bug is important, but nobody is working on it, and it is no showstopper,
5099 use a milestone like 2.1.x or 2.2.x.
5100 For all other bugs, do not set a milestone at all.
5103 \begin_layout Subsection
5104 Can we add rc entries in stable branch?
5107 \begin_layout Standard
5109 We are supposed to increase the prefs2prefs version number with such things.
5112 \begin_layout Section
5113 \begin_inset CommandInset label
5115 name "sec:Documentation-policies"
5119 Documentation policies
5122 \begin_layout Subsection
5126 \begin_layout Standard
5128 \begin_inset space ~
5131 rules in editing the docs:
5134 \begin_layout Enumerate
5135 \begin_inset CommandInset label
5137 name "enu:If-you-are"
5141 If you are not the maintainer of a doc file or a chapter/section, you MUST
5142 use change tracking so that the maintainer could review your changes
5145 \begin_layout Enumerate
5146 Respect the formatting of the document.
5147 The different files use different formatting styles.
5148 That is OK and has historic reasons nobody fully knows ;-).
5149 But it is important to be consistent within one file.
5152 \begin_layout Enumerate
5153 All changes you make to a file in one language MUST also go the file in
5154 the other actively maintained languages.
5155 Normally the maintainer does this for you, if you are the maintainer, you
5156 must do this by copying or changing the changed or added text to the other
5157 files so that the translators sees the blue underlined text and know what
5158 they have to translate and what was changed.
5161 \begin_layout Enumerate
5162 You MUST assure that the document is compilable as
5163 \begin_inset Quotes eld
5167 \begin_inset Quotes erd
5170 or the document's default output format after your changes.
5173 \begin_layout Enumerate
5174 All fixes (typos, compilation fixes, updates info etc.) go at first into
5175 the current GIT branch because the user should benefit from all fixes with
5176 every minor release.
5177 Feel free to commit directly to branch as long as you follow rule
5178 \begin_inset space ~
5182 \begin_inset CommandInset ref
5184 reference "enu:If-you-are"
5189 You can immediately commit to master as well.
5192 \begin_layout Enumerate
5193 \begin_inset CommandInset label
5195 name "enu:The-fileformat-of"
5199 The fileformat of a file must not be changed unless you document a new feature
5200 in LyX that requires a new fileformat.
5201 The reason for this rule is to keep it easy for the doc maintainers to
5202 port/backport changes to from master/branch.
5205 \begin_layout Standard
5206 The main documentation consists of these files:
5209 \begin_layout Description
5210 Welcome.lyx it is the first file you see after an installation.
5211 We assume that a new user sees this.
5212 It is therefore designed to be as simple as possible.
5213 Therefore please don't add any new formatting, only fix typos etc.
5214 Welcome.lyx is up to date for \SpecialChar LyX
5215 2.1.x, currently maintained by Uwe Stöhr.
5218 \begin_layout Description
5219 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5221 It therefore uses a limited set of formatting.
5222 For example a standard document class.
5223 Since new users will first learn about the formatting possibilities of
5225 please keep this file that simple.
5226 Intro.lyx is up to date for \SpecialChar LyX
5227 2.1.x, currently maintained by Uwe Stöhr.
5230 \begin_layout Description
5231 Tutorial.lyx our tutorial.
5232 It must be always up to date.
5233 Normally there is nothing to add since we don't want to overwhelm new users
5234 with too much details.
5235 The will learn these details while using \SpecialChar LyX
5236 and we have special manuals.
5237 Tutorial.lyx is up to date for \SpecialChar LyX
5238 2.1.x, currently maintained by Uwe Stöhr.
5241 \begin_layout Description
5242 UserGuide.lyx our main user guide.
5243 It covers a mixture of basic and detailed information.
5244 Some information is also in the Math and EmbeddedObjects manual so that
5245 the UserGuide refers to these files.
5246 UserGuide.lyx is up to date for \SpecialChar LyX
5247 2.1.x, currently maintained by Uwe Stöhr.
5250 \begin_layout Description
5251 EmbeddedObjects.lyx a special manual to explain things like tables floats
5254 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5255 2.1.x, currently maintained by Uwe
5259 \begin_layout Description
5260 Math.lyx a special manual to explain everything regarding math in all detail.
5261 Math.lyx is up to date for \SpecialChar LyX
5262 2.1.x, currently maintained by Uwe Stöhr.
5265 \begin_layout Description
5266 Additional.lyx this manual covers information that would be too much detail
5267 for the UserGuide or would make the UserGuide uncompilable or only compilable
5268 when installing a lot of special \SpecialChar LaTeX
5270 What should be in the UserGuide or better in Additional is a matter of
5272 it is up to you to decide that.
5273 Additional.lyx is not completely up to date for \SpecialChar LyX
5276 \begin_inset space ~
5279 8 is up to date and currently maintained by Uwe Stöhr.
5280 It certainly needs a rewrite and update.
5281 For example many info in chapter
5282 \begin_inset space ~
5285 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5289 \begin_layout Description
5290 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5292 output formats, operating systems, languages etc.
5293 It is currently completely out of date and needs a major rewrite and update.
5294 If you do this please assure that your information are given for all OSes
5295 and \SpecialChar LaTeX
5296 distributions (meaning be as objective as possible).