1 #LyX 2.3 created this file. For more info see http://www.lyx.org/
5 \save_transient_properties true
6 \origin /systemlyxdir/doc/
8 \options BCOR8mm,captions=tableheading
9 \use_default_options false
13 \maintain_unincluded_children false
15 \language_package default
18 \font_roman "lmodern" "default"
19 \font_sans "lmss" "default"
20 \font_typewriter "lmtt" "default"
21 \font_math "auto" "auto"
22 \font_default_family default
23 \use_non_tex_fonts false
26 \font_sf_scale 100 100
27 \font_tt_scale 100 100
29 \use_dash_ligatures true
31 \default_output_format pdf2
33 \bibtex_command default
34 \index_command default
38 \pdf_title "LyX's Development manual"
39 \pdf_author "LyX Team"
40 \pdf_subject "LyX's development documentation"
41 \pdf_keywords "LyX, Documentation, Development"
43 \pdf_bookmarksnumbered true
44 \pdf_bookmarksopen true
45 \pdf_bookmarksopenlevel 1
50 \pdf_pdfusetitle false
51 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
54 \use_package amsmath 1
55 \use_package amssymb 1
58 \use_package mathdots 1
59 \use_package mathtools 1
61 \use_package stackrel 1
62 \use_package stmaryrd 1
63 \use_package undertilde 1
65 \cite_engine_type default
69 \paperorientation portrait
74 \notefontcolor #0000ff
81 \paragraph_separation indent
82 \paragraph_indentation default
84 \math_numbering_side default
89 \paperpagestyle headings
90 \tracking_changes false
100 Developing \SpecialChar LyX
104 \begin_layout Subtitle
109 by the \SpecialChar LyX
114 \begin_layout Plain Layout
116 If you have comments or error corrections, please send them to the \SpecialChar LyX
119 \begin_inset Flex Code
122 \begin_layout Plain Layout
124 <lyx-docs@lists.lyx.org>
137 \begin_layout Standard
138 \begin_inset CommandInset toc
139 LatexCommand tableofcontents
146 \begin_layout Section
150 \begin_layout Standard
151 This manual documents some aspects of \SpecialChar LyX
153 It is currently rather incomplete, but will hopefully be extended in the
155 Meanwhile, additional information can be found in the
156 \begin_inset Flex Code
159 \begin_layout Plain Layout
165 subfolder of the \SpecialChar LyX
166 source code distribution.
167 This document is not translated, since the development language of \SpecialChar LyX
170 If you just want to use \SpecialChar LyX
171 , then you don't need to read this manual.
172 However, if you want to learn more about how \SpecialChar LyX
173 is developed, or even want
174 to participate in \SpecialChar LyX
175 development, you may find some interesting information
179 \begin_layout Section
183 \begin_layout Standard
185 uses several custom file formats for configuration files and documents.
186 This chapter contains some background concerning these file formats.
187 Several file formats are also described in detail in the regular user documenta
191 \begin_layout Subsection
195 \begin_layout Subsection
196 When is an update of the .lyx file format number needed?
197 \begin_inset CommandInset label
199 name "sec:When-is-an"
206 \begin_layout Standard
207 When you are working on a new feature you may ask yourself whether it needs
208 an update of the .lyx file format number.
209 Whether an update is needed or not is not always obvious.
214 Whenever there is the danger that a previous version of LyX cannot open
215 a file using the new feature, a file format update is needed.
218 \begin_layout Standard
219 The file format change allows lyx2lyx rules to implement backwards compatibility.
220 Below you can find a list of reasons for file format updates with explanations:
223 \begin_layout Description
232 setting Whenever you introduce a new setting that is stored in the document
233 header, a file format update is needed.
236 \begin_layout Description
245 setting If a certain setting becomes obsolete and gets removed, a file format
249 \begin_layout Description
275 \begin_inset space \thinspace{}
282 \begin_layout Description
283 \paragraph_spacing single
296 package The reason for this is that there is no true ERT inset for math
297 formulas: Each command is parsed, and if a user happens to define a local
298 command with the same name as a command that triggers an automatic load
299 of a package, they need to be able to switch off the automatic loading
301 This switch is stored by the
302 \begin_inset Flex Code
305 \begin_layout Plain Layout
314 \begin_layout Description
319 language that is stored in
320 \begin_inset Flex Code
323 \begin_layout Plain Layout
333 \begin_inset Note Note
336 \begin_layout Plain Layout
337 This requirement is under discussion.
346 \begin_layout Description
351 inset Of course a new inset requires a file format update.
354 \begin_layout Description
359 style If a new style or inset layout is added to any layout file or module
360 shipped with \SpecialChar LyX
361 , then a new file format is needed in the master (development)
363 It is possible to backport new styles to the stable version without a file
366 \begin_inset CommandInset ref
368 reference "subsec:Backporting-new-styles"
372 for more information.
375 \begin_layout Description
380 style If a style or inset layout is removed in any layout file or module
381 shipped with \SpecialChar LyX
382 , a new file format is required.
385 \begin_layout Standard
390 layouts and modules do
394 require a file format update (changed 03/16, see
395 \begin_inset CommandInset ref
397 reference "subsec:New-layouts"
405 \begin_layout Standard
406 If you are still unsure, please ask on the development list.
409 \begin_layout Subsection
410 \begin_inset CommandInset label
412 name "subsec:update_lyx_files"
416 How to update the file format number of .lyx files
419 \begin_layout Standard
420 Once you come to the conclusion that a file format update is needed, you
421 should use the following procedure to perform the update:
424 \begin_layout Enumerate
425 Implement and test the new feature, including the reading and writing of
427 Note that any file produced at this stage does not use a valid format,
428 so do not use this version of \SpecialChar LyX
429 for working on any important documents.
432 \begin_layout Enumerate
433 \begin_inset CommandInset label
435 name "enu:Describe_format"
439 Describe the new format in
440 \begin_inset Flex Code
443 \begin_layout Plain Layout
452 \begin_layout Enumerate
453 Update the \SpecialChar LyX
454 file format number in
455 \begin_inset Flex Code
458 \begin_layout Plain Layout
467 \begin_layout Enumerate
468 \begin_inset CommandInset label
470 name "enu:Add-an-entry"
474 Add an entry to both format lists (for conversion and reversion) in
475 \begin_inset Newline newline
479 \begin_inset Flex Code
482 \begin_layout Plain Layout
483 lib/lyx2lyx/lyx_2_3.py
489 Add a conversion routine if needed (e.
490 \begin_inset space \thinspace{}
493 g., a new header setting always needs a conversion that adds the new setting,
494 but a new document language does not need one).
495 Add a reversion routine if needed.
497 \begin_inset Newline newline
500 While the conversion routine is required to produce a document that is equivalen
501 t to the old version, the requirements of the reversion are not that strict.
502 If possible, try to produce a proper reversion, using ERT if needed, but
503 for some features this might be too complicated.
504 In this case, the minimum requirement of the reversion routine is that
505 it produces a valid document which can be read by an older \SpecialChar LyX
507 If absolutely needed, even data loss is allowed for the reversion.
508 (In that case, you might want to add a LyX comment that indicates what
509 you have had to do, so the user is at least warned).
512 \begin_layout Enumerate
513 Since tex2lyx has several implicit file format dependencies caused by sharing
514 code with \SpecialChar LyX
515 , updating the file format of .lyx files produced by tex2lyx at
516 the same time as updating the main .lyx file format is strongly recommended.
517 Therefore, a compiler warning will be issued if the \SpecialChar LyX
518 and tex2lyx .lyx file
519 format numbers differ.
520 In many cases the tex2lyx update requires only the first and last item
525 \begin_layout Enumerate
526 Update the tex2lyx file format number in
527 \begin_inset Flex Code
530 \begin_layout Plain Layout
539 \begin_layout Enumerate
540 If the lyx2lyx conversion from the old to the new format is empty, or if
541 tex2lyx does not yet output the changed feature, you do not need any further
543 Otherwise, search for the changed feature in tex2lyx, and adjust the output
544 according to the lyx2lyx changes.
547 \begin_layout Enumerate
548 Update the tex2lyx test references as described in
549 \begin_inset CommandInset ref
550 LatexCommand formatted
551 reference "sec:Updating-test-references"
559 \begin_layout Enumerate
560 If you did not implement full tex2lyx support for the new feature, add a
562 \begin_inset Flex Code
565 \begin_layout Plain Layout
571 describing the missing bits.
572 Note that it is perfectly fine if you do not add full tex2lyx support for
573 a new feature: The updating recommendation above is only issued for the
574 syntax of the produced .lyx file.
575 It is no problem if some features supported by \SpecialChar LyX
576 are still output as ERT
578 The problems in the past that resulted in the update recommendation were
579 related to mixed version syntax, not ERT.
582 \begin_layout Enumerate
583 It would be nice if you could create a .lyx test file which contains instances
584 of all changed or added features.
585 This could then be used to test lyx2lyx and tex2lyx.
586 Unfortunately, it has not yet been decided how to collect such examples,
587 so please ask on the development list if you want to create one.
590 \begin_layout Enumerate
591 \begin_inset CommandInset label
593 name "enu:updatefiles"
597 Test your lyx2lyx code by updating LyX's .lyx documentation files to the
599 The developer who makes the change knows best what changes to expect when
600 inspecting the resulting diff.
601 Because of this, you might be able to catch a bug in the lyx2lyx code that
602 updates the format just by taking a quick scan through the large diff that
604 \begin_inset Note Note
607 \begin_layout Plain Layout
608 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
609 see which layout update made an unexpected change by looking at the git
610 log of a .lyx file that suffers the problem.
615 To do this, first make sure that there are no changes to the git repository
616 that you will not want to commit (this is needed because it will be convenient
617 to commit with the command
618 \begin_inset Flex Code
621 \begin_layout Plain Layout
628 Then run the following command in the root folder of the source:
629 \begin_inset Flex Code
632 \begin_layout Plain Layout
633 python development/tools/updatedocs.py
639 Look at the resulting changes using the command
640 \begin_inset Flex Code
643 \begin_layout Plain Layout
650 If anything looks surprising, please investigate.
651 Keep in mind that the case of
652 \begin_inset Flex Code
655 \begin_layout Plain Layout
661 is special, because it is first generated with
662 \begin_inset Flex Code
665 \begin_layout Plain Layout
671 before being converted to the latest format.
672 \begin_inset Newline newline
676 \begin_inset Note Greyedout
679 \begin_layout Plain Layout
684 Only commit file format changes in the doc files if these files are using
685 the new feature of the new file format.
691 \begin_inset CommandInset ref
693 reference "enu:The-fileformat-of"
697 of the documentation policies described in sec.
702 \begin_inset CommandInset ref
704 reference "sec:Documentation-policies"
716 \begin_layout Enumerate
717 Finally, commit using
718 \begin_inset Flex Code
721 \begin_layout Plain Layout
730 \begin_layout Subsection
731 Updating the file format number of layout files
734 \begin_layout Standard
735 The procedure for updating the layout files is similar to that in step
736 \begin_inset CommandInset ref
738 reference "enu:updatefiles"
743 \begin_inset CommandInset ref
745 reference "subsec:update_lyx_files"
751 \begin_inset Flex Code
754 \begin_layout Plain Layout
755 python development/tools/updatelayouts.py
761 \begin_inset Flex Code
764 \begin_layout Plain Layout
773 \begin_layout Standard
774 Note that we do not automatically update any local layout used in the
775 \begin_inset Flex Code
778 \begin_layout Plain Layout
784 files shipped with \SpecialChar LyX
785 because users would then not be able to export to older
787 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
788 to open the file in \SpecialChar LyX
789 2.1.x, there would be an error because the file would
790 contain a local layout whose format is too new.
791 The root reason for this is that we do not support converting layouts to
792 older layout formats, as we do for the
793 \begin_inset Flex Code
796 \begin_layout Plain Layout
805 \begin_layout Subsection
806 Updating the file format number of bind/ui files
809 \begin_layout Standard
810 A change to the functionality of existing LFUNs can require a conversion
812 \begin_inset Flex Code
815 \begin_layout Plain Layout
822 \begin_inset Flex Code
825 \begin_layout Plain Layout
831 files, and therefore an increment of the LFUN format, as well as a conversion
833 \begin_inset Flex Code
836 \begin_layout Plain Layout
843 The latter cannot be done automatically and also requires an update of
847 \begin_inset space \space{}
850 of someone who might have made a set of \SpecialChar LyX
851 teaching manuals for use in their
856 \begin_layout Plain Layout
857 \begin_inset Flex URL
860 \begin_layout Plain Layout
862 http://www.lyx.org/trac/ticket/9794
875 \begin_layout Standard
876 To update the LFUN format:
879 \begin_layout Enumerate
880 Increment the LFUN file format number in
881 \begin_inset Flex Code
884 \begin_layout Plain Layout
893 \begin_layout Enumerate
894 Implement the LFUN conversion in
895 \begin_inset Flex Code
898 \begin_layout Plain Layout
899 lib/scripts/prefs2prefs_lfuns.py
907 \begin_layout Enumerate
909 \begin_inset CommandInset ref
911 reference "enu:updatefiles"
916 \begin_inset CommandInset ref
918 reference "subsec:update_lyx_files"
923 \begin_inset Flex Code
926 \begin_layout Plain Layout
932 command, use this command:
933 \begin_inset Flex Code
936 \begin_layout Plain Layout
937 bash development/tools/updatelfuns.sh
944 \begin_inset Note Note
947 \begin_layout Plain Layout
948 This file should really be converted to python.
956 \begin_layout Enumerate
957 Update Info insets in
958 \begin_inset Flex Code
961 \begin_layout Plain Layout
968 To do so, increment the \SpecialChar LyX
969 format and proceed as in
970 \begin_inset CommandInset ref
972 reference "subsec:update_lyx_files"
977 \begin_inset CommandInset ref
979 reference "enu:Describe_format"
984 \begin_inset CommandInset ref
986 reference "enu:updatefiles"
991 In the lyx2lyx implementation (step
992 \begin_inset CommandInset ref
994 reference "enu:Add-an-entry"
998 ), implement a conversion similar to the one in
999 \begin_inset Flex Code
1002 \begin_layout Plain Layout
1003 prefs2prefs_lfuns.py
1008 above, as well as a corresponding reversion; for this one can use
1009 \begin_inset Flex Code
1012 \begin_layout Plain Layout
1019 \begin_inset Flex Code
1022 \begin_layout Plain Layout
1023 lib/lyx2lyx/lyx2lyx_tools.py
1032 \begin_layout Subsection
1033 Backporting new styles to the stable version
1034 \begin_inset CommandInset label
1036 name "subsec:Backporting-new-styles"
1043 \begin_layout Standard
1044 Starting with the stable \SpecialChar LyX
1045 2.1 branch, there is a mechanism in place to backport
1046 new styles to the stable version without the need to update the file format.
1047 The basic idea is that the new style definition is automatically copied
1048 to the document preamble so that it can even be used by older minor versions
1049 that did not yet include the style.
1050 To backport a new style to the stable version, the following steps are
1054 \begin_layout Enumerate
1056 \begin_inset Flex Code
1059 \begin_layout Plain Layout
1065 to the style definition in the development version.
1068 \begin_layout Enumerate
1069 Copy the style definition to the stable version, but use
1070 \begin_inset Flex Code
1073 \begin_layout Plain Layout
1080 If needed adjust the format to the one used by the stable version (see
1081 the customization manual for details of the layout file format).
1084 \begin_layout Enumerate
1085 For each update of the style in a later stable version, increase the argument
1087 \begin_inset Flex Code
1090 \begin_layout Plain Layout
1097 (In the stable version, the development version should not be touched.)
1100 \begin_layout Standard
1101 For details about the
1102 \begin_inset Flex Code
1105 \begin_layout Plain Layout
1111 flag see the customization manual.
1113 \begin_inset Flex Code
1116 \begin_layout Plain Layout
1122 support is needed for backported styles: Since the style of the development
1123 version has an infinite version number, it will always be used.
1124 Furthermore, since its version number is less than one, the style will
1125 not be written anymore to the document header for files saved by the new
1129 \begin_layout Section
1130 New layouts and modules
1133 \begin_layout Subsection
1134 \begin_inset CommandInset label
1136 name "subsec:New-layouts"
1143 \begin_layout Standard
1144 Adding a new layout file to the \SpecialChar LyX
1146 \begin_inset Quotes eld
1149 officially supported
1150 \begin_inset Quotes erd
1154 You should therefore think carefully about whether you really want to do
1155 this and discuss it on lyx-devel, since you will need to be prepared to
1156 update and fix the layout if necessary.
1157 If the layout is experimental or for a rarely used document class, then
1158 it may be better to add it to the relevant portion of the \SpecialChar LyX
1162 \begin_inset CommandInset href
1164 target "https://wiki.lyx.org/Layouts/Layouts"
1172 \begin_layout Standard
1173 In older versions of this document, it was stated that new layout files
1174 require a file format change.
1175 After some discussion, it was decided that this is not needed.
1179 \begin_layout Plain Layout
1181 \begin_inset CommandInset href
1183 name "the thread “Proposal for a guide on updating layouts”"
1184 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1198 For reference, here are the arguments on each side
1202 \begin_layout Description
1204 \begin_inset Quotes eld
1207 New layout files are a file format change
1208 \begin_inset Quotes erd
1214 \begin_layout Itemize
1215 All documents produced by 2.2.
1216 \begin_inset Formula $x$
1219 can always be edited and exported even if
1220 \begin_inset Formula $x$
1224 This is important for people using different machines, or exchanging work
1228 \begin_layout Description
1230 \begin_inset Quotes eld
1233 New layout files are not a file format change
1234 \begin_inset Quotes erd
1240 \begin_layout Itemize
1241 No new LaTeX classes can be supported in a stable version, and stable versions
1242 have a typical lifetime of 2–3 years.
1245 \begin_layout Itemize
1246 We have the same situation already with custom layout files: If a document
1247 using a custom layout file is moved between machines or people, then the
1248 layout file needs to be exchanged as well.
1249 If that is not done, then we have a fallback implemented so that such documents
1250 can still be edited, but not exported, and the user gets a warning.
1254 \begin_layout Itemize
1255 The lyx2lyx script cannot do anything useful in such a case.
1259 \begin_layout Standard
1260 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1262 then, you should do the following:
1265 \begin_layout Enumerate
1266 Put your new layout file in
1267 \begin_inset Flex Code
1270 \begin_layout Plain Layout
1277 \begin_inset Flex Code
1280 \begin_layout Plain Layout
1281 git add lib/layouts/newlayout.layout
1286 ) so that it will be committed.
1289 \begin_layout Enumerate
1291 \begin_inset Flex Code
1294 \begin_layout Plain Layout
1300 , so that the new layout actually gets installed.
1303 \begin_layout Enumerate
1305 \begin_inset Flex Code
1308 \begin_layout Plain Layout
1309 lib/doc/LaTeXConfig.lyx
1314 containing in particular a line like
1322 \begin_layout Standard
1323 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1324 \begin_inset Flex Code
1327 \begin_layout Plain Layout
1328 info-insert textclass <name>
1334 This inset will automatically display a boxed
1335 \begin_inset Quotes eld
1339 \begin_inset Quotes erd
1343 \begin_inset Quotes eld
1347 \begin_inset Quotes erd
1350 depending on the availability of the package.
1354 \begin_layout Enumerate
1355 A template or example is strongly encouraged (but not necessarily required).
1356 It is also possible to provide both.
1358 \begin_inset Flex Code
1361 \begin_layout Plain Layout
1368 \begin_inset Flex Code
1371 \begin_layout Plain Layout
1380 \begin_layout Enumerate
1381 Reconfigure \SpecialChar LyX
1385 \begin_layout Enumerate
1386 Ensure the autotests for the new layout pass (see
1387 \begin_inset CommandInset ref
1389 reference "par:when-to-run-an-export-test"
1396 \begin_layout Subsection
1400 \begin_layout Standard
1401 Adding a new module is very similar to adding a new layout.
1402 Therefore, the previous section applies to new modules as well, with two
1406 \begin_layout Enumerate
1407 You only need to add an entry to
1408 \begin_inset Flex Code
1411 \begin_layout Plain Layout
1412 lib/doc/LaTeXConfig.lyx
1417 if the module requires a LaTeX package.
1418 In that case, the command for entering the InsetInfo is:
1419 \begin_inset Flex Code
1422 \begin_layout Plain Layout
1423 \paragraph_spacing single
1424 info-insert package <name>
1432 \begin_layout Enumerate
1433 Modules do not need a template, only an example, which is strongly encouraged
1434 but not necessarily required.
1437 \begin_layout Subsection
1441 \begin_layout Standard
1442 The declaration lines of layouts and modules (
1443 \begin_inset Flex Code
1446 \begin_layout Plain Layout
1455 \begin_inset Flex Code
1458 \begin_layout Plain Layout
1466 ) should list the packages and classes the layout (or some\SpecialChar breakableslash
1467 one of the layouts\SpecialChar breakableslash
1469 ts of the module) needs.
1470 Please do not add dependencies beyond this
1471 \begin_inset Quotes eld
1475 \begin_inset Quotes erd
1479 \begin_inset space \thinspace{}
1482 e., packages that are needed by a required class or package itself (e.
1483 \begin_inset space \thinspace{}
1487 \begin_inset Flex Code
1490 \begin_layout Plain Layout
1497 \begin_inset Flex Code
1500 \begin_layout Plain Layout
1507 Such lower level dependencies constantly change, so they differ between
1508 class and package versions.
1509 Thus, resolving such lower-level dependencies is a task of the respective
1510 package manager of the \SpecialChar LaTeX
1511 distribution (or your operating system).
1513 cannot reliably predict on a general level what a class package needs
1514 (or even what the packages a class need themselves need).
1517 \begin_layout Subsection
1518 Layouts for document classes with incompatible versions
1521 \begin_layout Standard
1522 \begin_inset Note Greyedout
1525 \begin_layout Description
1526 Note: This section is currently only a proposal under discussion.
1527 Please correct/amend as suited.
1528 Remove this note once a consensus is found.
1531 \begin_layout Plain Layout
1533 \begin_inset Quotes eld
1536 Proposal for a guide on updating layouts
1537 \begin_inset Quotes erd
1540 for details and background
1543 \begin_layout Plain Layout
1544 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1552 \begin_layout Standard
1553 Every now and then, there are changes to LaTeX document classes that break
1554 backwards compatibility.
1558 \begin_layout Plain Layout
1559 Uwe has suggested we implement automatic detection of changes in class files.
1560 This could be done by running a script every month that checks if a document
1561 class was changed at CTAN and at the homepages of the scientific journals.
1562 If it reports a change, we can check if our template and layout file are
1563 still usable with the changed document class.
1564 (This is different from the autotests insofar, as this would also catch
1565 changes that do not result in compilation errors.)
1570 Reasons can be a new name for the
1571 \begin_inset Flex Code
1574 \begin_layout Plain Layout
1580 file, removed \SpecialChar LaTeX
1582 How should this best be handled in \SpecialChar LyX
1586 \begin_layout Standard
1587 The idea is to support the new version with a new \SpecialChar LyX
1591 \begin_layout Itemize
1592 Existing documents can still be opened in \SpecialChar LyX
1593 and will continue to work on
1594 systems where the old version is still installed.
1598 \begin_layout Itemize
1599 With differently named
1600 \begin_inset Flex Code
1603 \begin_layout Plain Layout
1609 files, \SpecialChar LyX
1610 can check for the availability of the particular version and reflect
1612 Different document class versions with the same file name are currently
1613 (2.2.x) not detected by the configuration script.
1614 This is planned for 2.3.
1618 \begin_layout Plain Layout
1619 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1622 \begin_layout Plain Layout
1623 However, what we really need is version detection for the configuration,
1624 so that the user can be warned if the required class file has the wrong
1626 (If the class file keeps the name over the version change, only one of
1627 the two layout files generates compilable documents.)
1630 \begin_layout Plain Layout
1631 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1640 \begin_layout Itemize
1641 The new layout can be added both to the master and the stable branches,
1642 in accord with the policy discussed in
1643 \begin_inset CommandInset ref
1644 LatexCommand formatted
1645 reference "subsec:New-layouts"
1650 No lyx2lyx conversion is then required when a new major version is released.
1653 \begin_layout Standard
1654 The user can move an existing document to the new version simply by selecting
1655 a new document class.
1656 This step is well supported by \SpecialChar LyX
1657 , with established methods for handling
1658 unsupported styles and other changes.
1659 This way, no lyx2lyx code is required.
1662 \begin_layout Standard
1663 The steps to support a new version of an existing document class are thus:
1666 \begin_layout Itemize
1667 Create a new layout file including the upstream version in the name (avoid
1668 special characters like spaces and dots), e.g.
1670 \begin_inset Flex Code
1673 \begin_layout Plain Layout
1674 acmsiggraph-v0-92.layout
1682 \begin_layout Itemize
1683 Include the name of the
1684 \begin_inset Flex Code
1687 \begin_layout Plain Layout
1693 file as an optional argument in the
1694 \begin_inset Flex Code
1697 \begin_layout Plain Layout
1705 line and include the version number in the GUI name:
1706 \begin_inset Newline newline
1710 \begin_inset Flex Code
1713 \begin_layout Plain Layout
1716 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1717 \begin_inset space ~
1728 \begin_layout Itemize
1729 Update the GUI name in the old layout file (whose name should not be changed),
1731 \begin_inset Newline newline
1735 \begin_inset Flex Code
1738 \begin_layout Plain Layout
1741 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1742 \begin_inset space ~
1753 \begin_layout Itemize
1754 To avoid duplicate definitions, the new layout can
1755 \begin_inset Flex Code
1758 \begin_layout Plain Layout
1764 the old layout file and add\SpecialChar breakableslash
1765 remove\SpecialChar breakableslash
1766 obsolete\SpecialChar breakableslash
1767 modify settings and styles (similar
1769 \begin_inset Flex Code
1772 \begin_layout Plain Layout
1782 \begin_layout Standard
1783 It may be tempting to let the new layout be the
1784 \begin_inset Quotes eld
1788 \begin_inset Quotes erd
1791 and have the old layout import it.
1792 However, this should not be done because any changes to the new layout
1793 would need undo steps in the importing old layout.
1797 \begin_layout Itemize
1798 If the new LaTeX document class obsoletes the old one, update the example
1799 and template files to use the new layout.
1800 Add a note about the changes (preferably with a pointer to the documentation
1805 \begin_layout Standard
1806 This way, new documents based on the template or example will use the up-to-date
1807 document class version.
1811 \begin_layout Standard
1812 \begin_inset Newpage newpage
1818 \begin_layout Section
1822 \begin_layout Standard
1823 Automated tests are an important tool to detect bugs and regressions in
1824 software development.
1825 Some projects like gcc even require each bug fix to be accompanied by a
1826 test case for the automatic test suite, that would detect this bug.
1827 Testing interactive features automatically is of course very hard, but
1828 core functionality like document import and export can be tested quite
1829 easily, and some tests of this kind exist.
1832 \begin_layout Subsection
1836 \begin_layout Standard
1837 There are attempts to set up a suite of unit tests for LyX.
1840 \begin_layout Standard
1841 TODO: describe what is done and what is still to do.
1844 \begin_layout Subsection
1848 \begin_layout Standard
1849 The tex2lyx tests are located in the
1850 \begin_inset Flex Code
1853 \begin_layout Plain Layout
1859 subfolder of the \SpecialChar LyX
1860 source code distribution.
1861 The actual testing is performed by the simple python script
1862 \begin_inset Flex Code
1865 \begin_layout Plain Layout
1866 src/tex2lyx/test/runtests.py
1872 Each test consists of two files:
1873 \begin_inset Flex Code
1876 \begin_layout Plain Layout
1882 contains the \SpecialChar LaTeX
1883 code that should be tested.
1885 \begin_inset Flex Code
1888 \begin_layout Plain Layout
1894 contains the expected output of tex2lyx.
1895 When a test is run, the actual produced output is compared with the stored
1897 The test passes if both are identical.
1898 The test machinery is also able to generate a file
1899 \begin_inset Flex Code
1902 \begin_layout Plain Layout
1908 by exporting the produced .lyx file with \SpecialChar LyX
1910 This may be useful for roundtrip comparisons.
1913 \begin_layout Subsubsection
1917 \begin_layout Standard
1918 The tex2lyx tests can be run in several ways.
1920 \begin_inset Flex Code
1923 \begin_layout Plain Layout
1929 subfolder of the build directory, the commands
1930 \begin_inset Flex Code
1933 \begin_layout Plain Layout
1939 (cmake, all platforms),
1940 \begin_inset Flex Code
1943 \begin_layout Plain Layout
1949 (cmake, when using a make based build system and not MSVC) or
1950 \begin_inset Flex Code
1953 \begin_layout Plain Layout
1959 (autotools) will run the tex2lyx tests.
1960 Alternatively, in the root of the build directory, the command
1961 \begin_inset Flex Code
1964 \begin_layout Plain Layout
1970 runs all tests whose names match the regex
1971 \begin_inset Quotes eld
1975 \begin_inset Quotes erd
1979 Another way to run the tex2lyx tests in the root build directory is to
1980 instead use the command
1981 \begin_inset Flex Code
1984 \begin_layout Plain Layout
1985 ctest -L '(cmplyx|roundtrip)'
1990 , which runs all tests categorized with the label
1991 \begin_inset Quotes eld
1995 \begin_inset Quotes erd
1999 \begin_inset Quotes eld
2003 \begin_inset Quotes erd
2007 If a test fails, the differences between the expected and actual results
2008 are output in unified diff format.
2011 \begin_layout Subsubsection
2012 Updating test references
2013 \begin_inset CommandInset label
2015 name "sec:Updating-test-references"
2022 \begin_layout Standard
2023 In some cases a changed tex2lyx output is not a test failure, but wanted,
2025 \begin_inset space \thinspace{}
2029 \begin_inset space \space{}
2032 if a tex2lyx bug was fixed, or a new feature was added.
2033 In these cases the stored references need to be updated.
2034 To do so if using autotools, call
2035 \begin_inset Flex Code
2038 \begin_layout Plain Layout
2045 \begin_inset Flex Code
2048 \begin_layout Plain Layout
2054 subdirectory of the build directory.
2055 If instead using CMake, call
2056 \begin_inset Flex Code
2059 \begin_layout Plain Layout
2060 make updatetex2lyxtests
2065 in the build directory or in the
2066 \begin_inset Flex Code
2069 \begin_layout Plain Layout
2075 subdirectory of the build directory.
2079 \begin_layout Plain Layout
2080 Note that this is a case where a make target in the build directory can
2081 affect the source directory, which might not be advisable.
2086 On Windows do the following:
2089 \begin_layout Itemize
2090 Assure that the path to the python.exe is in your system PATH variable.
2093 \begin_layout Itemize
2094 Double-click on the file
2095 \begin_inset Flex Code
2098 \begin_layout Plain Layout
2099 updatetex2lyxtests.vcxproj
2104 in the build directory or in the
2105 \begin_inset Flex Code
2108 \begin_layout Plain Layout
2114 subdirectory of your build directory.
2117 \begin_layout Itemize
2118 In the appearing MSVC program assure that you build the
2122 version, then right-click on the project
2126 in the project explorer and choose then
2129 \begin_inset space ~
2132 Only\SpecialChar menuseparator
2134 \begin_inset space ~
2142 \begin_layout Standard
2143 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2145 Please examine the changed output carefully before committing the changed
2146 files to the repository: Since the test machinery does not do a roundtrip
2148 \begin_inset Formula $\Rightarrow$
2152 \begin_inset Formula $\Rightarrow$
2155 .tex, and does not compare the produced dvi or pdf output, it assumes that
2156 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2158 There is only one chance to detect wrong output: before committing a new
2160 Once it is committed, it is quite difficult to verify whether it is correct.
2163 \begin_layout Standard
2168 update the test references by opening them with \SpecialChar LyX
2169 or directly running lyx2lyx
2171 This would not work, since lyx2lyx and \SpecialChar LyX
2172 produce slightly different files
2173 regarding insignificant whitespace and line breaks.
2176 \begin_layout Subsubsection
2180 \begin_layout Standard
2181 In many cases tests for new features may be added to one of the existing
2182 test files, but sometimes this is not possible or not wanted.
2183 Then a new test file needs to be added:
2186 \begin_layout Enumerate
2188 \begin_inset Flex Code
2191 \begin_layout Plain Layout
2192 src/tex2lyx/test/<test name>.tex
2197 and run tex2lyx in roundtrip mode to produce the file
2198 \begin_inset Flex Code
2201 \begin_layout Plain Layout
2202 src/tex2lyx/test/<test name>.lyx.lyx
2208 This file will be the new reference.
2211 \begin_layout Enumerate
2212 Once you confirmed that the tex2lyx output is correct, add the new files
2213 to the corresponding lists in
2214 \begin_inset Flex Code
2217 \begin_layout Plain Layout
2218 src/tex2lyx/test/runtests.py
2224 \begin_inset Flex Code
2227 \begin_layout Plain Layout
2228 src/tex2lyx/Makefile.am
2234 \begin_inset Flex Code
2237 \begin_layout Plain Layout
2238 src/tex2lyx/test/CMakeLists.txt
2246 \begin_layout Enumerate
2247 Commit the changes to the repository, or send a patch to the development
2248 list and ask for committing if you do not have commit rights.
2251 \begin_layout Subsection
2252 ctest automatic tests
2255 \begin_layout Standard
2256 Some tests are located in the
2257 \begin_inset Flex Code
2260 \begin_layout Plain Layout
2261 development/autotests/
2266 subfolder of the \SpecialChar LyX
2267 source code distribution.
2272 \begin_layout Plain Layout
2273 The README document in this folder only describes the
2274 \begin_inset Quotes eld
2278 \begin_inset Quotes erd
2281 subset of autotests!
2289 \begin_layout Standard
2290 These tests can be run by the commands
2291 \begin_inset Flex Code
2294 \begin_layout Plain Layout
2304 (all platforms) or (when using a make based build system and not MSVC)
2306 \begin_inset Flex Code
2309 \begin_layout Plain Layout
2316 \begin_inset Flex Code
2319 \begin_layout Plain Layout
2330 The test logs are written to the
2331 \begin_inset Flex Code
2334 \begin_layout Plain Layout
2348 \begin_layout Subsubsection
2352 \begin_layout Standard
2353 The export tests are integration tests.
2354 They take longer to run and are more likely to break than the tex2lyx tests.
2355 Nevertheless, they have caught many regressions and without a better alternativ
2356 e it is important to keep them up-to-date and understand how they work.
2359 \begin_layout Standard
2361 \begin_inset Quotes eld
2365 \begin_inset Quotes erd
2368 documentation, template, and example documents.
2369 In addition, there are a number of dedicated sample documents in the
2370 \begin_inset Flex Code
2373 \begin_layout Plain Layout
2379 subfolder of the \SpecialChar LyX
2380 source code distribution.
2381 All samples are (after copying and eventual processing by scripts) exported
2382 to various output formats via the
2383 \begin_inset Flex Code
2386 \begin_layout Plain Layout
2392 command line option.
2393 The tests checks for errors reported by LyX.
2394 (However, error-free export is no guarantee for an error-free output document.)
2397 \begin_layout Paragraph
2398 \begin_inset CommandInset label
2400 name "par:when-to-run-an-export-test"
2404 Expectations of LyX developers
2407 \begin_layout Standard
2408 Because the export tests are integration tests and take a long time to run,
2409 LyX developers are rarely expected to run all of the tests.
2410 Here are some good practices to follow by developers:
2413 \begin_layout Itemize
2414 When making a non-trivial change to a .layout file, run the export and layout
2415 tests corresponding with that .layout file.
2418 \begin_layout Itemize
2419 When making non-trivial changes to a .lyx file, run the export tests correspondin
2420 g to that .lyx file.
2425 \begin_layout Plain Layout
2426 This rule is due to revision.
2430 \begin_layout Plain Layout
2431 There is an objection from the documentation maintainer that working on
2432 the documentation must not be complicated by having to consider non-standard
2436 \begin_layout Itemize
2437 successful compiling/testing an edited documentation file with pdflatex
2438 suffices to ensure it can be commited, not tests with other exports are
2442 \begin_layout Plain Layout
2443 If sudden failures with other exports due to “half-tested” documentation
2444 updates are a problem for the test maintainer, the test suite should use
2448 \begin_layout Itemize
2449 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2452 \begin_layout Itemize
2453 updated regularely (but on a time chosen by the test suite maintainer) from
2454 the originals in lib/doc/
2457 \begin_layout Plain Layout
2461 \begin_layout Itemize
2462 no test will fail due to ongoing work on documentation,
2465 \begin_layout Itemize
2466 the documentation is still tested in full (with some delay),
2469 \begin_layout Itemize
2470 failures with non-default export can be examined and handled accordingly
2471 in one run with the cache update,
2474 \begin_layout Itemize
2475 “interesting failures” (like the nested-language+polyglossia problem in
2476 es/Customization can be separated and moved into dedicated test samples.
2484 \begin_layout Itemize
2485 When making non-trivial changes to LyX's \SpecialChar LaTeX
2487 touching the encoding code or package handling code that you expect will
2488 change the exported \SpecialChar LaTeX
2493 \begin_layout Standard
2494 \paragraph_spacing single
2495 Consider running all of the export tests before and after your change.
2496 If there are differences, please reconcile these (i.e.
2497 fix the bug or fix the tests)
2502 Ask for help if you're not sure what to.
2505 \begin_layout Standard
2506 If you do not want to run the tests,
2509 \begin_layout Itemize
2510 post the patch on the list and others will run the tests and eventually
2514 \begin_layout Itemize
2515 commit, but be prepared to fix eventually arising problems or to revert
2516 the commit if there is no easy fix.
2520 \begin_layout Itemize
2521 Understand how to interpret test failures.
2522 If your commit is found to have broken a test, you should be able to interpret
2523 the test results when made aware of them.
2525 \begin_inset CommandInset ref
2527 reference "subsec:Interpreting-export-tests"
2534 \begin_layout Paragraph
2535 \begin_inset CommandInset label
2537 name "par:export-test-output-formats"
2544 \begin_layout Standard
2545 The following output formats are currently tested for each sample document
2547 \begin_inset CommandInset ref
2549 reference "par:Export-test-filtering"
2556 \begin_layout Labeling
2557 \labelwidthstring 00.00.0000
2562 \begin_layout Labeling
2563 \labelwidthstring 00.00.0000
2564 lyx16 LyX 1.6 file format (lyx2lyx)
2567 \begin_layout Labeling
2568 \labelwidthstring 00.00.0000
2569 lyx21 LyX 2.1 file format (lyx2lyx)
2572 \begin_layout Labeling
2573 \labelwidthstring 00.00.0000
2574 xhtml LyXHTML (native LyX HTML export)
2578 \begin_layout Labeling
2579 \labelwidthstring 00.00.0000
2581 \begin_inset space ~
2585 \begin_inset space ~
2592 \begin_layout Labeling
2593 \labelwidthstring pdf5msystemFM
2594 dvi DVI (8-bit latex)
2597 \begin_layout Labeling
2598 \labelwidthstring pdf5msystemFM
2599 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2602 \begin_layout Labeling
2603 \labelwidthstring pdf5msystemFM
2604 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2607 \begin_layout Labeling
2608 \labelwidthstring pdf5msystemFM
2612 \begin_layout Labeling
2613 \labelwidthstring pdf5msystemFM
2614 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2617 \begin_layout Labeling
2618 \labelwidthstring pdf5msystemFM
2619 pdf4_systemF PDF (XeTeX with Unicode fonts)
2622 \begin_layout Labeling
2623 \labelwidthstring pdf5msystemFM
2624 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2627 \begin_layout Labeling
2628 \labelwidthstring pdf5msystemFM
2629 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2633 \begin_layout Labeling
2634 \labelwidthstring 00.00.0000
2636 \begin_inset space ~
2640 \begin_inset space ~
2644 \begin_inset space ~
2648 \begin_inset space ~
2655 \begin_layout Labeling
2656 \labelwidthstring pdf5msystemFM
2657 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2660 \begin_layout Labeling
2661 \labelwidthstring pdf5msystemFM
2662 pdf3 DVI -> PDF (dvipdfm)
2666 \begin_layout Labeling
2667 \labelwidthstring 00.00.0000
2669 \begin_inset space ~
2672 tested: (or only if set as default output format in the document source)
2676 \begin_layout Labeling
2677 \labelwidthstring pdf5msystemFM
2681 \begin_layout Labeling
2682 \labelwidthstring pdf5msystemFM
2683 luatex LaTeX (LuaTeX)
2686 \begin_layout Labeling
2687 \labelwidthstring pdf5msystemFM
2688 dviluatex LaTeX (dviluatex)
2691 \begin_layout Labeling
2692 \labelwidthstring pdf5msystemFM
2693 pdflatex LaTeX (pdflatex)
2696 \begin_layout Labeling
2697 \labelwidthstring pdf5msystemFM
2698 platex LaTeX (pLaTeX)
2701 \begin_layout Labeling
2702 \labelwidthstring pdf5msystemFM
2706 \begin_layout Labeling
2707 \labelwidthstring pdf5msystemFM
2708 eps3 EPS (encapsulated Postscript) (cropped)
2711 \begin_layout Labeling
2712 \labelwidthstring pdf5msystemFM
2713 ps DVI -> Postscript (dvips)
2716 \begin_layout Labeling
2717 \labelwidthstring pdf5msystemFM
2721 \begin_layout Labeling
2722 \labelwidthstring pdf5msystemFM
2723 text (nor text2, ..., text4)
2726 \begin_layout Labeling
2727 \labelwidthstring pdf5msystemFM
2731 \begin_layout Labeling
2732 \labelwidthstring pdf5msystemFM
2736 \begin_layout Labeling
2737 \labelwidthstring pdf5msystemFM
2741 \begin_layout Labeling
2742 \labelwidthstring pdf5msystemFM
2747 \begin_layout Paragraph
2748 \begin_inset CommandInset label
2750 name "par:Configuring-ctests"
2754 Configuring the tests
2757 \begin_layout Standard
2758 To enable the export autotests, add the
2759 \begin_inset Flex Code
2762 \begin_layout Plain Layout
2763 -DLYX_ENABLE_EXPORT_TESTS=ON
2772 \begin_layout Standard
2773 \begin_inset Flex Code
2776 \begin_layout Plain Layout
2777 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2785 \begin_layout Standard
2787 This flag will increase the time for the cmake command by several seconds,
2788 mainly because of the process of inverting tests (see Section
2789 \begin_inset CommandInset ref
2791 reference "subsec:Interpreting-export-tests"
2798 \begin_layout Paragraph
2799 \begin_inset CommandInset label
2801 name "par:ctest-options"
2808 \begin_layout Standard
2809 To run all tests, in the build directory simply run the command
2810 \begin_inset Flex Code
2813 \begin_layout Plain Layout
2820 A full, up-to-date TeXLive installation is recommended to run the tests.
2821 Otherwise, some tests will fail.
2822 Tests with additional requirements are labeled
2823 \begin_inset Quotes eld
2826 unreliable:nonstandard
2827 \begin_inset Quotes erd
2834 \begin_layout Standard
2835 To run only some of the tests, use command line options (see examples below):
2838 \begin_layout Labeling
2839 \labelwidthstring -R
2840 \begin_inset Flex Code
2843 \begin_layout Plain Layout
2849 Run only the tests whose names match the given regular expression.
2852 \begin_layout Labeling
2853 \labelwidthstring -R
2854 \begin_inset Flex Code
2857 \begin_layout Plain Layout
2863 Run only the tests whose labels match the given regular expression.
2864 A test may have more that one label.
2868 \begin_layout Labeling
2869 \labelwidthstring -R
2870 \begin_inset Flex Code
2873 \begin_layout Plain Layout
2879 Exclude the tests whose names match the given regular expression.
2882 \begin_layout Labeling
2883 \labelwidthstring -R
2884 \begin_inset Flex Code
2887 \begin_layout Plain Layout
2893 Exclude the tests whose labels match the given regular expression.
2894 Cannot be combined with
2895 \begin_inset Flex Code
2898 \begin_layout Plain Layout
2907 \begin_layout Standard
2908 The following options help to find good selection patterns:
2911 \begin_layout Labeling
2912 \labelwidthstring -R
2913 \begin_inset Flex Code
2916 \begin_layout Plain Layout
2922 List the tests that would be run but not actually run them.
2927 \begin_layout Standard
2928 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2929 to know how many tests there are or whether your
2930 \begin_inset Flex Code
2933 \begin_layout Plain Layout
2939 regular expression did what you expected.
2943 \begin_layout Labeling
2944 \labelwidthstring -R
2945 \begin_inset Flex Code
2948 \begin_layout Plain Layout
2949 \SpecialChar nobreakdash
2950 \SpecialChar nobreakdash
2956 print the list of all labels associated with the test set.
2957 Can also be combined with -R, -L, -E, ...
2961 \begin_layout Standard
2962 Other useful options are:
2965 \begin_layout Labeling
2966 \labelwidthstring -R
2967 \begin_inset Flex Code
2970 \begin_layout Plain Layout
2976 Run the tests in parallel using the given number of jobs.
2980 \begin_layout Standard
2981 We are still working on getting the tests to run in parallel.
2982 However, when running the tests in parallel, sometimes tests fail that
2983 pass when run sequentially.
2984 A reasonable approach is to first run the tests in parallel and then run
2985 the failed tests sequentially.
2988 \begin_layout Standard
2989 For example, to run 8 jobs at a time:
2992 \begin_layout Standard
2993 \begin_inset Flex Code
2996 \begin_layout Plain Layout
3005 \begin_layout Standard
3006 \begin_inset Flex Code
3009 \begin_layout Plain Layout
3010 ctest \SpecialChar nobreakdash
3011 \SpecialChar nobreakdash
3020 \begin_layout Standard
3021 When specifying a subset of the tests (e.g.
3023 \begin_inset Flex Code
3026 \begin_layout Plain Layout
3027 \SpecialChar nobreakdash
3033 ), the same subset must be specified when using the
3034 \begin_inset Flex Code
3037 \begin_layout Plain Layout
3038 \SpecialChar nobreakdash
3039 \SpecialChar nobreakdash
3045 option because it is the test numbers that are used to index which tests
3046 failed on the previous run.
3049 \begin_layout Standard
3051 Note that some tests cannot be run in parallel.
3052 These tests are marked in the code with the
3053 \begin_inset Flex Code
3056 \begin_layout Plain Layout
3067 \begin_layout Labeling
3068 \labelwidthstring -R
3069 \begin_inset Flex Code
3072 \begin_layout Plain Layout
3073 \SpecialChar nobreakdash
3074 \SpecialChar nobreakdash
3080 Set a global timeout on all tests that do not already have a timeout set
3085 \begin_layout Standard
3086 There have been bugs in LyX and in \SpecialChar LaTeX
3087 which cause compilation to hang, and
3088 without a timeout a test might never stop (in one case there was even a
3090 If a test times out, the
3091 \begin_inset Flex Code
3094 \begin_layout Plain Layout
3100 command exits with error, but you can distinguish between a timed out test
3101 and a failed test in the output reported at the end of the
3102 \begin_inset Flex Code
3105 \begin_layout Plain Layout
3115 \begin_layout Standard
3117 \begin_inset Flex Code
3120 \begin_layout Plain Layout
3126 ) the full list of command line options.
3129 \begin_layout Paragraph
3133 \begin_layout Itemize
3134 run only the export tests:
3135 \begin_inset Flex Code
3138 \begin_layout Plain Layout
3147 \begin_layout Itemize
3149 \begin_inset Flex Code
3152 \begin_layout Plain Layout
3153 ctest -L "inverted|suspended"
3161 \begin_layout Itemize
3162 list all export tests which match any of the labelling patterns:
3163 \begin_inset Flex Code
3166 \begin_layout Plain Layout
3177 \begin_layout Itemize
3178 exclude rarely used output formats and post-processing tests
3179 \begin_inset Flex Code
3182 \begin_layout Plain Layout
3183 ctest -L export -E "_(texF|dvi3|pdf3?)"
3191 \begin_layout Paragraph
3192 \begin_inset CommandInset label
3194 name "subsec:Interpreting-export-tests"
3198 Interpreting the export test results
3201 \begin_layout Standard
3202 A test can fail for several reasons, not all of them bad.
3205 \begin_layout Enumerate
3206 A new or edited sample document may be incompatible with some output formats.
3209 \begin_layout Enumerate
3210 A dependency is not met (e.g.
3211 the \SpecialChar LaTeX
3213 One hint that this is the case is that the corresponding
3214 \begin_inset Flex Code
3217 \begin_layout Plain Layout
3223 test will likely also fail.
3226 \begin_layout Enumerate
3227 An inverted test fails to fail (i.e.
3228 export that previously failed now works).
3231 \begin_layout Enumerate
3232 An external dependency was updated (e.g.
3237 \begin_layout Enumerate
3238 A recent code change introduced a bug.
3241 \begin_layout Enumerate
3242 \begin_inset CommandInset label
3248 A change in a document exposed a previously unknown bug or an incompatibility
3249 with an export format (e.g.
3250 Lua\SpecialChar LaTeX
3254 \begin_layout Standard
3255 Because the .lyx files are exported in several formats, it is not surprising
3256 that many of the exports fail.
3257 This expectation of failure is addressed by
3258 \begin_inset Quotes eld
3262 \begin_inset Quotes erd
3265 the tests, that is, by marking the test as
3266 \begin_inset Quotes eld
3270 \begin_inset Quotes erd
3273 if the export exits with error and as
3274 \begin_inset Quotes eld
3278 \begin_inset Quotes erd
3281 if the export succeeds
3286 It follows that these expected failures will not show up as failed tests
3287 in the test results and thus will not pollute the
3288 \begin_inset Quotes eld
3292 \begin_inset Quotes erd
3296 If the export actually succeeds, then the test will fail.
3297 The purpose of this failure is to get your attention—something has changed,
3298 possibly for the better.
3301 \begin_layout Standard
3302 We try to document why a test is inverted or ignored.
3303 See the comment (prefixed with
3304 \begin_inset Flex Code
3307 \begin_layout Plain Layout
3313 ) above the block in which the test is listed as inverted or ignored in
3315 \begin_inset Flex Code
3318 \begin_layout Plain Layout
3319 development/autotests/invertedTests
3325 \begin_inset Flex Code
3328 \begin_layout Plain Layout
3329 development/autotests/unreliableTests
3335 \begin_inset Flex Code
3338 \begin_layout Plain Layout
3339 development/autotests/ignoredTests
3348 \begin_layout Standard
3349 A good question is why do we enable the tests for non-default formats? The
3350 answer is that if a non-default route is broken it is often because a bug
3351 was introduced in LyX and not because a document-specific change was made
3352 that is not supported by the route.
3353 In other words, there is a high signal/noise ratio in the export tests
3354 for some non-default formats.
3358 \begin_layout Standard
3359 When a test or several tests fail, consider checking the files in the
3360 \begin_inset Flex Code
3363 \begin_layout Plain Layout
3369 subdirectory of your build directory.
3370 In this subdirectory are three files: the file
3371 \begin_inset Flex Code
3374 \begin_layout Plain Layout
3380 simply lists the tests that failed on your last
3381 \begin_inset Flex Code
3384 \begin_layout Plain Layout
3391 \begin_inset Flex Code
3394 \begin_layout Plain Layout
3400 file contains the output from the tests (and often has details explaining
3401 why a test failed); and the
3402 \begin_inset Flex Code
3405 \begin_layout Plain Layout
3411 file lists the times that it took to run the tests.
3414 \begin_layout Paragraph
3415 What action should you take if a test fails?
3418 \begin_layout Standard
3419 \paragraph_spacing single
3420 It is always good to check manually why something fails and if it passes
3421 if the PDF output is good.
3424 \begin_layout Itemize
3425 Generally, if a change breaks compilation for the target format (for the
3426 manuals pdf2) without solving some important other issue,
3428 fix or revert the commit
3430 that led to failure.
3433 \begin_layout Itemize
3434 If it is not possible to (immediately) fix the failure but there are reasons
3435 not to revert the commit (e.g.
3436 it fixes another more important issue),
3440 the failing test case (see
3441 \begin_inset CommandInset ref
3443 reference "par:Inverted-tests"
3450 \begin_layout Itemize
3455 test case fails because the export now works,
3459 the test by removing the pattern from the
3460 \begin_inset Quotes eld
3464 \begin_inset Quotes erd
3468 \begin_inset CommandInset ref
3470 reference "par:Inverted-tests"
3477 \begin_layout Itemize
3478 If the export did not fail previously but led to wrong output (PDF, say),
3482 \begin_layout Plain Layout
3483 Non-failing test with wrong output should be labeled as
3484 \begin_inset Quotes eld
3487 unreliable:wrong_output
3488 \begin_inset Quotes erd
3492 \begin_inset CommandInset ref
3494 reference "par:Unreliable-tests"
3503 it is in fact an improvement when the test now fails.
3508 the failing test case (see
3509 \begin_inset CommandInset ref
3511 reference "par:Inverted-tests"
3518 \begin_layout Itemize
3519 In case of tests failing due to missing requirements (tests labeled
3520 \begin_inset Quotes eld
3523 unreliable:nonstandard
3524 \begin_inset Quotes erd
3527 or testing on a system with only a subset of TeXLive installed), ignore
3528 the failure, ask for someone else to run the test, or install the missing
3529 resources and try again.
3532 \begin_layout Itemize
3533 Check the log file Testing/Temporary/LastTest.log.
3534 In case of latex-errors rerun the failing test with environment variable
3535 'LYX_DEBUG_LATEX' set to '1'.
3536 This will include latex messages in LastTest.log, so it should be easier
3537 to interpret the fail-reason.
3540 \begin_layout Paragraph
3541 \begin_inset CommandInset label
3543 name "par:Inverted-tests"
3550 \begin_layout Standard
3551 Test cases whose name matches a pattern in the file
3552 \begin_inset Flex Code
3555 \begin_layout Plain Layout
3556 development/autotests/invertedTests
3566 They get also the test property
3567 \begin_inset Flex Code
3570 \begin_layout Plain Layout
3577 they are reported as failing if the export works without error
3578 \begin_inset Flex URL
3581 \begin_layout Plain Layout
3583 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3591 \begin_layout Standard
3592 Add failing cases to this file, if they cannot be solved
3593 \begin_inset Quotes eld
3597 \begin_inset Quotes erd
3600 but it is expected that the export will work in a foreseeable future, e.g.
3601 low priority issues like failures to export to a non-target format (for
3602 the manuals everything except pdf2).
3605 \begin_layout Standard
3606 The following sublabels are currently present in
3607 \begin_inset Flex Code
3610 \begin_layout Plain Layout
3619 \begin_layout Description
3620 todo test failures that require attention:
3624 \begin_layout Itemize
3625 minor issues to explore and properly sort later,
3628 \begin_layout Itemize
3632 \begin_layout Itemize
3633 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3637 \begin_layout Description
3638 lyxbugs LyX bugs with a Trac number.
3641 \begin_layout Description
3642 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3646 \begin_layout Standard
3647 "Wontfix" if demonstrating correct use and OK in the default output format.
3651 \begin_layout Description
3652 texissues Export fails due to LaTeX limitations like non-ASCII characters
3653 in verbatim or listings, incompatible packages, ...
3657 \begin_layout Standard
3658 "Wontfix" if documents demonstrate correct use in the default output format:
3661 \begin_layout Itemize
3662 If the source can be made more robust without becoming "hackish", fix the
3666 \begin_layout Itemize
3667 if LyX could be enhanced to care for a permanent TeX limitation, file a
3668 ticket at trac and add a pattern under lyxbugs,
3671 \begin_layout Itemize
3672 otherwise, add a pattern here.
3676 \begin_layout Description
3677 attic Documents in the attic (kept for reference and format conversion test).
3679 \begin_inset Quotes eld
3683 \begin_inset Quotes erd
3689 \begin_layout Subparagraph
3693 \begin_layout Standard
3694 Test cases whose name additionally matches a pattern in the file
3695 \begin_inset Flex Code
3698 \begin_layout Plain Layout
3699 development/autotests/suspendedTests
3717 This means they are not executed using
3718 \begin_inset Flex Code
3721 \begin_layout Plain Layout
3728 \begin_inset Flex Code
3731 \begin_layout Plain Layout
3738 However, they also get the test property
3739 \begin_inset Flex Code
3742 \begin_layout Plain Layout
3749 they are reported as failing if the export works without error.
3750 From time to time they still have to be checked using
3751 \begin_inset Flex Code
3754 \begin_layout Plain Layout
3763 \begin_layout Standard
3764 These tests are suspended, because the export fails for known reasons which
3765 cannot ATM be resolved.
3766 But it is expected the reason might disappear in the future.
3767 Be it new TL or better handling in \SpecialChar LyX
3771 \begin_layout Standard
3772 For ctest commands without the
3773 \begin_inset Flex Code
3776 \begin_layout Plain Layout
3782 parameter nothing changes.
3783 Suspended or not, tests will be executed depending only on the selecting
3784 regular expression given to the ctest command (see
3785 \begin_inset CommandInset ref
3787 reference "par:ctest-options"
3794 \begin_layout Paragraph
3795 \begin_inset CommandInset label
3797 name "par:Unreliable-tests"
3804 \begin_layout Standard
3805 Test cases whose name matches a pattern in the file
3806 \begin_inset Flex Code
3809 \begin_layout Plain Layout
3810 development/autotests/unreliableTests
3822 \begin_layout Standard
3823 These tests are not executed using
3824 \begin_inset Flex Code
3827 \begin_layout Plain Layout
3834 \begin_inset Flex Code
3837 \begin_layout Plain Layout
3847 \begin_layout Standard
3848 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3849 or pass but should rather fail (wrong output).
3851 \begin_inset Note Note
3854 \begin_layout Plain Layout
3855 *invalid* tests (wrong output) are not *unreliable*.
3856 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3865 \begin_layout Standard
3866 The following sublabels are currently present in
3867 \begin_inset Flex Code
3870 \begin_layout Plain Layout
3879 \begin_layout Description
3880 nonstandard Documents with additional requirements, e.g.
3881 a class or package file not in TeXLive.
3883 \begin_inset Note Note
3886 \begin_layout Plain Layout
3888 \begin_inset Quotes eld
3892 \begin_inset Quotes erd
3896 \begin_inset Quotes eld
3900 \begin_inset Quotes erd
3911 \begin_layout Description
3912 erratic Tests depending on local configuration or the phase of the moon.
3916 \begin_layout Description
3917 varying_versions Tests depending on e.g.
3918 OS or version of a non-TeX-Live dependency.
3919 Note that a full, up-to-date TeX Live installation is required so this
3920 sublabel is about versions of other dependencies.
3923 \begin_layout Description
3925 \begin_inset space ~
3928 output Export does not fail but the resulting document has (undetected)
3933 \begin_layout Standard
3934 \paragraph_spacing single
3935 \begin_inset Note Note
3938 \begin_layout Plain Layout
3939 \paragraph_spacing single
3940 These tests are in a strict sense not unreliable but
3944 (not measuring what they should measure).
3953 \begin_layout Paragraph
3954 \begin_inset CommandInset label
3956 name "par:Export-test-filtering"
3960 Export test filtering
3963 \begin_layout Standard
3964 The assignment of a label to a test is controlled by a set of files with
3965 regular expressions that are matched against the test names.
3968 \begin_layout Description
3969 ignoredTests (small file)
3970 \begin_inset Newline newline
3973 Tests selected here are withdrawn in the configuration step (cf.
3975 \begin_inset CommandInset ref
3977 reference "par:Configuring-ctests"
3985 \begin_layout Labeling
3986 \labelwidthstring 00.00.0000
3987 Input Test of any export combination
3990 \begin_layout Labeling
3991 \labelwidthstring 00.00.0000
3992 Output Stop if tests not selected here
3996 \begin_layout Description
3997 unreliableTests: Tests selected pass or fail dependent on the system where
3999 Selected tests gain the label 'unreliable'.
4003 \begin_layout Labeling
4004 \labelwidthstring 00.00.0000
4005 Input Each test which passed 'ignoredTests'
4008 \begin_layout Labeling
4009 \labelwidthstring 00.00.0000
4010 Output Gain label 'unreliable', proceed with checking for 'inverted'.
4014 \begin_layout Description
4016 \begin_inset space \space{}
4023 \begin_layout Labeling
4024 \labelwidthstring 00.00.0000
4025 Input Each test which passed 'ignoredTests'
4028 \begin_layout Labeling
4029 \labelwidthstring 00.00.0000
4030 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
4031 tests are reported as failing if the export works without error.) If no
4032 subselection applies, gain labels 'export' and 'inverted'.
4035 \begin_layout Standard
4036 The following filter perfoms a subselection of 'invertedTests':
4039 \begin_layout Description
4040 suspendedTests Tests selected here gain the label 'suspended' but _not_
4041 'export' or 'inverted', although in ctest they remain inverted.
4042 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
4046 \begin_layout Labeling
4047 \labelwidthstring 00.00.0000
4048 Input Each test selected by 'invertedTests'
4051 \begin_layout Labeling
4052 \labelwidthstring 00.00.0000
4053 Output Selected test gains label 'suspended'.
4059 \begin_layout Standard
4060 The following table may clarify label assignement
4063 \begin_layout Standard
4064 \begin_inset space \hspace{}
4069 \begin_inset Tabular
4070 <lyxtabular version="3" rows="6" columns="8">
4071 <features tabularvalignment="middle">
4072 <column alignment="left" valignment="top" width="2cm">
4073 <column alignment="left" valignment="top" width="2.5cm">
4074 <column alignment="left" valignment="top" width="2cm">
4075 <column alignment="center" valignment="top" width="2.5cm">
4076 <column alignment="center" valignment="top">
4077 <column alignment="center" valignment="top">
4078 <column alignment="center" valignment="top">
4079 <column alignment="center" valignment="top">
4081 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4084 \begin_layout Plain Layout
4085 Test matching pattern in file:
4090 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4093 \begin_layout Plain Layout
4099 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4102 \begin_layout Plain Layout
4108 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4111 \begin_layout Plain Layout
4117 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4120 \begin_layout Plain Layout
4126 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4129 \begin_layout Plain Layout
4135 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4138 \begin_layout Plain Layout
4144 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4147 \begin_layout Plain Layout
4155 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4158 \begin_layout Plain Layout
4159 ignored\SpecialChar softhyphen
4165 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4168 \begin_layout Plain Layout
4169 unreliable\SpecialChar softhyphen
4175 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4178 \begin_layout Plain Layout
4179 inverted\SpecialChar softhyphen
4185 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4188 \begin_layout Plain Layout
4189 suspended\SpecialChar softhyphen
4195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4198 \begin_layout Plain Layout
4204 <cell alignment="center" valignment="top" topline="true" usebox="none">
4207 \begin_layout Plain Layout
4213 <cell alignment="center" valignment="top" topline="true" usebox="none">
4216 \begin_layout Plain Layout
4222 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4225 \begin_layout Plain Layout
4233 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4236 \begin_layout Plain Layout
4242 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4245 \begin_layout Plain Layout
4251 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4254 \begin_layout Plain Layout
4260 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4263 \begin_layout Plain Layout
4269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4272 \begin_layout Plain Layout
4278 <cell alignment="center" valignment="top" topline="true" usebox="none">
4281 \begin_layout Plain Layout
4287 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4290 \begin_layout Plain Layout
4296 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4299 \begin_layout Plain Layout
4307 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4310 \begin_layout Plain Layout
4316 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4319 \begin_layout Plain Layout
4321 \begin_inset Newline newline
4325 \begin_inset Newline newline
4333 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4336 \begin_layout Plain Layout
4342 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4345 \begin_layout Plain Layout
4351 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4354 \begin_layout Plain Layout
4360 <cell alignment="center" valignment="top" topline="true" usebox="none">
4363 \begin_layout Plain Layout
4369 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4372 \begin_layout Plain Layout
4378 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4381 \begin_layout Plain Layout
4389 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4392 \begin_layout Plain Layout
4398 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4401 \begin_layout Plain Layout
4407 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4410 \begin_layout Plain Layout
4416 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4419 \begin_layout Plain Layout
4425 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4428 \begin_layout Plain Layout
4434 <cell alignment="center" valignment="top" topline="true" usebox="none">
4437 \begin_layout Plain Layout
4443 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4446 \begin_layout Plain Layout
4452 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4455 \begin_layout Plain Layout
4463 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4466 \begin_layout Plain Layout
4472 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4475 \begin_layout Plain Layout
4481 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4484 \begin_layout Plain Layout
4490 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4493 \begin_layout Plain Layout
4499 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4502 \begin_layout Plain Layout
4508 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4511 \begin_layout Plain Layout
4517 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4520 \begin_layout Plain Layout
4526 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4529 \begin_layout Plain Layout
4543 \begin_layout Standard
4544 \begin_inset Note Note
4547 \begin_layout Plain Layout
4549 \begin_inset Quotes eld
4553 \begin_inset Quotes erd
4556 filter, this would be far less complicated:
4559 \begin_layout Plain Layout
4560 \begin_inset Tabular
4561 <lyxtabular version="3" rows="6" columns="7">
4562 <features tabularvalignment="middle">
4563 <column alignment="left" valignment="top" width="0pt">
4564 <column alignment="left" valignment="top" width="0pt">
4565 <column alignment="left" valignment="top" width="0pt">
4566 <column alignment="center" valignment="top">
4567 <column alignment="center" valignment="top">
4568 <column alignment="center" valignment="top">
4569 <column alignment="center" valignment="top">
4571 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4574 \begin_layout Plain Layout
4575 Test matching pattern in file:
4580 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4583 \begin_layout Plain Layout
4589 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4592 \begin_layout Plain Layout
4598 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4601 \begin_layout Plain Layout
4607 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4610 \begin_layout Plain Layout
4616 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4619 \begin_layout Plain Layout
4625 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4628 \begin_layout Plain Layout
4636 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4639 \begin_layout Plain Layout
4645 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4648 \begin_layout Plain Layout
4654 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4657 \begin_layout Plain Layout
4663 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4666 \begin_layout Plain Layout
4672 <cell alignment="center" valignment="top" topline="true" usebox="none">
4675 \begin_layout Plain Layout
4681 <cell alignment="center" valignment="top" topline="true" usebox="none">
4684 \begin_layout Plain Layout
4690 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4693 \begin_layout Plain Layout
4701 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4704 \begin_layout Plain Layout
4710 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4713 \begin_layout Plain Layout
4719 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4722 \begin_layout Plain Layout
4728 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4731 \begin_layout Plain Layout
4737 <cell alignment="center" valignment="top" topline="true" usebox="none">
4740 \begin_layout Plain Layout
4746 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4749 \begin_layout Plain Layout
4755 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4758 \begin_layout Plain Layout
4766 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4769 \begin_layout Plain Layout
4775 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4778 \begin_layout Plain Layout
4784 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4787 \begin_layout Plain Layout
4793 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4796 \begin_layout Plain Layout
4802 <cell alignment="center" valignment="top" topline="true" usebox="none">
4805 \begin_layout Plain Layout
4811 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4814 \begin_layout Plain Layout
4820 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4823 \begin_layout Plain Layout
4831 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4834 \begin_layout Plain Layout
4840 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4843 \begin_layout Plain Layout
4849 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4852 \begin_layout Plain Layout
4858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4861 \begin_layout Plain Layout
4867 <cell alignment="center" valignment="top" topline="true" usebox="none">
4870 \begin_layout Plain Layout
4876 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4879 \begin_layout Plain Layout
4885 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4888 \begin_layout Plain Layout
4896 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4899 \begin_layout Plain Layout
4905 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4908 \begin_layout Plain Layout
4914 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4917 \begin_layout Plain Layout
4923 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4926 \begin_layout Plain Layout
4932 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4935 \begin_layout Plain Layout
4941 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4944 \begin_layout Plain Layout
4950 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4953 \begin_layout Plain Layout
4972 \begin_layout Subsubsection
4976 \begin_layout Standard
4977 These tests check whether a .lyx file loads without any terminal messages.
4978 They correspond to the manual operations of simply opening a .lyx file on
4979 the terminal, exiting LyX once the file is loaded, and then checking whether
4980 there is any output from the terminal.
4981 These tests are useful for catching malformed .lyx files and parsing bugs.
4982 They can also be used to find a .lyx file in which an instance of something
4984 To do this, compile LyX with a local patch that outputs something to the
4985 terminal when an instance is found, and then run the check_load tests to
4986 see if any fail, which would mean that the situation occurs in the LyX
4987 documentation files corresponding to the failed tests.
4988 These tests are expectedly fragile: any LyX diagnostic message, which is
4989 not necessarily an error, would cause the tests to fail.
4990 Similarly, any message output by a library (e.g.
4991 Qt) would also cause failure.
4992 There are some messages that the check_load tests are instructed to ignore,
4993 which are stored in the file
4994 \begin_inset Flex Code
4997 \begin_layout Plain Layout
4998 development/autotests/filterCheckWarnings
5006 \begin_layout Standard
5007 Under cmake, the tests are labeled as 'load'.
5010 \begin_layout Subsubsection
5014 \begin_layout Standard
5015 Automated tests based on the "MonKey Testing" keytest program are enabled
5016 if the necessary dependencies are found and if the CMake flag
5017 \begin_inset Flex Code
5020 \begin_layout Plain Layout
5021 -DLYX_ENABLE_KEYTESTS=ON
5027 They are documented in the README document in
5028 \begin_inset Flex Code
5031 \begin_layout Plain Layout
5032 development/autotests
5037 subfolder of the \SpecialChar LyX
5038 source code distribution.
5041 \begin_layout Subsubsection
5045 \begin_layout Standard
5046 These tests combine lyx2lyx tests with check_load tests.
5047 They fail if either fails.
5050 \begin_layout Subsubsection
5054 \begin_layout Standard
5055 The URL tests are enabled with the
5056 \begin_inset Flex Code
5059 \begin_layout Plain Layout
5060 -DLYX_ENABLE_URLTESTS=ON
5065 CMake flag and are useful for finding broken links in our documentation
5067 If a URL test fails, to see which link in particular was reported as broken,
5069 \begin_inset Flex Code
5072 \begin_layout Plain Layout
5079 These tests are extremely fragile (e.g.
5080 a test can depend on your Internet connection) and a failed URL test should
5081 not be taken too seriously.
5082 URL tests are labeled as
5087 \begin_layout Paragraph
5091 \begin_layout Standard
5092 cmake is required to run the \SpecialChar LyX
5093 tests, running them is not implemented for
5097 \begin_layout Standard
5098 The appropriate commands are:
5101 \begin_layout Itemize
5107 \begin_inset Newline newline
5110 runs all tests with label
5115 \begin_layout Itemize
5118 ctest -R 'check_.*urls'
5121 \begin_inset Newline newline
5124 runs the tests 'check_accessible_urls'
5127 \begin_layout Standard
5128 Associated test results can be examined in ctest-log directory in files
5129 of the form 'LastFailed.*URLS.log'
5132 \begin_layout Section
5133 Development policies
5136 \begin_layout Standard
5137 This chapter lists some guidelines that should be followed.
5138 This list is not complete, and many guidelines are in separate chapters,
5140 \begin_inset Quotes eld
5143 When is an update of the .lyx file format number needed?
5144 \begin_inset Quotes erd
5148 \begin_inset CommandInset ref
5150 reference "sec:When-is-an"
5157 \begin_layout Subsection
5158 When to set a fixed milestone?
5161 \begin_layout Standard
5162 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5166 \begin_layout Enumerate
5167 Somebody is actively working on a fix.
5170 \begin_layout Enumerate
5171 The bug is so severe that it would block the release if it is not fixed.
5174 \begin_layout Standard
5175 If a bug is important, but nobody is working on it, and it is no showstopper,
5176 use a milestone like 2.1.x or 2.2.x.
5177 For all other bugs, do not set a milestone at all.
5180 \begin_layout Subsection
5181 Can we add rc entries in stable branch?
5184 \begin_layout Standard
5186 We are supposed to increase the prefs2prefs version number with such things.
5189 \begin_layout Section
5190 \begin_inset CommandInset label
5192 name "sec:Documentation-policies"
5196 Documentation policies
5199 \begin_layout Subsection
5203 \begin_layout Standard
5205 \begin_inset space ~
5208 rules in editing the docs:
5211 \begin_layout Enumerate
5212 \begin_inset CommandInset label
5214 name "enu:If-you-are"
5218 If you are not the maintainer of a doc file or a chapter/section, you MUST
5219 use change tracking so that the maintainer could review your changes
5222 \begin_layout Enumerate
5223 Respect the formatting of the document.
5224 The different files use different formatting styles.
5225 That is OK and has historic reasons nobody fully knows ;-).
5226 But it is important to be consistent within one file.
5229 \begin_layout Enumerate
5230 All changes you make to a file in one language MUST also go the file in
5231 the other actively maintained languages.
5232 Normally the maintainer does this for you, if you are the maintainer, you
5233 must do this by copying or changing the changed or added text to the other
5234 files so that the translators sees the blue underlined text and know what
5235 they have to translate and what was changed.
5238 \begin_layout Enumerate
5239 You MUST assure that the document is compilable as
5240 \begin_inset Quotes eld
5244 \begin_inset Quotes erd
5247 or the document's default output format after your changes.
5250 \begin_layout Enumerate
5251 All fixes (typos, compilation fixes, updates info etc.) go at first into
5252 the current GIT branch because the user should benefit from all fixes with
5253 every minor release.
5254 Feel free to commit directly to branch as long as you follow rule
5255 \begin_inset space ~
5259 \begin_inset CommandInset ref
5261 reference "enu:If-you-are"
5266 You can immediately commit to master as well.
5269 \begin_layout Enumerate
5270 \begin_inset CommandInset label
5272 name "enu:The-fileformat-of"
5276 The fileformat of a file must not be changed unless you document a new feature
5277 in LyX that requires a new fileformat.
5278 The reason for this rule is to keep it easy for the doc maintainers to
5279 port/backport changes to from master/branch.
5282 \begin_layout Standard
5283 The main documentation consists of these files:
5286 \begin_layout Description
5287 splash.lyx it is the first file you see after an installation.
5288 We assume that a new user sees this.
5289 It is therefore designed to be as simple as possible.
5290 Therefore please don't add any new formatting, only fix typos etc.
5291 Splash.lyx is up to date for \SpecialChar LyX
5292 2.1.x, currently maintained by Uwe Stöhr.
5295 \begin_layout Description
5296 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5298 It therefore uses a limited set of formatting.
5299 For example a standard document class.
5300 Since new users will first learn about the formatting possibilities of
5302 please keep this file that simple.
5303 Intro.lyx is up to date for \SpecialChar LyX
5304 2.1.x, currently maintained by Uwe Stöhr.
5307 \begin_layout Description
5308 Tutorial.lyx our tutorial.
5309 It must be always up to date.
5310 Normally there is nothing to add since we don't want to overwhelm new users
5311 with too much details.
5312 The will learn these details while using \SpecialChar LyX
5313 and we have special manuals.
5314 Tutorial.lyx is up to date for \SpecialChar LyX
5315 2.1.x, currently maintained by Uwe Stöhr.
5318 \begin_layout Description
5319 UserGuide.lyx our main user guide.
5320 It covers a mixture of basic and detailed information.
5321 Some information is also in the Math and EmbeddedObjects manual so that
5322 the UserGuide refers to these files.
5323 UserGuide.lyx is up to date for \SpecialChar LyX
5324 2.1.x, currently maintained by Uwe Stöhr.
5327 \begin_layout Description
5328 EmbeddedObjects.lyx a special manual to explain things like tables floats
5331 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5332 2.1.x, currently maintained by Uwe
5336 \begin_layout Description
5337 Math.lyx a special manual to explain everything regarding math in all detail.
5338 Math.lyx is up to date for \SpecialChar LyX
5339 2.1.x, currently maintained by Uwe Stöhr.
5342 \begin_layout Description
5343 Additional.lyx this manual covers information that would be too much detail
5344 for the UserGuide or would make the UserGuide uncompilable or only compilable
5345 when installing a lot of special \SpecialChar LaTeX
5347 What should be in the UserGuide or better in Additional is a matter of
5349 it is up to you to decide that.
5350 Additional.lyx is not completely up to date for \SpecialChar LyX
5353 \begin_inset space ~
5356 8 is up to date and currently maintained by Uwe Stöhr.
5357 It certainly needs a rewrite and update.
5358 For example many info in chapter
5359 \begin_inset space ~
5362 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5366 \begin_layout Description
5367 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5369 output formats, operating systems, languages etc.
5370 It is currently completely out of date and needs a major rewrite and update.
5371 If you do this please assure that your information are given for all OSes
5372 and \SpecialChar LaTeX
5373 distributions (meaning be as objective as possible).