1 #LyX 2.2 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 \default_output_format pdf2
31 \bibtex_command default
32 \index_command default
36 \pdf_title "LyX's Development manual"
37 \pdf_author "LyX Team"
38 \pdf_subject "LyX's development documentation"
39 \pdf_keywords "LyX, Documentation, Development"
41 \pdf_bookmarksnumbered true
42 \pdf_bookmarksopen true
43 \pdf_bookmarksopenlevel 1
48 \pdf_pdfusetitle false
49 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
52 \use_package amsmath 1
53 \use_package amssymb 1
56 \use_package mathdots 1
57 \use_package mathtools 0
59 \use_package stackrel 0
60 \use_package stmaryrd 0
61 \use_package undertilde 0
63 \cite_engine_type default
67 \paperorientation portrait
71 \notefontcolor #0000ff
78 \paragraph_separation indent
79 \paragraph_indentation default
80 \quotes_language english
83 \paperpagestyle headings
84 \tracking_changes false
94 Developing \SpecialChar LyX
98 \begin_layout Subtitle
103 by the \SpecialChar LyX
108 \begin_layout Plain Layout
110 If you have comments or error corrections, please send them to the \SpecialChar LyX
113 \begin_inset Flex Code
116 \begin_layout Plain Layout
118 <lyx-docs@lists.lyx.org>
131 \begin_layout Standard
132 \begin_inset CommandInset toc
133 LatexCommand tableofcontents
140 \begin_layout Section
144 \begin_layout Standard
145 This manual documents some aspects of \SpecialChar LyX
147 It is currently rather incomplete, but will hopefully be extended in the
149 Meanwhile, additional information can be found in the
150 \begin_inset Flex Code
153 \begin_layout Plain Layout
159 subfolder of the \SpecialChar LyX
160 source code distribution.
161 This document is not translated, since the development language of \SpecialChar LyX
164 If you just want to use \SpecialChar LyX
165 , then you don't need to read this manual.
166 However, if you want to learn more about how \SpecialChar LyX
167 is developed, or even want
168 to participate in \SpecialChar LyX
169 development, you may find some interesting information
173 \begin_layout Section
177 \begin_layout Standard
179 uses several custom file formats for configuration files and documents.
180 This chapter contains some background concerning these file formats.
181 Several file formats are also described in detail in the regular user documenta
185 \begin_layout Subsection
189 \begin_layout Subsection
190 When is an update of the .lyx file format number needed?
191 \begin_inset CommandInset label
193 name "sec:When-is-an"
200 \begin_layout Standard
201 When you are working on a new feature you may ask yourself whether it needs
202 an update of the .lyx file format number.
203 Whether an update is needed or not is not always obvious.
208 Whenever there is the danger that a previous version of LyX cannot open
209 a file using the new feature, a file format update is needed.
212 \begin_layout Standard
213 The file format change allows lyx2lyx rules to implement backwards compatibility.
214 Below you can find a list of reasons for file format updates with explanations:
217 \begin_layout Description
226 setting Whenever you introduce a new setting that is stored in the document
227 header, a file format update is needed.
230 \begin_layout Description
239 setting If a certain setting becomes obsolete and gets removed, a file format
243 \begin_layout Description
269 \begin_inset space \thinspace{}
276 \begin_layout Description
277 \paragraph_spacing single
290 package The reason for this is that there is no true ERT inset for math
291 formulas: Each command is parsed, and if a user happens to define a local
292 command with the same name as a command that triggers an automatic load
293 of a package, they need to be able to switch off the automatic loading
295 This switch is stored by the
296 \begin_inset Flex Code
299 \begin_layout Plain Layout
308 \begin_layout Description
313 language that is stored in
314 \begin_inset Flex Code
317 \begin_layout Plain Layout
327 \begin_inset Note Note
330 \begin_layout Plain Layout
331 This requirement is under discussion.
340 \begin_layout Description
345 inset Of course a new inset requires a file format update.
348 \begin_layout Description
353 style If a new style or inset layout is added to any layout file or module
354 shipped with \SpecialChar LyX
355 , then a new file format is needed in the master (development)
357 It is possible to backport new styles to the stable version without a file
360 \begin_inset CommandInset ref
362 reference "subsec:Backporting-new-styles"
366 for more information.
369 \begin_layout Description
374 style If a style or inset layout is removed in any layout file or module
375 shipped with \SpecialChar LyX
376 , a new file format is required.
379 \begin_layout Standard
384 layouts and modules do
388 require a file format update (changed 03/16, see
389 \begin_inset CommandInset ref
391 reference "subsec:New-layouts"
399 \begin_layout Standard
400 If you are still unsure, please ask on the development list.
403 \begin_layout Subsection
404 \begin_inset CommandInset label
406 name "subsec:update_lyx_files"
410 How to update the file format number of .lyx files
413 \begin_layout Standard
414 Once you come to the conclusion that a file format update is needed, you
415 should use the following procedure to perform the update:
418 \begin_layout Enumerate
419 Implement and test the new feature, including the reading and writing of
421 Note that any file produced at this stage does not use a valid format,
422 so do not use this version of \SpecialChar LyX
423 for working on any important documents.
426 \begin_layout Enumerate
427 \begin_inset CommandInset label
429 name "enu:Describe_format"
433 Describe the new format in
434 \begin_inset Flex Code
437 \begin_layout Plain Layout
446 \begin_layout Enumerate
447 Update the \SpecialChar LyX
448 file format number in
449 \begin_inset Flex Code
452 \begin_layout Plain Layout
461 \begin_layout Enumerate
462 \begin_inset CommandInset label
464 name "enu:Add-an-entry"
468 Add an entry to both format lists (for conversion and reversion) in
469 \begin_inset Newline newline
473 \begin_inset Flex Code
476 \begin_layout Plain Layout
477 lib/lyx2lyx/lyx_2_3.py
483 Add a conversion routine if needed (e.
484 \begin_inset space \thinspace{}
487 g., a new header setting always needs a conversion that adds the new setting,
488 but a new document language does not need one).
489 Add a reversion routine if needed.
491 \begin_inset Newline newline
494 While the conversion routine is required to produce a document that is equivalen
495 t to the old version, the requirements of the reversion are not that strict.
496 If possible, try to produce a proper reversion, using ERT if needed, but
497 for some features this might be too complicated.
498 In this case, the minimum requirement of the reversion routine is that
499 it produces a valid document which can be read by an older \SpecialChar LyX
501 If absolutely needed, even data loss is allowed for the reversion.
502 (In that case, you might want to add a LyX comment that indicates what
503 you have had to do, so the user is at least warned).
506 \begin_layout Enumerate
507 Since tex2lyx has several implicit file format dependencies caused by sharing
508 code with \SpecialChar LyX
509 , updating the file format of .lyx files produced by tex2lyx at
510 the same time as updating the main .lyx file format is strongly recommended.
511 Therefore, a compiler warning will be issued if the \SpecialChar LyX
512 and tex2lyx .lyx file
513 format numbers differ.
514 In many cases the tex2lyx update requires only the first and last item
519 \begin_layout Enumerate
520 Update the tex2lyx file format number in
521 \begin_inset Flex Code
524 \begin_layout Plain Layout
533 \begin_layout Enumerate
534 If the lyx2lyx conversion from the old to the new format is empty, or if
535 tex2lyx does not yet output the changed feature, you do not need any further
537 Otherwise, search for the changed feature in tex2lyx, and adjust the output
538 according to the lyx2lyx changes.
541 \begin_layout Enumerate
542 Update the tex2lyx test references as described in
543 \begin_inset CommandInset ref
544 LatexCommand formatted
545 reference "sec:Updating-test-references"
553 \begin_layout Enumerate
554 If you did not implement full tex2lyx support for the new feature, add a
556 \begin_inset Flex Code
559 \begin_layout Plain Layout
565 describing the missing bits.
566 Note that it is perfectly fine if you do not add full tex2lyx support for
567 a new feature: The updating recommendation above is only issued for the
568 syntax of the produced .lyx file.
569 It is no problem if some features supported by \SpecialChar LyX
570 are still output as ERT
572 The problems in the past that resulted in the update recommendation were
573 related to mixed version syntax, not ERT.
576 \begin_layout Enumerate
577 It would be nice if you could create a .lyx test file which contains instances
578 of all changed or added features.
579 This could then be used to test lyx2lyx and tex2lyx.
580 Unfortunately, it has not yet been decided how to collect such examples,
581 so please ask on the development list if you want to create one.
584 \begin_layout Enumerate
585 \begin_inset CommandInset label
587 name "enu:updatefiles"
591 Test your lyx2lyx code by updating LyX's .lyx documentation files to the
593 The developer who makes the change knows best what changes to expect when
594 inspecting the resulting diff.
595 Because of this, you might be able to catch a bug in the lyx2lyx code that
596 updates the format just by taking a quick scan through the large diff that
598 \begin_inset Note Note
601 \begin_layout Plain Layout
602 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
603 see which layout update made an unexpected change by looking at the git
604 log of a .lyx file that suffers the problem.
609 To do this, first make sure that there are no changes to the git repository
610 that you will not want to commit (this is needed because it will be convenient
611 to commit with the command
612 \begin_inset Flex Code
615 \begin_layout Plain Layout
622 Then run the following command in the root folder of the source:
623 \begin_inset Flex Code
626 \begin_layout Plain Layout
627 python development/tools/updatedocs.py
633 Look at the resulting changes using the command
634 \begin_inset Flex Code
637 \begin_layout Plain Layout
644 If anything looks surprising, please investigate.
645 Keep in mind that the case of
646 \begin_inset Flex Code
649 \begin_layout Plain Layout
655 is special, because it is first generated with
656 \begin_inset Flex Code
659 \begin_layout Plain Layout
665 before being converted to the latest format.
666 \begin_inset Newline newline
670 \begin_inset Note Greyedout
673 \begin_layout Plain Layout
678 Only commit file format changes in the doc files if these files are using
679 the new feature of the new file format.
685 \begin_inset CommandInset ref
687 reference "enu:The-fileformat-of"
691 of the documentation policies described in sec.
696 \begin_inset CommandInset ref
698 reference "sec:Documentation-policies"
710 \begin_layout Enumerate
711 Finally, commit using
712 \begin_inset Flex Code
715 \begin_layout Plain Layout
724 \begin_layout Subsection
725 Updating the file format number of layout files
728 \begin_layout Standard
729 The procedure for updating the layout files is similar to that in step
730 \begin_inset CommandInset ref
732 reference "enu:updatefiles"
737 \begin_inset CommandInset ref
739 reference "subsec:update_lyx_files"
745 \begin_inset Flex Code
748 \begin_layout Plain Layout
749 python development/tools/updatelayouts.py
755 \begin_inset Flex Code
758 \begin_layout Plain Layout
767 \begin_layout Standard
768 Note that we do not automatically any local layout used in the
769 \begin_inset Flex Code
772 \begin_layout Plain Layout
778 files shipped with \SpecialChar LyX
779 because users would then not be able to export to older
781 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
782 to open the file in \SpecialChar LyX
783 2.1.x, there would be an error because the file would
784 contain a local layout whose format is too new.
785 The root reason for this is that we do not support converting layouts to
786 older layout formats, as we do for the
787 \begin_inset Flex Code
790 \begin_layout Plain Layout
799 \begin_layout Subsection
800 Updating the file format number of bind/ui files
803 \begin_layout Standard
804 A change to the functionality of existing LFUNs can require a conversion
806 \begin_inset Flex Code
809 \begin_layout Plain Layout
816 \begin_inset Flex Code
819 \begin_layout Plain Layout
825 files, and therefore an increment of the LFUN format, as well as a conversion
827 \begin_inset Flex Code
830 \begin_layout Plain Layout
837 The latter cannot be done automatically and also requires an update of
841 \begin_inset space \space{}
844 of someone who might have made a set of \SpecialChar LyX
845 teaching manuals for use in their
850 \begin_layout Plain Layout
851 \begin_inset Flex URL
854 \begin_layout Plain Layout
856 http://www.lyx.org/trac/ticket/9794
869 \begin_layout Standard
870 To update the LFUN format:
873 \begin_layout Enumerate
874 Increment the LFUN file format number in
875 \begin_inset Flex Code
878 \begin_layout Plain Layout
887 \begin_layout Enumerate
888 Implement the LFUN conversion in
889 \begin_inset Flex Code
892 \begin_layout Plain Layout
893 lib/scripts/prefs2prefs_lfuns.py
901 \begin_layout Enumerate
903 \begin_inset CommandInset ref
905 reference "enu:updatefiles"
910 \begin_inset CommandInset ref
912 reference "subsec:update_lyx_files"
917 \begin_inset Flex Code
920 \begin_layout Plain Layout
926 command, use this command:
927 \begin_inset Flex Code
930 \begin_layout Plain Layout
931 bash development/tools/updatelfuns.sh
938 \begin_inset Note Note
941 \begin_layout Plain Layout
942 This file should really be converted to python.
950 \begin_layout Enumerate
951 Update Info insets in
952 \begin_inset Flex Code
955 \begin_layout Plain Layout
962 To do so, increment the \SpecialChar LyX
963 format and proceed as in
964 \begin_inset CommandInset ref
966 reference "subsec:update_lyx_files"
971 \begin_inset CommandInset ref
973 reference "enu:Describe_format"
978 \begin_inset CommandInset ref
980 reference "enu:updatefiles"
985 In the lyx2lyx implementation (step
986 \begin_inset CommandInset ref
988 reference "enu:Add-an-entry"
992 ), implement a conversion similar to the one in
993 \begin_inset Flex Code
996 \begin_layout Plain Layout
1002 above, as well as a corresponding reversion; for this one can use
1003 \begin_inset Flex Code
1006 \begin_layout Plain Layout
1013 \begin_inset Flex Code
1016 \begin_layout Plain Layout
1017 lib/lyx2lyx/lyx2lyx_tools.py
1026 \begin_layout Subsection
1027 Backporting new styles to the stable version
1028 \begin_inset CommandInset label
1030 name "subsec:Backporting-new-styles"
1037 \begin_layout Standard
1038 Starting with the stable \SpecialChar LyX
1039 2.1 branch, there is a mechanism in place to backport
1040 new styles to the stable version without the need to update the file format.
1041 The basic idea is that the new style definition is automatically copied
1042 to the document preamble so that it can even be used by older minor versions
1043 that did not yet include the style.
1044 To backport a new style to the stable version, the following steps are
1048 \begin_layout Enumerate
1050 \begin_inset Flex Code
1053 \begin_layout Plain Layout
1059 to the style definition in the development version.
1062 \begin_layout Enumerate
1063 Copy the style definition to the stable version, but use
1064 \begin_inset Flex Code
1067 \begin_layout Plain Layout
1074 If needed adjust the format to the one used by the stable version (see
1075 the customization manual for details of the layout file format).
1078 \begin_layout Enumerate
1079 For each update of the style in a later stable version, increase the argument
1081 \begin_inset Flex Code
1084 \begin_layout Plain Layout
1091 (In the stable version, the development version should not be touched.)
1094 \begin_layout Standard
1095 For details about the
1096 \begin_inset Flex Code
1099 \begin_layout Plain Layout
1105 flag see the customization manual.
1107 \begin_inset Flex Code
1110 \begin_layout Plain Layout
1116 support is needed for backported styles: Since the style of the development
1117 version has an infinite version number, it will always be used.
1118 Furthermore, since its version number is less than one, the style will
1119 not be written anymore to the document header for files saved by the new
1123 \begin_layout Section
1124 New layouts and modules
1127 \begin_layout Subsection
1128 \begin_inset CommandInset label
1130 name "subsec:New-layouts"
1137 \begin_layout Standard
1138 Adding a new layout file to the \SpecialChar LyX
1140 \begin_inset Quotes eld
1143 officially supported
1144 \begin_inset Quotes erd
1148 You should therefore think carefully about whether you really want to do
1149 this and discuss it on lyx-devel, since you will need to be prepared to
1150 update and fix the layout if necessary.
1151 If the layout is experimental or for a rarely used document class, then
1152 it may be better to add it to the relevant portion of the \SpecialChar LyX
1156 \begin_inset CommandInset href
1158 target "https://wiki.lyx.org/Layouts/Layouts"
1165 \begin_layout Standard
1166 In older versions of this document, it was stated that new layout files
1167 require a file format change.
1168 After some discussion, it was decided that this is not needed.
1172 \begin_layout Plain Layout
1174 \begin_inset CommandInset href
1176 name "the thread “Proposal for a guide on updating layouts”"
1177 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1190 For reference, here are the arguments on each side
1194 \begin_layout Description
1196 \begin_inset Quotes eld
1199 New layout files are a file format change
1200 \begin_inset Quotes erd
1206 \begin_layout Itemize
1207 All documents produced by 2.2.
1208 \begin_inset Formula $x$
1211 can always be edited and exported even if
1212 \begin_inset Formula $x$
1216 This is important for people using different machines, or exchanging work
1220 \begin_layout Description
1222 \begin_inset Quotes eld
1225 New layout files are not a file format change
1226 \begin_inset Quotes erd
1232 \begin_layout Itemize
1233 No new LaTeX classes can be supported in a stable version, and stable versions
1234 have a typical lifetime of 2–3 years.
1237 \begin_layout Itemize
1238 We have the same situation already with custom layout files: If a document
1239 using a custom layout file is moved between machines or people, then the
1240 layout file needs to be exchanged as well.
1241 If that is not done, then we have a fallback implemented so that such documents
1242 can still be edited, but not exported, and the user gets a warning.
1246 \begin_layout Itemize
1247 The lyx2lyx script cannot do anything useful in such a case.
1251 \begin_layout Standard
1252 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1254 then, you should do the following:
1257 \begin_layout Enumerate
1258 Put your new layout file in
1259 \begin_inset Flex Code
1262 \begin_layout Plain Layout
1269 \begin_inset Flex Code
1272 \begin_layout Plain Layout
1273 git add lib/layouts/newlayout.layout
1278 ) so that it will be committed.
1281 \begin_layout Enumerate
1283 \begin_inset Flex Code
1286 \begin_layout Plain Layout
1292 , so that the new layout actually gets installed.
1295 \begin_layout Enumerate
1297 \begin_inset Flex Code
1300 \begin_layout Plain Layout
1301 lib/doc/LaTeXConfig.lyx
1306 containing in particular a line like
1314 \begin_layout Standard
1315 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1316 \begin_inset Flex Code
1319 \begin_layout Plain Layout
1320 info-insert textclass <name>
1326 This inset will automatically display a boxed
1327 \begin_inset Quotes eld
1331 \begin_inset Quotes erd
1335 \begin_inset Quotes eld
1339 \begin_inset Quotes erd
1342 depending on the availability of the package.
1346 \begin_layout Enumerate
1347 A template or example is strongly encouraged (but not necessarily required).
1348 It is also possible to provide both.
1350 \begin_inset Flex Code
1353 \begin_layout Plain Layout
1360 \begin_inset Flex Code
1363 \begin_layout Plain Layout
1372 \begin_layout Enumerate
1373 Reconfigure \SpecialChar LyX
1377 \begin_layout Enumerate
1378 Ensure the autotests for the new layout pass (see
1379 \begin_inset CommandInset ref
1381 reference "par:when-to-run-an-export-test"
1388 \begin_layout Subsection
1392 \begin_layout Standard
1393 Adding a new module is very similar to adding a new layout.
1394 Therefore, the previous section applies to new modules as well, with two
1398 \begin_layout Enumerate
1399 You only need to add an entry to
1400 \begin_inset Flex Code
1403 \begin_layout Plain Layout
1404 lib/doc/LaTeXConfig.lyx
1409 if the module requires a LaTeX package.
1410 In that case, the command for entering the InsetInfo is:
1411 \begin_inset Flex Code
1414 \begin_layout Plain Layout
1415 \paragraph_spacing single
1416 info-insert package <name>
1424 \begin_layout Enumerate
1425 Modules do not need a template, only an example, which is strongly encouraged
1426 but not necessarily required.
1429 \begin_layout Subsection
1430 Layouts for document classes with incompatible versions
1433 \begin_layout Standard
1434 \begin_inset Note Greyedout
1437 \begin_layout Description
1438 Note: This section is currently only a proposal under discussion.
1439 Please correct/amend as suited.
1440 Remove this note once a consensus is found.
1443 \begin_layout Plain Layout
1445 \begin_inset Quotes eld
1448 Proposal for a guide on updating layouts
1449 \begin_inset Quotes erd
1452 for details and background
1455 \begin_layout Plain Layout
1456 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1464 \begin_layout Standard
1465 Every now and then, there are changes to LaTeX document classes that break
1466 backwards compatibility.
1470 \begin_layout Plain Layout
1471 Uwe has suggested we implement automatic detection of changes in class files.
1472 This could be done by running a script every month that checks if a document
1473 class was changed at CTAN and at the homepages of the scientific journals.
1474 If it reports a change, we can check if our template and layout file are
1475 still usable with the changed document class.
1476 (This is different from the autotests insofar, as this would also catch
1477 changes that do not result in compilation errors.)
1482 Reasons can be a new name for the
1483 \begin_inset Flex Code
1486 \begin_layout Plain Layout
1492 file, removed \SpecialChar LaTeX
1494 How should this best be handled in \SpecialChar LyX
1498 \begin_layout Standard
1499 The idea is to support the new version with a new \SpecialChar LyX
1503 \begin_layout Itemize
1504 Existing documents can still be opened in \SpecialChar LyX
1505 and will continue to work on
1506 systems where the old version is still installed.
1510 \begin_layout Itemize
1511 With differently named
1512 \begin_inset Flex Code
1515 \begin_layout Plain Layout
1521 files, \SpecialChar LyX
1522 can check for the availability of the particular version and reflect
1524 Different document class versions with the same file name are currently
1525 (2.2.x) not detected by the configuration script.
1526 This is planned for 2.3.
1530 \begin_layout Plain Layout
1531 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1534 \begin_layout Plain Layout
1535 However, what we really need is version detection for the configuration,
1536 so that the user can be warned if the required class file has the wrong
1538 (If the class file keeps the name over the version change, only one of
1539 the two layout files generates compilable documents.)
1542 \begin_layout Plain Layout
1543 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1552 \begin_layout Itemize
1553 The new layout can be added both to the master and the stable branches,
1554 in accord with the policy discussed in
1555 \begin_inset CommandInset ref
1556 LatexCommand formatted
1557 reference "subsec:New-layouts"
1562 No lyx2lyx conversion is then required when a new major version is released.
1565 \begin_layout Standard
1566 The user can move an existing document to the new version simply by selecting
1567 a new document class.
1568 This step is well supported by \SpecialChar LyX
1569 , with established methods for handling
1570 unsupported styles and other changes.
1571 This way, no lyx2lyx code is required.
1574 \begin_layout Standard
1575 The steps to support a new version of an existing document class are thus:
1578 \begin_layout Itemize
1579 Create a new layout file including the upstream version in the name (avoid
1580 special characters like spaces and dots), e.g.
1582 \begin_inset Flex Code
1585 \begin_layout Plain Layout
1586 acmsiggraph-v0-92.layout
1594 \begin_layout Itemize
1595 Include the name of the
1596 \begin_inset Flex Code
1599 \begin_layout Plain Layout
1605 file as an optional argument in the
1606 \begin_inset Flex Code
1609 \begin_layout Plain Layout
1617 line and include the version number in the GUI name:
1618 \begin_inset Newline newline
1622 \begin_inset Flex Code
1625 \begin_layout Plain Layout
1628 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1629 \begin_inset space ~
1640 \begin_layout Itemize
1641 Update the GUI name in the old layout file (whose name should not be changed),
1643 \begin_inset Newline newline
1647 \begin_inset Flex Code
1650 \begin_layout Plain Layout
1653 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1654 \begin_inset space ~
1665 \begin_layout Itemize
1666 To avoid duplicate definitions, the new layout can
1667 \begin_inset Flex Code
1670 \begin_layout Plain Layout
1676 the old layout file and add\SpecialChar breakableslash
1677 remove\SpecialChar breakableslash
1678 obsolete\SpecialChar breakableslash
1679 modify settings and styles (similar
1681 \begin_inset Flex Code
1684 \begin_layout Plain Layout
1694 \begin_layout Standard
1695 It may be tempting to let the new layout be the
1696 \begin_inset Quotes eld
1700 \begin_inset Quotes erd
1703 and have the old layout import it.
1704 However, this should not be done because any changes to the new layout
1705 would need undo steps in the importing old layout.
1709 \begin_layout Itemize
1710 If the new LaTeX document class obsoletes the old one, update the example
1711 and template files to use the new layout.
1712 Add a note about the changes (preferably with a pointer to the documentation
1717 \begin_layout Standard
1718 This way, new documents based on the template or example will use the up-to-date
1719 document class version.
1723 \begin_layout Standard
1724 \begin_inset Newpage newpage
1730 \begin_layout Section
1734 \begin_layout Standard
1735 Automated tests are an important tool to detect bugs and regressions in
1736 software development.
1737 Some projects like gcc even require each bug fix to be accompanied by a
1738 test case for the automatic test suite, that would detect this bug.
1739 Testing interactive features automatically is of course very hard, but
1740 core functionality like document import and export can be tested quite
1741 easily, and some tests of this kind exist.
1744 \begin_layout Subsection
1748 \begin_layout Standard
1749 There are attempts to set up a suite of unit tests for LyX.
1752 \begin_layout Standard
1753 TODO: describe what is done and what is still to do.
1756 \begin_layout Subsection
1760 \begin_layout Standard
1761 The tex2lyx tests are located in the
1762 \begin_inset Flex Code
1765 \begin_layout Plain Layout
1771 subfolder of the \SpecialChar LyX
1772 source code distribution.
1773 The actual testing is performed by the simple python script
1774 \begin_inset Flex Code
1777 \begin_layout Plain Layout
1778 src/tex2lyx/test/runtests.py
1784 Each test consists of two files:
1785 \begin_inset Flex Code
1788 \begin_layout Plain Layout
1794 contains the \SpecialChar LaTeX
1795 code that should be tested.
1797 \begin_inset Flex Code
1800 \begin_layout Plain Layout
1806 contains the expected output of tex2lyx.
1807 When a test is run, the actual produced output is compared with the stored
1809 The test passes if both are identical.
1810 The test machinery is also able to generate a file
1811 \begin_inset Flex Code
1814 \begin_layout Plain Layout
1820 by exporting the produced .lyx file with \SpecialChar LyX
1822 This may be useful for roundtrip comparisons.
1825 \begin_layout Subsubsection
1829 \begin_layout Standard
1830 The tex2lyx tests can be run in several ways.
1832 \begin_inset Flex Code
1835 \begin_layout Plain Layout
1841 subfolder of the build directory, the commands
1842 \begin_inset Flex Code
1845 \begin_layout Plain Layout
1851 (cmake, all platforms),
1852 \begin_inset Flex Code
1855 \begin_layout Plain Layout
1861 (cmake, when using a make based build system and not MSVC) or
1862 \begin_inset Flex Code
1865 \begin_layout Plain Layout
1871 (autotools) will run the tex2lyx tests.
1872 Alternatively, in the root of the build directory, the command
1873 \begin_inset Flex Code
1876 \begin_layout Plain Layout
1882 runs all tests whose names match the regex
1883 \begin_inset Quotes eld
1887 \begin_inset Quotes erd
1891 Another way to run the tex2lyx tests in the root build directory is to
1892 instead use the command
1893 \begin_inset Flex Code
1896 \begin_layout Plain Layout
1897 ctest -L '(cmplyx|roundtrip)'
1902 , which runs all tests categorized with the label
1903 \begin_inset Quotes eld
1907 \begin_inset Quotes erd
1911 \begin_inset Quotes eld
1915 \begin_inset Quotes erd
1919 If a test fails, the differences between the expected and actual results
1920 are output in unified diff format.
1923 \begin_layout Subsubsection
1924 Updating test references
1925 \begin_inset CommandInset label
1927 name "sec:Updating-test-references"
1934 \begin_layout Standard
1935 In some cases a changed tex2lyx output is not a test failure, but wanted,
1937 \begin_inset space \thinspace{}
1941 \begin_inset space \space{}
1944 if a tex2lyx bug was fixed, or a new feature was added.
1945 In these cases the stored references need to be updated.
1946 To do so if using autotools, call
1947 \begin_inset Flex Code
1950 \begin_layout Plain Layout
1957 \begin_inset Flex Code
1960 \begin_layout Plain Layout
1966 subdirectory of the build directory.
1967 If instead using CMake, call
1968 \begin_inset Flex Code
1971 \begin_layout Plain Layout
1972 make updatetex2lyxtests
1977 in the build directory or in the
1978 \begin_inset Flex Code
1981 \begin_layout Plain Layout
1987 subdirectory of the build directory.
1991 \begin_layout Plain Layout
1992 Note that this is a case where a make target in the build directory can
1993 affect the source directory, which might not be advisable.
1998 On Windows do the following:
2001 \begin_layout Itemize
2002 Assure that the path to the python.exe is in your system PATH variable.
2005 \begin_layout Itemize
2006 Double-click on the file
2007 \begin_inset Flex Code
2010 \begin_layout Plain Layout
2011 updatetex2lyxtests.vcxproj
2016 in the build directory or in the
2017 \begin_inset Flex Code
2020 \begin_layout Plain Layout
2026 subdirectory of your build directory.
2029 \begin_layout Itemize
2030 In the appearing MSVC program assure that you build the
2034 version, then right-click on the project
2038 in the project explorer and choose then
2041 \begin_inset space ~
2044 Only\SpecialChar menuseparator
2046 \begin_inset space ~
2054 \begin_layout Standard
2055 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2057 Please examine the changed output carefully before committing the changed
2058 files to the repository: Since the test machinery does not do a roundtrip
2060 \begin_inset Formula $\Rightarrow$
2064 \begin_inset Formula $\Rightarrow$
2067 .tex, and does not compare the produced dvi or pdf output, it assumes that
2068 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2070 There is only one chance to detect wrong output: before committing a new
2072 Once it is committed, it is quite difficult to verify whether it is correct.
2075 \begin_layout Standard
2080 update the test references by opening them with \SpecialChar LyX
2081 or directly running lyx2lyx
2083 This would not work, since lyx2lyx and \SpecialChar LyX
2084 produce slightly different files
2085 regarding insignificant whitespace and line breaks.
2088 \begin_layout Subsubsection
2092 \begin_layout Standard
2093 In many cases tests for new features may be added to one of the existing
2094 test files, but sometimes this is not possible or not wanted.
2095 Then a new test file needs to be added:
2098 \begin_layout Enumerate
2100 \begin_inset Flex Code
2103 \begin_layout Plain Layout
2104 src/tex2lyx/test/<test name>.tex
2109 and run tex2lyx in roundtrip mode to produce the file
2110 \begin_inset Flex Code
2113 \begin_layout Plain Layout
2114 src/tex2lyx/test/<test name>.lyx.lyx
2120 This file will be the new reference.
2123 \begin_layout Enumerate
2124 Once you confirmed that the tex2lyx output is correct, add the new files
2125 to the corresponding lists in
2126 \begin_inset Flex Code
2129 \begin_layout Plain Layout
2130 src/tex2lyx/test/runtests.py
2136 \begin_inset Flex Code
2139 \begin_layout Plain Layout
2140 src/tex2lyx/Makefile.am
2146 \begin_inset Flex Code
2149 \begin_layout Plain Layout
2150 src/tex2lyx/test/CMakeLists.txt
2158 \begin_layout Enumerate
2159 Commit the changes to the repository, or send a patch to the development
2160 list and ask for committing if you do not have commit rights.
2163 \begin_layout Subsection
2164 ctest automatic tests
2167 \begin_layout Standard
2168 Some tests are located in the
2169 \begin_inset Flex Code
2172 \begin_layout Plain Layout
2173 development/autotests/
2178 subfolder of the \SpecialChar LyX
2179 source code distribution.
2184 \begin_layout Plain Layout
2185 The README document in this folder only describes the
2186 \begin_inset Quotes eld
2190 \begin_inset Quotes erd
2193 subset of autotests!
2201 \begin_layout Standard
2202 These tests can be run by the commands
2203 \begin_inset Flex Code
2206 \begin_layout Plain Layout
2216 (all platforms) or (when using a make based build system and not MSVC)
2218 \begin_inset Flex Code
2221 \begin_layout Plain Layout
2228 \begin_inset Flex Code
2231 \begin_layout Plain Layout
2242 The test logs are written to the
2243 \begin_inset Flex Code
2246 \begin_layout Plain Layout
2260 \begin_layout Subsubsection
2264 \begin_layout Standard
2265 The export tests are integration tests.
2266 They take longer to run and are more likely to break than the tex2lyx tests.
2267 Nevertheless, they have caught many regressions and without a better alternativ
2268 e it is important to keep them up-to-date and understand how they work.
2271 \begin_layout Standard
2273 \begin_inset Quotes eld
2277 \begin_inset Quotes erd
2280 documentation, template, and example documents.
2281 In addition, there are a number of dedicated sample documents in the
2282 \begin_inset Flex Code
2285 \begin_layout Plain Layout
2291 subfolder of the \SpecialChar LyX
2292 source code distribution.
2293 All samples are (after copying and eventual processing by scripts) exported
2294 to various output formats via the
2295 \begin_inset Flex Code
2298 \begin_layout Plain Layout
2304 command line option.
2305 The tests checks for errors reported by LyX.
2306 (However, error-free export is no guarantee for an error-free output document.)
2309 \begin_layout Paragraph
2310 \begin_inset CommandInset label
2312 name "par:when-to-run-an-export-test"
2316 Expectations of LyX developers
2319 \begin_layout Standard
2320 Because the export tests are integration tests and take a long time to run,
2321 LyX developers are rarely expected to run all of the tests.
2322 Here are some good practices to follow by developers:
2325 \begin_layout Itemize
2326 When making a non-trivial change to a .layout file, run the export and layout
2327 tests corresponding with that .layout file.
2330 \begin_layout Itemize
2331 When making non-trivial changes to a .lyx file, run the export tests correspondin
2332 g to that .lyx file.
2337 \begin_layout Plain Layout
2338 This rule is due to revision.
2342 \begin_layout Plain Layout
2343 There is an objection from the documentation maintainer that working on
2344 the documentation must not be complicated by having to consider non-standard
2348 \begin_layout Itemize
2349 successful compiling/testing an edited documentation file with pdflatex
2350 suffices to ensure it can be commited, not tests with other exports are
2354 \begin_layout Plain Layout
2355 If sudden failures with other exports due to “half-tested” documentation
2356 updates are a problem for the test maintainer, the test suite should use
2360 \begin_layout Itemize
2361 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2364 \begin_layout Itemize
2365 updated regularely (but on a time chosen by the test suite maintainer) from
2366 the originals in lib/doc/
2369 \begin_layout Plain Layout
2373 \begin_layout Itemize
2374 no test will fail due to ongoing work on documentation,
2377 \begin_layout Itemize
2378 the documentation is still tested in full (with some delay),
2381 \begin_layout Itemize
2382 failures with non-default export can be examined and handled accordingly
2383 in one run with the cache update,
2386 \begin_layout Itemize
2387 “interesting failures” (like the nested-language+polyglossia problem in
2388 es/Customization can be separated and moved into dedicated test samples.
2396 \begin_layout Itemize
2397 When making non-trivial changes to LyX's \SpecialChar LaTeX
2399 touching the encoding code or package handling code that you expect will
2400 change the exported \SpecialChar LaTeX
2405 \begin_layout Standard
2406 \paragraph_spacing single
2407 Consider running all of the export tests before and after your change.
2408 If there are differences, please reconcile these (i.e.
2409 fix the bug or fix the tests)
2414 Ask for help if you're not sure what to.
2417 \begin_layout Standard
2418 If you do not want to run the tests,
2421 \begin_layout Itemize
2422 post the patch on the list and others will run the tests and eventually
2426 \begin_layout Itemize
2427 commit, but be prepared to fix eventually arising problems or to revert
2428 the commit if there is no easy fix.
2432 \begin_layout Itemize
2433 Understand how to interpret test failures.
2434 If your commit is found to have broken a test, you should be able to interpret
2435 the test results when made aware of them.
2437 \begin_inset CommandInset ref
2439 reference "subsec:Interpreting-export-tests"
2446 \begin_layout Paragraph
2447 \begin_inset CommandInset label
2449 name "par:export-test-output-formats"
2456 \begin_layout Standard
2457 The following output formats are currently tested for each sample document
2459 \begin_inset CommandInset ref
2461 reference "par:Export-test-filtering"
2468 \begin_layout Labeling
2469 \labelwidthstring 00.00.0000
2474 \begin_layout Labeling
2475 \labelwidthstring 00.00.0000
2476 lyx16 LyX 1.6 file format (lyx2lyx)
2479 \begin_layout Labeling
2480 \labelwidthstring 00.00.0000
2481 lyx21 LyX 2.1 file format (lyx2lyx)
2484 \begin_layout Labeling
2485 \labelwidthstring 00.00.0000
2486 xhtml LyXHTML (native LyX HTML export)
2490 \begin_layout Labeling
2491 \labelwidthstring 00.00.0000
2493 \begin_inset space ~
2497 \begin_inset space ~
2504 \begin_layout Labeling
2505 \labelwidthstring pdf5msystemFM
2506 dvi DVI (8-bit latex)
2509 \begin_layout Labeling
2510 \labelwidthstring pdf5msystemFM
2511 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2514 \begin_layout Labeling
2515 \labelwidthstring pdf5msystemFM
2516 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2519 \begin_layout Labeling
2520 \labelwidthstring pdf5msystemFM
2524 \begin_layout Labeling
2525 \labelwidthstring pdf5msystemFM
2526 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2529 \begin_layout Labeling
2530 \labelwidthstring pdf5msystemFM
2531 pdf4_systemF PDF (XeTeX with Unicode fonts)
2534 \begin_layout Labeling
2535 \labelwidthstring pdf5msystemFM
2536 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2539 \begin_layout Labeling
2540 \labelwidthstring pdf5msystemFM
2541 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2545 \begin_layout Labeling
2546 \labelwidthstring 00.00.0000
2548 \begin_inset space ~
2552 \begin_inset space ~
2556 \begin_inset space ~
2560 \begin_inset space ~
2567 \begin_layout Labeling
2568 \labelwidthstring pdf5msystemFM
2569 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2572 \begin_layout Labeling
2573 \labelwidthstring pdf5msystemFM
2574 pdf3 DVI -> PDF (dvipdfm)
2578 \begin_layout Labeling
2579 \labelwidthstring 00.00.0000
2581 \begin_inset space ~
2584 tested: (or only if set as default output format in the document source)
2588 \begin_layout Labeling
2589 \labelwidthstring pdf5msystemFM
2593 \begin_layout Labeling
2594 \labelwidthstring pdf5msystemFM
2595 luatex LaTeX (LuaTeX)
2598 \begin_layout Labeling
2599 \labelwidthstring pdf5msystemFM
2600 dviluatex LaTeX (dviluatex)
2603 \begin_layout Labeling
2604 \labelwidthstring pdf5msystemFM
2605 pdflatex LaTeX (pdflatex)
2608 \begin_layout Labeling
2609 \labelwidthstring pdf5msystemFM
2610 platex LaTeX (pLaTeX)
2613 \begin_layout Labeling
2614 \labelwidthstring pdf5msystemFM
2618 \begin_layout Labeling
2619 \labelwidthstring pdf5msystemFM
2620 eps3 EPS (encapsulated Postscript) (cropped)
2623 \begin_layout Labeling
2624 \labelwidthstring pdf5msystemFM
2625 ps DVI -> Postscript (dvips)
2628 \begin_layout Labeling
2629 \labelwidthstring pdf5msystemFM
2633 \begin_layout Labeling
2634 \labelwidthstring pdf5msystemFM
2635 text (nor text2, ..., text4)
2638 \begin_layout Labeling
2639 \labelwidthstring pdf5msystemFM
2643 \begin_layout Labeling
2644 \labelwidthstring pdf5msystemFM
2648 \begin_layout Labeling
2649 \labelwidthstring pdf5msystemFM
2653 \begin_layout Labeling
2654 \labelwidthstring pdf5msystemFM
2659 \begin_layout Paragraph
2660 \begin_inset CommandInset label
2662 name "par:Configuring-ctests"
2666 Configuring the tests
2669 \begin_layout Standard
2670 To enable the export autotests, add the
2671 \begin_inset Flex Code
2674 \begin_layout Plain Layout
2675 -DLYX_ENABLE_EXPORT_TESTS=ON
2684 \begin_layout Standard
2685 \begin_inset Flex Code
2688 \begin_layout Plain Layout
2689 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2697 \begin_layout Standard
2699 This flag will increase the time for the cmake command by several seconds,
2700 mainly because of the process of inverting tests (see Section
2701 \begin_inset CommandInset ref
2703 reference "subsec:Interpreting-export-tests"
2710 \begin_layout Paragraph
2711 \begin_inset CommandInset label
2713 name "par:ctest-options"
2720 \begin_layout Standard
2721 To run all tests, in the build directory simply run the command
2722 \begin_inset Flex Code
2725 \begin_layout Plain Layout
2732 A full, up-to-date TeXLive installation is recommended to run the tests.
2733 Otherwise, some tests will fail.
2734 Tests with additional requirements are labeled
2735 \begin_inset Quotes eld
2738 unreliable:nonstandard
2739 \begin_inset Quotes erd
2746 \begin_layout Standard
2747 To run only some of the tests, use command line options (see examples below):
2750 \begin_layout Labeling
2751 \labelwidthstring -R
2752 \begin_inset Flex Code
2755 \begin_layout Plain Layout
2761 Run only the tests whose names match the given regular expression.
2764 \begin_layout Labeling
2765 \labelwidthstring -R
2766 \begin_inset Flex Code
2769 \begin_layout Plain Layout
2775 Run only the tests whose labels match the given regular expression.
2776 A test may have more that one label.
2780 \begin_layout Labeling
2781 \labelwidthstring -R
2782 \begin_inset Flex Code
2785 \begin_layout Plain Layout
2791 Exclude the tests whose names match the given regular expression.
2794 \begin_layout Labeling
2795 \labelwidthstring -R
2796 \begin_inset Flex Code
2799 \begin_layout Plain Layout
2805 Exclude the tests whose labels match the given regular expression.
2806 Cannot be combined with
2807 \begin_inset Flex Code
2810 \begin_layout Plain Layout
2819 \begin_layout Standard
2820 The following options help to find good selection patterns:
2823 \begin_layout Labeling
2824 \labelwidthstring -R
2825 \begin_inset Flex Code
2828 \begin_layout Plain Layout
2834 List the tests that would be run but not actually run them.
2839 \begin_layout Standard
2840 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2841 to know how many tests there are or whether your
2842 \begin_inset Flex Code
2845 \begin_layout Plain Layout
2851 regular expression did what you expected.
2855 \begin_layout Labeling
2856 \labelwidthstring -R
2857 \begin_inset Flex Code
2860 \begin_layout Plain Layout
2861 \SpecialChar nobreakdash
2862 \SpecialChar nobreakdash
2868 print the list of all labels associated with the test set.
2869 Can also be combined with -R, -L, -E, ...
2873 \begin_layout Standard
2874 Other useful options are:
2877 \begin_layout Labeling
2878 \labelwidthstring -R
2879 \begin_inset Flex Code
2882 \begin_layout Plain Layout
2888 Run the tests in parallel using the given number of jobs.
2892 \begin_layout Standard
2893 We are still working on getting the tests to run in parallel.
2894 However, when running the tests in parallel, sometimes tests fail that
2895 pass when run sequentially.
2896 A reasonable approach is to first run the tests in parallel and then run
2897 the failed tests sequentially.
2900 \begin_layout Standard
2901 For example, to run 8 jobs at a time:
2904 \begin_layout Standard
2905 \begin_inset Flex Code
2908 \begin_layout Plain Layout
2917 \begin_layout Standard
2918 \begin_inset Flex Code
2921 \begin_layout Plain Layout
2922 ctest \SpecialChar nobreakdash
2923 \SpecialChar nobreakdash
2932 \begin_layout Standard
2933 When specifying a subset of the tests (e.g.
2935 \begin_inset Flex Code
2938 \begin_layout Plain Layout
2939 \SpecialChar nobreakdash
2945 ), the same subset must be specified when using the
2946 \begin_inset Flex Code
2949 \begin_layout Plain Layout
2950 \SpecialChar nobreakdash
2951 \SpecialChar nobreakdash
2957 option because it is the test numbers that are used to index which tests
2958 failed on the previous run.
2961 \begin_layout Standard
2963 Note that some tests cannot be run in parallel.
2964 These tests are marked in the code with the
2965 \begin_inset Flex Code
2968 \begin_layout Plain Layout
2979 \begin_layout Labeling
2980 \labelwidthstring -R
2981 \begin_inset Flex Code
2984 \begin_layout Plain Layout
2985 \SpecialChar nobreakdash
2986 \SpecialChar nobreakdash
2992 Set a global timeout on all tests that do not already have a timeout set
2997 \begin_layout Standard
2998 There have been bugs in LyX and in \SpecialChar LaTeX
2999 which cause compilation to hang, and
3000 without a timeout a test might never stop (in one case there was even a
3002 If a test times out, the
3003 \begin_inset Flex Code
3006 \begin_layout Plain Layout
3012 command exits with error, but you can distinguish between a timed out test
3013 and a failed test in the output reported at the end of the
3014 \begin_inset Flex Code
3017 \begin_layout Plain Layout
3027 \begin_layout Standard
3029 \begin_inset Flex Code
3032 \begin_layout Plain Layout
3038 ) the full list of command line options.
3041 \begin_layout Paragraph
3045 \begin_layout Itemize
3046 run only the export tests:
3047 \begin_inset Flex Code
3050 \begin_layout Plain Layout
3059 \begin_layout Itemize
3061 \begin_inset Flex Code
3064 \begin_layout Plain Layout
3065 ctest -L "inverted|suspended"
3073 \begin_layout Itemize
3074 list all export tests which match any of the labelling patterns:
3075 \begin_inset Flex Code
3078 \begin_layout Plain Layout
3089 \begin_layout Itemize
3090 exclude rarely used output formats and post-processing tests
3091 \begin_inset Flex Code
3094 \begin_layout Plain Layout
3095 ctest -L export -E "_(texF|dvi3|pdf3?)"
3103 \begin_layout Paragraph
3104 \begin_inset CommandInset label
3106 name "subsec:Interpreting-export-tests"
3110 Interpreting the export test results
3113 \begin_layout Standard
3114 A test can fail for several reasons, not all of them bad.
3117 \begin_layout Enumerate
3118 A new or edited sample document may be incompatible with some output formats.
3121 \begin_layout Enumerate
3122 A dependency is not met (e.g.
3123 the \SpecialChar LaTeX
3125 One hint that this is the case is that the corresponding
3126 \begin_inset Flex Code
3129 \begin_layout Plain Layout
3135 test will likely also fail.
3138 \begin_layout Enumerate
3139 An inverted test fails to fail (i.e.
3140 export that previously failed now works).
3143 \begin_layout Enumerate
3144 An external dependency was updated (e.g.
3149 \begin_layout Enumerate
3150 A recent code change introduced a bug.
3153 \begin_layout Enumerate
3154 \begin_inset CommandInset label
3160 A change in a document exposed a previously unknown bug or an incompatibility
3161 with an export format (e.g.
3162 Lua\SpecialChar LaTeX
3166 \begin_layout Standard
3167 Because the .lyx files are exported in several formats, it is not surprising
3168 that many of the exports fail.
3169 This expectation of failure is addressed by
3170 \begin_inset Quotes eld
3174 \begin_inset Quotes erd
3177 the tests, that is, by marking the test as
3178 \begin_inset Quotes eld
3182 \begin_inset Quotes erd
3185 if the export exits with error and as
3186 \begin_inset Quotes eld
3190 \begin_inset Quotes erd
3193 if the export succeeds
3198 It follows that these expected failures will not show up as failed tests
3199 in the test results and thus will not pollute the
3200 \begin_inset Quotes eld
3204 \begin_inset Quotes erd
3208 If the export actually succeeds, then the test will fail.
3209 The purpose of this failure is to get your attention—something has changed,
3210 possibly for the better.
3213 \begin_layout Standard
3214 We try to document why a test is inverted or ignored.
3215 See the comment (prefixed with
3216 \begin_inset Flex Code
3219 \begin_layout Plain Layout
3225 ) above the block in which the test is listed as inverted or ignored in
3227 \begin_inset Flex Code
3230 \begin_layout Plain Layout
3231 development/autotests/invertedTests
3237 \begin_inset Flex Code
3240 \begin_layout Plain Layout
3241 development/autotests/unreliableTests
3247 \begin_inset Flex Code
3250 \begin_layout Plain Layout
3251 development/autotests/ignoredTests
3260 \begin_layout Standard
3261 A good question is why do we enable the tests for non-default formats? The
3262 answer is that if a non-default route is broken it is often because a bug
3263 was introduced in LyX and not because a document-specific change was made
3264 that is not supported by the route.
3265 In other words, there is a high signal/noise ratio in the export tests
3266 for some non-default formats.
3270 \begin_layout Standard
3271 When a test or several tests fail, consider checking the files in the
3272 \begin_inset Flex Code
3275 \begin_layout Plain Layout
3281 subdirectory of your build directory.
3282 In this subdirectory are three files: the file
3283 \begin_inset Flex Code
3286 \begin_layout Plain Layout
3292 simply lists the tests that failed on your last
3293 \begin_inset Flex Code
3296 \begin_layout Plain Layout
3303 \begin_inset Flex Code
3306 \begin_layout Plain Layout
3312 file contains the output from the tests (and often has details explaining
3313 why a test failed); and the
3314 \begin_inset Flex Code
3317 \begin_layout Plain Layout
3323 file lists the times that it took to run the tests.
3326 \begin_layout Paragraph
3327 What action should you take if a test fails?
3330 \begin_layout Standard
3331 \paragraph_spacing single
3332 It is always good to check manually why something fails and if it passes
3333 if the PDF output is good.
3336 \begin_layout Itemize
3337 Generally, if a change breaks compilation for the target format (for the
3338 manuals pdf2) without solving some important other issue,
3340 fix or revert the commit
3342 that led to failure.
3345 \begin_layout Itemize
3346 If it is not possible to (immediately) fix the failure but there are reasons
3347 not to revert the commit (e.g.
3348 it fixes another more important issue),
3352 the failing test case (see
3353 \begin_inset CommandInset ref
3355 reference "par:Inverted-tests"
3362 \begin_layout Itemize
3367 test case fails because the export now works,
3371 the test by removing the pattern from the
3372 \begin_inset Quotes eld
3376 \begin_inset Quotes erd
3380 \begin_inset CommandInset ref
3382 reference "par:Inverted-tests"
3389 \begin_layout Itemize
3390 If the export did not fail previously but led to wrong output (PDF, say),
3394 \begin_layout Plain Layout
3395 Non-failing test with wrong output should be labeledas
3396 \begin_inset Quotes eld
3399 unreliable:wrong_output
3400 \begin_inset Quotes erd
3404 \begin_inset CommandInset ref
3406 reference "par:Unreliable-tests"
3415 it is in fact an improvement when the test now fails.
3420 the failing test case (see
3421 \begin_inset CommandInset ref
3423 reference "par:Inverted-tests"
3430 \begin_layout Itemize
3431 In case of tests failing due to missing requirements (tests labeled
3432 \begin_inset Quotes eld
3435 unreliable:nonstandard
3436 \begin_inset Quotes erd
3439 or testing on a system with only a subset of TeXLive installed), ignore
3440 the failure, ask for someone else to run the test, or install the missing
3441 resources and try again.
3444 \begin_layout Itemize
3445 Check the log file Testing/Temporary/LastTest.log.
3446 In case of latex-errors rerun the failing test with environment variable
3447 'LAX_DEBUG_LATEX' set to '1'.
3448 This will include latex messages in LastTest.log, so it should be easier
3449 to interpret the fail-reason.
3452 \begin_layout Paragraph
3453 \begin_inset CommandInset label
3455 name "par:Inverted-tests"
3462 \begin_layout Standard
3463 Test cases whose name matches a pattern in the file
3464 \begin_inset Flex Code
3467 \begin_layout Plain Layout
3468 development/autotests/invertedTests
3478 They get also the test property
3479 \begin_inset Flex Code
3482 \begin_layout Plain Layout
3489 they are reported as failing if the export works without error
3490 \begin_inset Flex URL
3493 \begin_layout Plain Layout
3495 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3503 \begin_layout Standard
3504 Add failing cases to this file, if they cannot be solved
3505 \begin_inset Quotes eld
3509 \begin_inset Quotes erd
3512 but it is expected that the export will work in a foreseeable future, e.g.
3513 low priority issues like failures to export to a non-target format (for
3514 the manuals everything except pdf2).
3517 \begin_layout Standard
3518 The following sublabels are currently present in
3519 \begin_inset Flex Code
3522 \begin_layout Plain Layout
3531 \begin_layout Description
3532 todo test failures that require attention:
3536 \begin_layout Itemize
3537 minor issues to explore and properly sort later,
3540 \begin_layout Itemize
3544 \begin_layout Itemize
3545 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3549 \begin_layout Description
3550 lyxbugs LyX bugs with a Trac number.
3553 \begin_layout Description
3554 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3558 \begin_layout Standard
3559 "Wontfix" if demonstrating correct use and OK in the default output format.
3563 \begin_layout Description
3564 texissues Export fails due to LaTeX limitations like non-ASCII characters
3565 in verbatim or listings, incompatible packages, ...
3569 \begin_layout Standard
3570 "Wontfix" if documents demonstrate correct use in the default output format:
3573 \begin_layout Itemize
3574 If the source can be made more robust without becoming "hackish", fix the
3578 \begin_layout Itemize
3579 if LyX could be enhanced to care for a permanent TeX limitation, file a
3580 ticket at trac and add a pattern under lyxbugs,
3583 \begin_layout Itemize
3584 otherwise, add a pattern here.
3588 \begin_layout Description
3589 attic Documents in the attic (kept for reference and format conversion test).
3591 \begin_inset Quotes eld
3595 \begin_inset Quotes erd
3601 \begin_layout Subparagraph
3605 \begin_layout Standard
3606 Test cases whose name additionally matches a pattern in the file
3607 \begin_inset Flex Code
3610 \begin_layout Plain Layout
3611 development/autotests/suspendedTests
3629 This means they are not executed using
3630 \begin_inset Flex Code
3633 \begin_layout Plain Layout
3640 \begin_inset Flex Code
3643 \begin_layout Plain Layout
3650 However, they also get the test property
3651 \begin_inset Flex Code
3654 \begin_layout Plain Layout
3661 they are reported as failing if the export works without error.
3662 From time to time they still have to be checked using
3663 \begin_inset Flex Code
3666 \begin_layout Plain Layout
3675 \begin_layout Standard
3676 These tests are suspended, because the export fails for known reasons which
3677 cannot ATM be resolved.
3678 But it is expected the reason might disappear in the future.
3679 Be it new TL or better handling in \SpecialChar LyX
3683 \begin_layout Standard
3684 For ctest commands without the
3685 \begin_inset Flex Code
3688 \begin_layout Plain Layout
3694 parameter nothing changes.
3695 Suspended or not, tests will be executed depending only on the selecting
3696 regular expression given to the ctest command (see
3697 \begin_inset CommandInset ref
3699 reference "par:ctest-options"
3706 \begin_layout Paragraph
3707 \begin_inset CommandInset label
3709 name "par:Unreliable-tests"
3716 \begin_layout Standard
3717 Test cases whose name matches a pattern in the file
3718 \begin_inset Flex Code
3721 \begin_layout Plain Layout
3722 development/autotests/unreliableTests
3734 \begin_layout Standard
3735 These tests are not executed using
3736 \begin_inset Flex Code
3739 \begin_layout Plain Layout
3746 \begin_inset Flex Code
3749 \begin_layout Plain Layout
3759 \begin_layout Standard
3760 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3761 or pass but should rather fail (wrong output).
3763 \begin_inset Note Note
3766 \begin_layout Plain Layout
3767 *invalid* tests (wrong output) are not *unreliable*.
3768 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3777 \begin_layout Standard
3778 The following sublabels are currently present in
3779 \begin_inset Flex Code
3782 \begin_layout Plain Layout
3791 \begin_layout Description
3792 nonstandard Documents with additional requirements, e.g.
3793 a class or package file not in TeXLive.
3795 \begin_inset Note Note
3798 \begin_layout Plain Layout
3800 \begin_inset Quotes eld
3804 \begin_inset Quotes erd
3808 \begin_inset Quotes eld
3812 \begin_inset Quotes erd
3823 \begin_layout Description
3824 erratic Tests depending on local configuration or the phase of the moon.
3828 \begin_layout Description
3829 varying_versions Test depending on TeX distribution, package versions or
3833 \begin_layout Description
3835 \begin_inset space ~
3838 output Export does not fail but the resulting document has (undetected)
3843 \begin_layout Standard
3844 \paragraph_spacing single
3845 \begin_inset Note Note
3848 \begin_layout Plain Layout
3849 \paragraph_spacing single
3850 These tests are in a strict sense not unreliable but
3854 (not measuring what they should measure).
3863 \begin_layout Paragraph
3864 \begin_inset CommandInset label
3866 name "par:Export-test-filtering"
3870 Export test filtering
3873 \begin_layout Standard
3874 The assignment of a label to a test is controlled by a set of files with
3875 regular expressions that are matched against the test names.
3878 \begin_layout Description
3879 ignoredTests (small file)
3880 \begin_inset Newline newline
3883 Tests selected here are withdrawn in the configuration step (cf.
3885 \begin_inset CommandInset ref
3887 reference "par:Configuring-ctests"
3895 \begin_layout Labeling
3896 \labelwidthstring 00.00.0000
3897 Input Test of any export combination
3900 \begin_layout Labeling
3901 \labelwidthstring 00.00.0000
3902 Output Stop if tests not selected here
3906 \begin_layout Description
3907 unreliableTests: Tests selected pass or fail dependent on the system where
3909 Selected tests gain the label 'unreliable'.
3913 \begin_layout Labeling
3914 \labelwidthstring 00.00.0000
3915 Input Each test which passed 'ignoredTests'
3918 \begin_layout Labeling
3919 \labelwidthstring 00.00.0000
3920 Output Stop if test selected, gain label 'unreliable'.
3924 \begin_layout Description
3926 \begin_inset space \space{}
3933 \begin_layout Labeling
3934 \labelwidthstring 00.00.0000
3935 Input Each test which passed 'unreliableTests'
3938 \begin_layout Labeling
3939 \labelwidthstring 00.00.0000
3940 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3941 tests are reported as failing if the export works without error.) If no
3942 subselection applies, gain labels 'export' and 'inverted'.
3945 \begin_layout Standard
3946 The following filter perfoms a subselection of 'invertedTests':
3949 \begin_layout Description
3950 suspendedTests Tests selected here gain the label 'suspended' but _not_
3951 'export' or 'inverted', although in ctest they remain inverted.
3952 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3956 \begin_layout Labeling
3957 \labelwidthstring 00.00.0000
3958 Input Each test selected by 'invertedTests'
3961 \begin_layout Labeling
3962 \labelwidthstring 00.00.0000
3963 Output Selected test gains label 'suspended'.
3969 \begin_layout Standard
3970 The following table may clarify label assignement
3973 \begin_layout Standard
3974 \begin_inset Tabular
3975 <lyxtabular version="3" rows="7" columns="9">
3976 <features tabularvalignment="middle">
3977 <column alignment="left" valignment="top" width="0pt">
3978 <column alignment="left" valignment="top" width="0pt">
3979 <column alignment="left" valignment="top" width="0pt">
3980 <column alignment="left" valignment="top" width="0pt">
3981 <column alignment="center" valignment="top">
3982 <column alignment="center" valignment="top">
3983 <column alignment="center" valignment="top">
3984 <column alignment="center" valignment="top">
3985 <column alignment="center" valignment="top">
3987 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3990 \begin_layout Plain Layout
3991 Test matching pattern in file:
3996 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3999 \begin_layout Plain Layout
4005 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4008 \begin_layout Plain Layout
4014 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4017 \begin_layout Plain Layout
4023 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4026 \begin_layout Plain Layout
4032 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4035 \begin_layout Plain Layout
4041 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4044 \begin_layout Plain Layout
4050 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4053 \begin_layout Plain Layout
4059 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4062 \begin_layout Plain Layout
4070 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4073 \begin_layout Plain Layout
4079 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4082 \begin_layout Plain Layout
4088 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4091 \begin_layout Plain Layout
4097 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4100 \begin_layout Plain Layout
4106 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4109 \begin_layout Plain Layout
4115 <cell alignment="center" valignment="top" topline="true" usebox="none">
4118 \begin_layout Plain Layout
4124 <cell alignment="center" valignment="top" topline="true" usebox="none">
4127 \begin_layout Plain Layout
4133 <cell alignment="center" valignment="top" topline="true" usebox="none">
4136 \begin_layout Plain Layout
4142 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4145 \begin_layout Plain Layout
4153 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4156 \begin_layout Plain Layout
4162 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4165 \begin_layout Plain Layout
4171 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4174 \begin_layout Plain Layout
4180 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4183 \begin_layout Plain Layout
4189 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4192 \begin_layout Plain Layout
4198 <cell alignment="center" valignment="top" topline="true" usebox="none">
4201 \begin_layout Plain Layout
4207 <cell alignment="center" valignment="top" topline="true" usebox="none">
4210 \begin_layout Plain Layout
4216 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4219 \begin_layout Plain Layout
4225 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4228 \begin_layout Plain Layout
4236 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4239 \begin_layout Plain Layout
4245 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4248 \begin_layout Plain Layout
4254 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4257 \begin_layout Plain Layout
4263 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4266 \begin_layout Plain Layout
4272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4275 \begin_layout Plain Layout
4281 <cell alignment="center" valignment="top" topline="true" usebox="none">
4284 \begin_layout Plain Layout
4290 <cell alignment="center" valignment="top" topline="true" usebox="none">
4293 \begin_layout Plain Layout
4299 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4302 \begin_layout Plain Layout
4308 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4311 \begin_layout Plain Layout
4319 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4322 \begin_layout Plain Layout
4328 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4331 \begin_layout Plain Layout
4337 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4340 \begin_layout Plain Layout
4346 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4349 \begin_layout Plain Layout
4355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4358 \begin_layout Plain Layout
4364 <cell alignment="center" valignment="top" topline="true" usebox="none">
4367 \begin_layout Plain Layout
4373 <cell alignment="center" valignment="top" topline="true" usebox="none">
4376 \begin_layout Plain Layout
4382 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4385 \begin_layout Plain Layout
4391 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4394 \begin_layout Plain Layout
4402 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4405 \begin_layout Plain Layout
4411 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4414 \begin_layout Plain Layout
4420 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4423 \begin_layout Plain Layout
4429 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4432 \begin_layout Plain Layout
4438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4441 \begin_layout Plain Layout
4447 <cell alignment="center" valignment="top" topline="true" usebox="none">
4450 \begin_layout Plain Layout
4456 <cell alignment="center" valignment="top" topline="true" usebox="none">
4459 \begin_layout Plain Layout
4465 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4468 \begin_layout Plain Layout
4474 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4477 \begin_layout Plain Layout
4485 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4488 \begin_layout Plain Layout
4494 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4497 \begin_layout Plain Layout
4503 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4506 \begin_layout Plain Layout
4512 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4515 \begin_layout Plain Layout
4521 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4524 \begin_layout Plain Layout
4530 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4533 \begin_layout Plain Layout
4539 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4542 \begin_layout Plain Layout
4548 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4551 \begin_layout Plain Layout
4557 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4560 \begin_layout Plain Layout
4574 \begin_layout Standard
4575 \begin_inset Note Note
4578 \begin_layout Plain Layout
4580 \begin_inset Quotes eld
4584 \begin_inset Quotes erd
4587 filter, this would be far less complicated:
4590 \begin_layout Plain Layout
4591 \begin_inset Tabular
4592 <lyxtabular version="3" rows="6" columns="7">
4593 <features tabularvalignment="middle">
4594 <column alignment="left" valignment="top" width="0pt">
4595 <column alignment="left" valignment="top" width="0pt">
4596 <column alignment="left" valignment="top" width="0pt">
4597 <column alignment="center" valignment="top">
4598 <column alignment="center" valignment="top">
4599 <column alignment="center" valignment="top">
4600 <column alignment="center" valignment="top">
4602 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4605 \begin_layout Plain Layout
4606 Test matching pattern in file:
4611 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4614 \begin_layout Plain Layout
4620 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4623 \begin_layout Plain Layout
4629 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4632 \begin_layout Plain Layout
4638 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4641 \begin_layout Plain Layout
4647 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4650 \begin_layout Plain Layout
4656 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4659 \begin_layout Plain Layout
4667 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4670 \begin_layout Plain Layout
4676 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4679 \begin_layout Plain Layout
4685 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4688 \begin_layout Plain Layout
4694 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4697 \begin_layout Plain Layout
4703 <cell alignment="center" valignment="top" topline="true" usebox="none">
4706 \begin_layout Plain Layout
4712 <cell alignment="center" valignment="top" topline="true" usebox="none">
4715 \begin_layout Plain Layout
4721 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4724 \begin_layout Plain Layout
4732 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4735 \begin_layout Plain Layout
4741 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4744 \begin_layout Plain Layout
4750 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4753 \begin_layout Plain Layout
4759 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4762 \begin_layout Plain Layout
4768 <cell alignment="center" valignment="top" topline="true" usebox="none">
4771 \begin_layout Plain Layout
4777 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4780 \begin_layout Plain Layout
4786 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4789 \begin_layout Plain Layout
4797 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4800 \begin_layout Plain Layout
4806 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4809 \begin_layout Plain Layout
4815 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4818 \begin_layout Plain Layout
4824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4827 \begin_layout Plain Layout
4833 <cell alignment="center" valignment="top" topline="true" usebox="none">
4836 \begin_layout Plain Layout
4842 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4845 \begin_layout Plain Layout
4851 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4854 \begin_layout Plain Layout
4862 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4865 \begin_layout Plain Layout
4871 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4874 \begin_layout Plain Layout
4880 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4883 \begin_layout Plain Layout
4889 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4892 \begin_layout Plain Layout
4898 <cell alignment="center" valignment="top" topline="true" usebox="none">
4901 \begin_layout Plain Layout
4907 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4910 \begin_layout Plain Layout
4916 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4919 \begin_layout Plain Layout
4927 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4930 \begin_layout Plain Layout
4936 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4939 \begin_layout Plain Layout
4945 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4948 \begin_layout Plain Layout
4954 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4957 \begin_layout Plain Layout
4963 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4966 \begin_layout Plain Layout
4972 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4975 \begin_layout Plain Layout
4981 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4984 \begin_layout Plain Layout
5003 \begin_layout Subsubsection
5007 \begin_layout Standard
5008 These tests check whether a .lyx file loads without any terminal messages.
5009 They correspond to the manual operations of simply opening a .lyx file on
5010 the terminal, exiting LyX once the file is loaded, and then checking whether
5011 there is any output from the terminal.
5012 These tests are useful for catching malformed .lyx files and parsing bugs.
5013 They can also be used to find a .lyx file in which an instance of something
5015 To do this, compile LyX with a local patch that outputs something to the
5016 terminal when an instance is found, and then run the check_load tests to
5017 see if any fail, which would mean that the situation occurs in the LyX
5018 documentation files corresponding to the failed tests.
5019 These tests are expectedly fragile: any LyX diagnostic message, which is
5020 not necessarily an error, would cause the tests to fail.
5021 Similarly, any message output by a library (e.g.
5022 Qt) would also cause failure.
5023 There are some messages that the check_load tests are instructed to ignore,
5024 which are stored in the file
5025 \begin_inset Flex Code
5028 \begin_layout Plain Layout
5029 development/autotests/filterCheckWarnings
5037 \begin_layout Standard
5038 Under cmake, the tests are labeled as 'load'.
5041 \begin_layout Subsubsection
5045 \begin_layout Standard
5046 Automated tests based on the "MonKey Testing" keytest program are enabled
5047 if the necessary dependencies are found and if the CMake flag
5048 \begin_inset Flex Code
5051 \begin_layout Plain Layout
5052 -DLYX_ENABLE_KEYTESTS=ON
5058 They are documented in the README document in
5059 \begin_inset Flex Code
5062 \begin_layout Plain Layout
5063 development/autotests
5068 subfolder of the \SpecialChar LyX
5069 source code distribution.
5072 \begin_layout Subsubsection
5076 \begin_layout Standard
5077 These tests combine lyx2lyx tests with check_load tests.
5078 They fail if either fails.
5081 \begin_layout Subsubsection
5085 \begin_layout Standard
5086 The URL tests are enabled with the
5087 \begin_inset Flex Code
5090 \begin_layout Plain Layout
5091 -DLYX_ENABLE_URLTESTS=ON
5096 CMake flag and are useful for finding broken links in our documentation
5098 If a URL test fails, to see which link in particular was reported as broken,
5100 \begin_inset Flex Code
5103 \begin_layout Plain Layout
5110 These tests are extremely fragile (e.g.
5111 a test can depend on your Internet connection) and a failed URL test should
5112 not be taken too seriously.
5113 URL tests are labeled as
5118 \begin_layout Paragraph
5122 \begin_layout Standard
5123 cmake is required to run the \SpecialChar LyX
5124 tests, running them is not implemented for
5128 \begin_layout Standard
5129 The appropriate commands are:
5132 \begin_layout Itemize
5138 \begin_inset Newline newline
5141 runs all tests with label
5146 \begin_layout Itemize
5149 ctest -R 'check_.*urls'
5152 \begin_inset Newline newline
5155 runs the tests 'check_accessible_urls'
5158 \begin_layout Standard
5159 Associated test results can be examined in ctest-log directory in files
5160 of the form 'LastFailed.*URLS.log'
5163 \begin_layout Section
5164 Development policies
5167 \begin_layout Standard
5168 This chapter lists some guidelines that should be followed.
5169 This list is not complete, and many guidelines are in separate chapters,
5171 \begin_inset Quotes eld
5174 When is an update of the .lyx file format number needed?
5175 \begin_inset Quotes erd
5179 \begin_inset CommandInset ref
5181 reference "sec:When-is-an"
5188 \begin_layout Subsection
5189 When to set a fixed milestone?
5192 \begin_layout Standard
5193 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5197 \begin_layout Enumerate
5198 Somebody is actively working on a fix.
5201 \begin_layout Enumerate
5202 The bug is so severe that it would block the release if it is not fixed.
5205 \begin_layout Standard
5206 If a bug is important, but nobody is working on it, and it is no showstopper,
5207 use a milestone like 2.1.x or 2.2.x.
5208 For all other bugs, do not set a milestone at all.
5211 \begin_layout Subsection
5212 Can we add rc entries in stable branch?
5215 \begin_layout Standard
5217 We are supposed to increase the prefs2prefs version number with such things.
5220 \begin_layout Section
5221 \begin_inset CommandInset label
5223 name "sec:Documentation-policies"
5227 Documentation policies
5230 \begin_layout Subsection
5234 \begin_layout Standard
5236 \begin_inset space ~
5239 rules in editing the docs:
5242 \begin_layout Enumerate
5243 \begin_inset CommandInset label
5245 name "enu:If-you-are"
5249 If you are not the maintainer of a doc file or a chapter/section, you MUST
5250 use change tracking so that the maintainer could review your changes
5253 \begin_layout Enumerate
5254 Respect the formatting of the document.
5255 The different files use different formatting styles.
5256 That is OK and has historic reasons nobody fully knows ;-).
5257 But it is important to be consistent within one file.
5260 \begin_layout Enumerate
5261 All changes you make to a file in one language MUST also go the file in
5262 the other actively maintained languages.
5263 Normally the maintainer does this for you, if you are the maintainer, you
5264 must do this by copying or changing the changed or added text to the other
5265 files so that the translators sees the blue underlined text and know what
5266 they have to translate and what was changed.
5269 \begin_layout Enumerate
5270 You MUST assure that the document is compilable as
5271 \begin_inset Quotes eld
5275 \begin_inset Quotes erd
5278 or the document's default output format after your changes.
5281 \begin_layout Enumerate
5282 All fixes (typos, compilation fixes, updates info etc.) go at first into
5283 the current GIT branch because the user should benefit from all fixes with
5284 every minor release.
5285 Feel free to commit directly to branch as long as you follow rule
5286 \begin_inset space ~
5290 \begin_inset CommandInset ref
5292 reference "enu:If-you-are"
5297 You can immediately commit to master as well.
5300 \begin_layout Enumerate
5301 \begin_inset CommandInset label
5303 name "enu:The-fileformat-of"
5307 The fileformat of a file must not be changed unless you document a new feature
5308 in LyX that requires a new fileformat.
5309 The reason for this rule is to keep it easy for the doc maintainers to
5310 port/backport changes to from master/branch.
5313 \begin_layout Standard
5314 The main documentation consists of these files:
5317 \begin_layout Description
5318 splash.lyx it is the first file you see after an installation.
5319 We assume that a new user sees this.
5320 It is therefore designed to be as simple as possible.
5321 Therefore please don't add any new formatting, only fix typos etc.
5322 Splash.lyx is up to date for \SpecialChar LyX
5323 2.1.x, currently maintained by Uwe Stöhr.
5326 \begin_layout Description
5327 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5329 It therefore uses a limited set of formatting.
5330 For example a standard document class.
5331 Since new users will first learn about the formatting possibilities of
5333 please keep this file that simple.
5334 Intro.lyx is up to date for \SpecialChar LyX
5335 2.1.x, currently maintained by Uwe Stöhr.
5338 \begin_layout Description
5339 Tutorial.lyx our tutorial.
5340 It must be always up to date.
5341 Normally there is nothing to add since we don't want to overwhelm new users
5342 with too much details.
5343 The will learn these details while using \SpecialChar LyX
5344 and we have special manuals.
5345 Tutorial.lyx is up to date for \SpecialChar LyX
5346 2.1.x, currently maintained by Uwe Stöhr.
5349 \begin_layout Description
5350 UserGuide.lyx our main user guide.
5351 It covers a mixture of basic and detailed information.
5352 Some information is also in the Math and EmbeddedObjects manual so that
5353 the UserGuide refers to these files.
5354 UserGuide.lyx is up to date for \SpecialChar LyX
5355 2.1.x, currently maintained by Uwe Stöhr.
5358 \begin_layout Description
5359 EmbeddedObjects.lyx a special manual to explain things like tables floats
5362 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5363 2.1.x, currently maintained by Uwe
5367 \begin_layout Description
5368 Math.lyx a special manual to explain everything regarding math in all detail.
5369 Math.lyx is up to date for \SpecialChar LyX
5370 2.1.x, currently maintained by Uwe Stöhr.
5373 \begin_layout Description
5374 Additional.lyx this manual covers information that would be too much detail
5375 for the UserGuide or would make the UserGuide uncompilable or only compilable
5376 when installing a lot of special \SpecialChar LaTeX
5378 What should be in the UserGuide or better in Additional is a matter of
5380 it is up to you to decide that.
5381 Additional.lyx is not completely up to date for \SpecialChar LyX
5384 \begin_inset space ~
5387 8 is up to date and currently maintained by Uwe Stöhr.
5388 It certainly needs a rewrite and update.
5389 For example many info in chapter
5390 \begin_inset space ~
5393 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5397 \begin_layout Description
5398 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5400 output formats, operating systems, languages etc.
5401 It is currently completely out of date and needs a major rewrite and update.
5402 If you do this please assure that your information are given for all OSes
5403 and \SpecialChar LaTeX
5404 distributions (meaning be as objective as possible).