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 0
61 \use_package stackrel 0
62 \use_package stmaryrd 0
63 \use_package undertilde 0
65 \cite_engine_type default
69 \paperorientation portrait
73 \notefontcolor #0000ff
80 \paragraph_separation indent
81 \paragraph_indentation default
87 \paperpagestyle headings
88 \tracking_changes false
98 Developing \SpecialChar LyX
102 \begin_layout Subtitle
107 by the \SpecialChar LyX
112 \begin_layout Plain Layout
114 If you have comments or error corrections, please send them to the \SpecialChar LyX
117 \begin_inset Flex Code
120 \begin_layout Plain Layout
122 <lyx-docs@lists.lyx.org>
135 \begin_layout Standard
136 \begin_inset CommandInset toc
137 LatexCommand tableofcontents
144 \begin_layout Section
148 \begin_layout Standard
149 This manual documents some aspects of \SpecialChar LyX
151 It is currently rather incomplete, but will hopefully be extended in the
153 Meanwhile, additional information can be found in the
154 \begin_inset Flex Code
157 \begin_layout Plain Layout
163 subfolder of the \SpecialChar LyX
164 source code distribution.
165 This document is not translated, since the development language of \SpecialChar LyX
168 If you just want to use \SpecialChar LyX
169 , then you don't need to read this manual.
170 However, if you want to learn more about how \SpecialChar LyX
171 is developed, or even want
172 to participate in \SpecialChar LyX
173 development, you may find some interesting information
177 \begin_layout Section
181 \begin_layout Standard
183 uses several custom file formats for configuration files and documents.
184 This chapter contains some background concerning these file formats.
185 Several file formats are also described in detail in the regular user documenta
189 \begin_layout Subsection
193 \begin_layout Subsection
194 When is an update of the .lyx file format number needed?
195 \begin_inset CommandInset label
197 name "sec:When-is-an"
204 \begin_layout Standard
205 When you are working on a new feature you may ask yourself whether it needs
206 an update of the .lyx file format number.
207 Whether an update is needed or not is not always obvious.
212 Whenever there is the danger that a previous version of LyX cannot open
213 a file using the new feature, a file format update is needed.
216 \begin_layout Standard
217 The file format change allows lyx2lyx rules to implement backwards compatibility.
218 Below you can find a list of reasons for file format updates with explanations:
221 \begin_layout Description
230 setting Whenever you introduce a new setting that is stored in the document
231 header, a file format update is needed.
234 \begin_layout Description
243 setting If a certain setting becomes obsolete and gets removed, a file format
247 \begin_layout Description
273 \begin_inset space \thinspace{}
280 \begin_layout Description
281 \paragraph_spacing single
294 package The reason for this is that there is no true ERT inset for math
295 formulas: Each command is parsed, and if a user happens to define a local
296 command with the same name as a command that triggers an automatic load
297 of a package, they need to be able to switch off the automatic loading
299 This switch is stored by the
300 \begin_inset Flex Code
303 \begin_layout Plain Layout
312 \begin_layout Description
317 language that is stored in
318 \begin_inset Flex Code
321 \begin_layout Plain Layout
331 \begin_inset Note Note
334 \begin_layout Plain Layout
335 This requirement is under discussion.
344 \begin_layout Description
349 inset Of course a new inset requires a file format update.
352 \begin_layout Description
357 style If a new style or inset layout is added to any layout file or module
358 shipped with \SpecialChar LyX
359 , then a new file format is needed in the master (development)
361 It is possible to backport new styles to the stable version without a file
364 \begin_inset CommandInset ref
366 reference "subsec:Backporting-new-styles"
370 for more information.
373 \begin_layout Description
378 style If a style or inset layout is removed in any layout file or module
379 shipped with \SpecialChar LyX
380 , a new file format is required.
383 \begin_layout Standard
388 layouts and modules do
392 require a file format update (changed 03/16, see
393 \begin_inset CommandInset ref
395 reference "subsec:New-layouts"
403 \begin_layout Standard
404 If you are still unsure, please ask on the development list.
407 \begin_layout Subsection
408 \begin_inset CommandInset label
410 name "subsec:update_lyx_files"
414 How to update the file format number of .lyx files
417 \begin_layout Standard
418 Once you come to the conclusion that a file format update is needed, you
419 should use the following procedure to perform the update:
422 \begin_layout Enumerate
423 Implement and test the new feature, including the reading and writing of
425 Note that any file produced at this stage does not use a valid format,
426 so do not use this version of \SpecialChar LyX
427 for working on any important documents.
430 \begin_layout Enumerate
431 \begin_inset CommandInset label
433 name "enu:Describe_format"
437 Describe the new format in
438 \begin_inset Flex Code
441 \begin_layout Plain Layout
450 \begin_layout Enumerate
451 Update the \SpecialChar LyX
452 file format number in
453 \begin_inset Flex Code
456 \begin_layout Plain Layout
465 \begin_layout Enumerate
466 \begin_inset CommandInset label
468 name "enu:Add-an-entry"
472 Add an entry to both format lists (for conversion and reversion) in
473 \begin_inset Newline newline
477 \begin_inset Flex Code
480 \begin_layout Plain Layout
481 lib/lyx2lyx/lyx_2_3.py
487 Add a conversion routine if needed (e.
488 \begin_inset space \thinspace{}
491 g., a new header setting always needs a conversion that adds the new setting,
492 but a new document language does not need one).
493 Add a reversion routine if needed.
495 \begin_inset Newline newline
498 While the conversion routine is required to produce a document that is equivalen
499 t to the old version, the requirements of the reversion are not that strict.
500 If possible, try to produce a proper reversion, using ERT if needed, but
501 for some features this might be too complicated.
502 In this case, the minimum requirement of the reversion routine is that
503 it produces a valid document which can be read by an older \SpecialChar LyX
505 If absolutely needed, even data loss is allowed for the reversion.
506 (In that case, you might want to add a LyX comment that indicates what
507 you have had to do, so the user is at least warned).
510 \begin_layout Enumerate
511 Since tex2lyx has several implicit file format dependencies caused by sharing
512 code with \SpecialChar LyX
513 , updating the file format of .lyx files produced by tex2lyx at
514 the same time as updating the main .lyx file format is strongly recommended.
515 Therefore, a compiler warning will be issued if the \SpecialChar LyX
516 and tex2lyx .lyx file
517 format numbers differ.
518 In many cases the tex2lyx update requires only the first and last item
523 \begin_layout Enumerate
524 Update the tex2lyx file format number in
525 \begin_inset Flex Code
528 \begin_layout Plain Layout
537 \begin_layout Enumerate
538 If the lyx2lyx conversion from the old to the new format is empty, or if
539 tex2lyx does not yet output the changed feature, you do not need any further
541 Otherwise, search for the changed feature in tex2lyx, and adjust the output
542 according to the lyx2lyx changes.
545 \begin_layout Enumerate
546 Update the tex2lyx test references as described in
547 \begin_inset CommandInset ref
548 LatexCommand formatted
549 reference "sec:Updating-test-references"
557 \begin_layout Enumerate
558 If you did not implement full tex2lyx support for the new feature, add a
560 \begin_inset Flex Code
563 \begin_layout Plain Layout
569 describing the missing bits.
570 Note that it is perfectly fine if you do not add full tex2lyx support for
571 a new feature: The updating recommendation above is only issued for the
572 syntax of the produced .lyx file.
573 It is no problem if some features supported by \SpecialChar LyX
574 are still output as ERT
576 The problems in the past that resulted in the update recommendation were
577 related to mixed version syntax, not ERT.
580 \begin_layout Enumerate
581 It would be nice if you could create a .lyx test file which contains instances
582 of all changed or added features.
583 This could then be used to test lyx2lyx and tex2lyx.
584 Unfortunately, it has not yet been decided how to collect such examples,
585 so please ask on the development list if you want to create one.
588 \begin_layout Enumerate
589 \begin_inset CommandInset label
591 name "enu:updatefiles"
595 Test your lyx2lyx code by updating LyX's .lyx documentation files to the
597 The developer who makes the change knows best what changes to expect when
598 inspecting the resulting diff.
599 Because of this, you might be able to catch a bug in the lyx2lyx code that
600 updates the format just by taking a quick scan through the large diff that
602 \begin_inset Note Note
605 \begin_layout Plain Layout
606 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
607 see which layout update made an unexpected change by looking at the git
608 log of a .lyx file that suffers the problem.
613 To do this, first make sure that there are no changes to the git repository
614 that you will not want to commit (this is needed because it will be convenient
615 to commit with the command
616 \begin_inset Flex Code
619 \begin_layout Plain Layout
626 Then run the following command in the root folder of the source:
627 \begin_inset Flex Code
630 \begin_layout Plain Layout
631 python development/tools/updatedocs.py
637 Look at the resulting changes using the command
638 \begin_inset Flex Code
641 \begin_layout Plain Layout
648 If anything looks surprising, please investigate.
649 Keep in mind that the case of
650 \begin_inset Flex Code
653 \begin_layout Plain Layout
659 is special, because it is first generated with
660 \begin_inset Flex Code
663 \begin_layout Plain Layout
669 before being converted to the latest format.
670 \begin_inset Newline newline
674 \begin_inset Note Greyedout
677 \begin_layout Plain Layout
682 Only commit file format changes in the doc files if these files are using
683 the new feature of the new file format.
689 \begin_inset CommandInset ref
691 reference "enu:The-fileformat-of"
695 of the documentation policies described in sec.
700 \begin_inset CommandInset ref
702 reference "sec:Documentation-policies"
714 \begin_layout Enumerate
715 Finally, commit using
716 \begin_inset Flex Code
719 \begin_layout Plain Layout
728 \begin_layout Subsection
729 Updating the file format number of layout files
732 \begin_layout Standard
733 The procedure for updating the layout files is similar to that in step
734 \begin_inset CommandInset ref
736 reference "enu:updatefiles"
741 \begin_inset CommandInset ref
743 reference "subsec:update_lyx_files"
749 \begin_inset Flex Code
752 \begin_layout Plain Layout
753 python development/tools/updatelayouts.py
759 \begin_inset Flex Code
762 \begin_layout Plain Layout
771 \begin_layout Standard
772 Note that we do not automatically update any local layout used in the
773 \begin_inset Flex Code
776 \begin_layout Plain Layout
782 files shipped with \SpecialChar LyX
783 because users would then not be able to export to older
785 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
786 to open the file in \SpecialChar LyX
787 2.1.x, there would be an error because the file would
788 contain a local layout whose format is too new.
789 The root reason for this is that we do not support converting layouts to
790 older layout formats, as we do for the
791 \begin_inset Flex Code
794 \begin_layout Plain Layout
803 \begin_layout Subsection
804 Updating the file format number of bind/ui files
807 \begin_layout Standard
808 A change to the functionality of existing LFUNs can require a conversion
810 \begin_inset Flex Code
813 \begin_layout Plain Layout
820 \begin_inset Flex Code
823 \begin_layout Plain Layout
829 files, and therefore an increment of the LFUN format, as well as a conversion
831 \begin_inset Flex Code
834 \begin_layout Plain Layout
841 The latter cannot be done automatically and also requires an update of
845 \begin_inset space \space{}
848 of someone who might have made a set of \SpecialChar LyX
849 teaching manuals for use in their
854 \begin_layout Plain Layout
855 \begin_inset Flex URL
858 \begin_layout Plain Layout
860 http://www.lyx.org/trac/ticket/9794
873 \begin_layout Standard
874 To update the LFUN format:
877 \begin_layout Enumerate
878 Increment the LFUN file format number in
879 \begin_inset Flex Code
882 \begin_layout Plain Layout
891 \begin_layout Enumerate
892 Implement the LFUN conversion in
893 \begin_inset Flex Code
896 \begin_layout Plain Layout
897 lib/scripts/prefs2prefs_lfuns.py
905 \begin_layout Enumerate
907 \begin_inset CommandInset ref
909 reference "enu:updatefiles"
914 \begin_inset CommandInset ref
916 reference "subsec:update_lyx_files"
921 \begin_inset Flex Code
924 \begin_layout Plain Layout
930 command, use this command:
931 \begin_inset Flex Code
934 \begin_layout Plain Layout
935 bash development/tools/updatelfuns.sh
942 \begin_inset Note Note
945 \begin_layout Plain Layout
946 This file should really be converted to python.
954 \begin_layout Enumerate
955 Update Info insets in
956 \begin_inset Flex Code
959 \begin_layout Plain Layout
966 To do so, increment the \SpecialChar LyX
967 format and proceed as in
968 \begin_inset CommandInset ref
970 reference "subsec:update_lyx_files"
975 \begin_inset CommandInset ref
977 reference "enu:Describe_format"
982 \begin_inset CommandInset ref
984 reference "enu:updatefiles"
989 In the lyx2lyx implementation (step
990 \begin_inset CommandInset ref
992 reference "enu:Add-an-entry"
996 ), implement a conversion similar to the one in
997 \begin_inset Flex Code
1000 \begin_layout Plain Layout
1001 prefs2prefs_lfuns.py
1006 above, as well as a corresponding reversion; for this one can use
1007 \begin_inset Flex Code
1010 \begin_layout Plain Layout
1017 \begin_inset Flex Code
1020 \begin_layout Plain Layout
1021 lib/lyx2lyx/lyx2lyx_tools.py
1030 \begin_layout Subsection
1031 Backporting new styles to the stable version
1032 \begin_inset CommandInset label
1034 name "subsec:Backporting-new-styles"
1041 \begin_layout Standard
1042 Starting with the stable \SpecialChar LyX
1043 2.1 branch, there is a mechanism in place to backport
1044 new styles to the stable version without the need to update the file format.
1045 The basic idea is that the new style definition is automatically copied
1046 to the document preamble so that it can even be used by older minor versions
1047 that did not yet include the style.
1048 To backport a new style to the stable version, the following steps are
1052 \begin_layout Enumerate
1054 \begin_inset Flex Code
1057 \begin_layout Plain Layout
1063 to the style definition in the development version.
1066 \begin_layout Enumerate
1067 Copy the style definition to the stable version, but use
1068 \begin_inset Flex Code
1071 \begin_layout Plain Layout
1078 If needed adjust the format to the one used by the stable version (see
1079 the customization manual for details of the layout file format).
1082 \begin_layout Enumerate
1083 For each update of the style in a later stable version, increase the argument
1085 \begin_inset Flex Code
1088 \begin_layout Plain Layout
1095 (In the stable version, the development version should not be touched.)
1098 \begin_layout Standard
1099 For details about the
1100 \begin_inset Flex Code
1103 \begin_layout Plain Layout
1109 flag see the customization manual.
1111 \begin_inset Flex Code
1114 \begin_layout Plain Layout
1120 support is needed for backported styles: Since the style of the development
1121 version has an infinite version number, it will always be used.
1122 Furthermore, since its version number is less than one, the style will
1123 not be written anymore to the document header for files saved by the new
1127 \begin_layout Section
1128 New layouts and modules
1131 \begin_layout Subsection
1132 \begin_inset CommandInset label
1134 name "subsec:New-layouts"
1141 \begin_layout Standard
1142 Adding a new layout file to the \SpecialChar LyX
1144 \begin_inset Quotes eld
1147 officially supported
1148 \begin_inset Quotes erd
1152 You should therefore think carefully about whether you really want to do
1153 this and discuss it on lyx-devel, since you will need to be prepared to
1154 update and fix the layout if necessary.
1155 If the layout is experimental or for a rarely used document class, then
1156 it may be better to add it to the relevant portion of the \SpecialChar LyX
1160 \begin_inset CommandInset href
1162 target "https://wiki.lyx.org/Layouts/Layouts"
1170 \begin_layout Standard
1171 In older versions of this document, it was stated that new layout files
1172 require a file format change.
1173 After some discussion, it was decided that this is not needed.
1177 \begin_layout Plain Layout
1179 \begin_inset CommandInset href
1181 name "the thread “Proposal for a guide on updating layouts”"
1182 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1196 For reference, here are the arguments on each side
1200 \begin_layout Description
1202 \begin_inset Quotes eld
1205 New layout files are a file format change
1206 \begin_inset Quotes erd
1212 \begin_layout Itemize
1213 All documents produced by 2.2.
1214 \begin_inset Formula $x$
1217 can always be edited and exported even if
1218 \begin_inset Formula $x$
1222 This is important for people using different machines, or exchanging work
1226 \begin_layout Description
1228 \begin_inset Quotes eld
1231 New layout files are not a file format change
1232 \begin_inset Quotes erd
1238 \begin_layout Itemize
1239 No new LaTeX classes can be supported in a stable version, and stable versions
1240 have a typical lifetime of 2–3 years.
1243 \begin_layout Itemize
1244 We have the same situation already with custom layout files: If a document
1245 using a custom layout file is moved between machines or people, then the
1246 layout file needs to be exchanged as well.
1247 If that is not done, then we have a fallback implemented so that such documents
1248 can still be edited, but not exported, and the user gets a warning.
1252 \begin_layout Itemize
1253 The lyx2lyx script cannot do anything useful in such a case.
1257 \begin_layout Standard
1258 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1260 then, you should do the following:
1263 \begin_layout Enumerate
1264 Put your new layout file in
1265 \begin_inset Flex Code
1268 \begin_layout Plain Layout
1275 \begin_inset Flex Code
1278 \begin_layout Plain Layout
1279 git add lib/layouts/newlayout.layout
1284 ) so that it will be committed.
1287 \begin_layout Enumerate
1289 \begin_inset Flex Code
1292 \begin_layout Plain Layout
1298 , so that the new layout actually gets installed.
1301 \begin_layout Enumerate
1303 \begin_inset Flex Code
1306 \begin_layout Plain Layout
1307 lib/doc/LaTeXConfig.lyx
1312 containing in particular a line like
1320 \begin_layout Standard
1321 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1322 \begin_inset Flex Code
1325 \begin_layout Plain Layout
1326 info-insert textclass <name>
1332 This inset will automatically display a boxed
1333 \begin_inset Quotes eld
1337 \begin_inset Quotes erd
1341 \begin_inset Quotes eld
1345 \begin_inset Quotes erd
1348 depending on the availability of the package.
1352 \begin_layout Enumerate
1353 A template or example is strongly encouraged (but not necessarily required).
1354 It is also possible to provide both.
1356 \begin_inset Flex Code
1359 \begin_layout Plain Layout
1366 \begin_inset Flex Code
1369 \begin_layout Plain Layout
1378 \begin_layout Enumerate
1379 Reconfigure \SpecialChar LyX
1383 \begin_layout Enumerate
1384 Ensure the autotests for the new layout pass (see
1385 \begin_inset CommandInset ref
1387 reference "par:when-to-run-an-export-test"
1394 \begin_layout Subsection
1398 \begin_layout Standard
1399 Adding a new module is very similar to adding a new layout.
1400 Therefore, the previous section applies to new modules as well, with two
1404 \begin_layout Enumerate
1405 You only need to add an entry to
1406 \begin_inset Flex Code
1409 \begin_layout Plain Layout
1410 lib/doc/LaTeXConfig.lyx
1415 if the module requires a LaTeX package.
1416 In that case, the command for entering the InsetInfo is:
1417 \begin_inset Flex Code
1420 \begin_layout Plain Layout
1421 \paragraph_spacing single
1422 info-insert package <name>
1430 \begin_layout Enumerate
1431 Modules do not need a template, only an example, which is strongly encouraged
1432 but not necessarily required.
1435 \begin_layout Subsection
1436 Layouts for document classes with incompatible versions
1439 \begin_layout Standard
1440 \begin_inset Note Greyedout
1443 \begin_layout Description
1444 Note: This section is currently only a proposal under discussion.
1445 Please correct/amend as suited.
1446 Remove this note once a consensus is found.
1449 \begin_layout Plain Layout
1451 \begin_inset Quotes eld
1454 Proposal for a guide on updating layouts
1455 \begin_inset Quotes erd
1458 for details and background
1461 \begin_layout Plain Layout
1462 http://permalink.gmane.org/gmane.editors.lyx.devel/161126
1470 \begin_layout Standard
1471 Every now and then, there are changes to LaTeX document classes that break
1472 backwards compatibility.
1476 \begin_layout Plain Layout
1477 Uwe has suggested we implement automatic detection of changes in class files.
1478 This could be done by running a script every month that checks if a document
1479 class was changed at CTAN and at the homepages of the scientific journals.
1480 If it reports a change, we can check if our template and layout file are
1481 still usable with the changed document class.
1482 (This is different from the autotests insofar, as this would also catch
1483 changes that do not result in compilation errors.)
1488 Reasons can be a new name for the
1489 \begin_inset Flex Code
1492 \begin_layout Plain Layout
1498 file, removed \SpecialChar LaTeX
1500 How should this best be handled in \SpecialChar LyX
1504 \begin_layout Standard
1505 The idea is to support the new version with a new \SpecialChar LyX
1509 \begin_layout Itemize
1510 Existing documents can still be opened in \SpecialChar LyX
1511 and will continue to work on
1512 systems where the old version is still installed.
1516 \begin_layout Itemize
1517 With differently named
1518 \begin_inset Flex Code
1521 \begin_layout Plain Layout
1527 files, \SpecialChar LyX
1528 can check for the availability of the particular version and reflect
1530 Different document class versions with the same file name are currently
1531 (2.2.x) not detected by the configuration script.
1532 This is planned for 2.3.
1536 \begin_layout Plain Layout
1537 https://www.mail-archive.com/lyx-devel@lists.lyx.org/msg192467.html
1540 \begin_layout Plain Layout
1541 However, what we really need is version detection for the configuration,
1542 so that the user can be warned if the required class file has the wrong
1544 (If the class file keeps the name over the version change, only one of
1545 the two layout files generates compilable documents.)
1548 \begin_layout Plain Layout
1549 This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.devel/143
1558 \begin_layout Itemize
1559 The new layout can be added both to the master and the stable branches,
1560 in accord with the policy discussed in
1561 \begin_inset CommandInset ref
1562 LatexCommand formatted
1563 reference "subsec:New-layouts"
1568 No lyx2lyx conversion is then required when a new major version is released.
1571 \begin_layout Standard
1572 The user can move an existing document to the new version simply by selecting
1573 a new document class.
1574 This step is well supported by \SpecialChar LyX
1575 , with established methods for handling
1576 unsupported styles and other changes.
1577 This way, no lyx2lyx code is required.
1580 \begin_layout Standard
1581 The steps to support a new version of an existing document class are thus:
1584 \begin_layout Itemize
1585 Create a new layout file including the upstream version in the name (avoid
1586 special characters like spaces and dots), e.g.
1588 \begin_inset Flex Code
1591 \begin_layout Plain Layout
1592 acmsiggraph-v0-92.layout
1600 \begin_layout Itemize
1601 Include the name of the
1602 \begin_inset Flex Code
1605 \begin_layout Plain Layout
1611 file as an optional argument in the
1612 \begin_inset Flex Code
1615 \begin_layout Plain Layout
1623 line and include the version number in the GUI name:
1624 \begin_inset Newline newline
1628 \begin_inset Flex Code
1631 \begin_layout Plain Layout
1634 DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v.
1635 \begin_inset space ~
1646 \begin_layout Itemize
1647 Update the GUI name in the old layout file (whose name should not be changed),
1649 \begin_inset Newline newline
1653 \begin_inset Flex Code
1656 \begin_layout Plain Layout
1659 DeclareLaTeXClass{ACM SIGGRAPH (<= v.
1660 \begin_inset space ~
1671 \begin_layout Itemize
1672 To avoid duplicate definitions, the new layout can
1673 \begin_inset Flex Code
1676 \begin_layout Plain Layout
1682 the old layout file and add\SpecialChar breakableslash
1683 remove\SpecialChar breakableslash
1684 obsolete\SpecialChar breakableslash
1685 modify settings and styles (similar
1687 \begin_inset Flex Code
1690 \begin_layout Plain Layout
1700 \begin_layout Standard
1701 It may be tempting to let the new layout be the
1702 \begin_inset Quotes eld
1706 \begin_inset Quotes erd
1709 and have the old layout import it.
1710 However, this should not be done because any changes to the new layout
1711 would need undo steps in the importing old layout.
1715 \begin_layout Itemize
1716 If the new LaTeX document class obsoletes the old one, update the example
1717 and template files to use the new layout.
1718 Add a note about the changes (preferably with a pointer to the documentation
1723 \begin_layout Standard
1724 This way, new documents based on the template or example will use the up-to-date
1725 document class version.
1729 \begin_layout Standard
1730 \begin_inset Newpage newpage
1736 \begin_layout Section
1740 \begin_layout Standard
1741 Automated tests are an important tool to detect bugs and regressions in
1742 software development.
1743 Some projects like gcc even require each bug fix to be accompanied by a
1744 test case for the automatic test suite, that would detect this bug.
1745 Testing interactive features automatically is of course very hard, but
1746 core functionality like document import and export can be tested quite
1747 easily, and some tests of this kind exist.
1750 \begin_layout Subsection
1754 \begin_layout Standard
1755 There are attempts to set up a suite of unit tests for LyX.
1758 \begin_layout Standard
1759 TODO: describe what is done and what is still to do.
1762 \begin_layout Subsection
1766 \begin_layout Standard
1767 The tex2lyx tests are located in the
1768 \begin_inset Flex Code
1771 \begin_layout Plain Layout
1777 subfolder of the \SpecialChar LyX
1778 source code distribution.
1779 The actual testing is performed by the simple python script
1780 \begin_inset Flex Code
1783 \begin_layout Plain Layout
1784 src/tex2lyx/test/runtests.py
1790 Each test consists of two files:
1791 \begin_inset Flex Code
1794 \begin_layout Plain Layout
1800 contains the \SpecialChar LaTeX
1801 code that should be tested.
1803 \begin_inset Flex Code
1806 \begin_layout Plain Layout
1812 contains the expected output of tex2lyx.
1813 When a test is run, the actual produced output is compared with the stored
1815 The test passes if both are identical.
1816 The test machinery is also able to generate a file
1817 \begin_inset Flex Code
1820 \begin_layout Plain Layout
1826 by exporting the produced .lyx file with \SpecialChar LyX
1828 This may be useful for roundtrip comparisons.
1831 \begin_layout Subsubsection
1835 \begin_layout Standard
1836 The tex2lyx tests can be run in several ways.
1838 \begin_inset Flex Code
1841 \begin_layout Plain Layout
1847 subfolder of the build directory, the commands
1848 \begin_inset Flex Code
1851 \begin_layout Plain Layout
1857 (cmake, all platforms),
1858 \begin_inset Flex Code
1861 \begin_layout Plain Layout
1867 (cmake, when using a make based build system and not MSVC) or
1868 \begin_inset Flex Code
1871 \begin_layout Plain Layout
1877 (autotools) will run the tex2lyx tests.
1878 Alternatively, in the root of the build directory, the command
1879 \begin_inset Flex Code
1882 \begin_layout Plain Layout
1888 runs all tests whose names match the regex
1889 \begin_inset Quotes eld
1893 \begin_inset Quotes erd
1897 Another way to run the tex2lyx tests in the root build directory is to
1898 instead use the command
1899 \begin_inset Flex Code
1902 \begin_layout Plain Layout
1903 ctest -L '(cmplyx|roundtrip)'
1908 , which runs all tests categorized with the label
1909 \begin_inset Quotes eld
1913 \begin_inset Quotes erd
1917 \begin_inset Quotes eld
1921 \begin_inset Quotes erd
1925 If a test fails, the differences between the expected and actual results
1926 are output in unified diff format.
1929 \begin_layout Subsubsection
1930 Updating test references
1931 \begin_inset CommandInset label
1933 name "sec:Updating-test-references"
1940 \begin_layout Standard
1941 In some cases a changed tex2lyx output is not a test failure, but wanted,
1943 \begin_inset space \thinspace{}
1947 \begin_inset space \space{}
1950 if a tex2lyx bug was fixed, or a new feature was added.
1951 In these cases the stored references need to be updated.
1952 To do so if using autotools, call
1953 \begin_inset Flex Code
1956 \begin_layout Plain Layout
1963 \begin_inset Flex Code
1966 \begin_layout Plain Layout
1972 subdirectory of the build directory.
1973 If instead using CMake, call
1974 \begin_inset Flex Code
1977 \begin_layout Plain Layout
1978 make updatetex2lyxtests
1983 in the build directory or in the
1984 \begin_inset Flex Code
1987 \begin_layout Plain Layout
1993 subdirectory of the build directory.
1997 \begin_layout Plain Layout
1998 Note that this is a case where a make target in the build directory can
1999 affect the source directory, which might not be advisable.
2004 On Windows do the following:
2007 \begin_layout Itemize
2008 Assure that the path to the python.exe is in your system PATH variable.
2011 \begin_layout Itemize
2012 Double-click on the file
2013 \begin_inset Flex Code
2016 \begin_layout Plain Layout
2017 updatetex2lyxtests.vcxproj
2022 in the build directory or in the
2023 \begin_inset Flex Code
2026 \begin_layout Plain Layout
2032 subdirectory of your build directory.
2035 \begin_layout Itemize
2036 In the appearing MSVC program assure that you build the
2040 version, then right-click on the project
2044 in the project explorer and choose then
2047 \begin_inset space ~
2050 Only\SpecialChar menuseparator
2052 \begin_inset space ~
2060 \begin_layout Standard
2061 For convenience, these commands also produce re-exported roundtrip .lyx.tex
2063 Please examine the changed output carefully before committing the changed
2064 files to the repository: Since the test machinery does not do a roundtrip
2066 \begin_inset Formula $\Rightarrow$
2070 \begin_inset Formula $\Rightarrow$
2073 .tex, and does not compare the produced dvi or pdf output, it assumes that
2074 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
2076 There is only one chance to detect wrong output: before committing a new
2078 Once it is committed, it is quite difficult to verify whether it is correct.
2081 \begin_layout Standard
2086 update the test references by opening them with \SpecialChar LyX
2087 or directly running lyx2lyx
2089 This would not work, since lyx2lyx and \SpecialChar LyX
2090 produce slightly different files
2091 regarding insignificant whitespace and line breaks.
2094 \begin_layout Subsubsection
2098 \begin_layout Standard
2099 In many cases tests for new features may be added to one of the existing
2100 test files, but sometimes this is not possible or not wanted.
2101 Then a new test file needs to be added:
2104 \begin_layout Enumerate
2106 \begin_inset Flex Code
2109 \begin_layout Plain Layout
2110 src/tex2lyx/test/<test name>.tex
2115 and run tex2lyx in roundtrip mode to produce the file
2116 \begin_inset Flex Code
2119 \begin_layout Plain Layout
2120 src/tex2lyx/test/<test name>.lyx.lyx
2126 This file will be the new reference.
2129 \begin_layout Enumerate
2130 Once you confirmed that the tex2lyx output is correct, add the new files
2131 to the corresponding lists in
2132 \begin_inset Flex Code
2135 \begin_layout Plain Layout
2136 src/tex2lyx/test/runtests.py
2142 \begin_inset Flex Code
2145 \begin_layout Plain Layout
2146 src/tex2lyx/Makefile.am
2152 \begin_inset Flex Code
2155 \begin_layout Plain Layout
2156 src/tex2lyx/test/CMakeLists.txt
2164 \begin_layout Enumerate
2165 Commit the changes to the repository, or send a patch to the development
2166 list and ask for committing if you do not have commit rights.
2169 \begin_layout Subsection
2170 ctest automatic tests
2173 \begin_layout Standard
2174 Some tests are located in the
2175 \begin_inset Flex Code
2178 \begin_layout Plain Layout
2179 development/autotests/
2184 subfolder of the \SpecialChar LyX
2185 source code distribution.
2190 \begin_layout Plain Layout
2191 The README document in this folder only describes the
2192 \begin_inset Quotes eld
2196 \begin_inset Quotes erd
2199 subset of autotests!
2207 \begin_layout Standard
2208 These tests can be run by the commands
2209 \begin_inset Flex Code
2212 \begin_layout Plain Layout
2222 (all platforms) or (when using a make based build system and not MSVC)
2224 \begin_inset Flex Code
2227 \begin_layout Plain Layout
2234 \begin_inset Flex Code
2237 \begin_layout Plain Layout
2248 The test logs are written to the
2249 \begin_inset Flex Code
2252 \begin_layout Plain Layout
2266 \begin_layout Subsubsection
2270 \begin_layout Standard
2271 The export tests are integration tests.
2272 They take longer to run and are more likely to break than the tex2lyx tests.
2273 Nevertheless, they have caught many regressions and without a better alternativ
2274 e it is important to keep them up-to-date and understand how they work.
2277 \begin_layout Standard
2279 \begin_inset Quotes eld
2283 \begin_inset Quotes erd
2286 documentation, template, and example documents.
2287 In addition, there are a number of dedicated sample documents in the
2288 \begin_inset Flex Code
2291 \begin_layout Plain Layout
2297 subfolder of the \SpecialChar LyX
2298 source code distribution.
2299 All samples are (after copying and eventual processing by scripts) exported
2300 to various output formats via the
2301 \begin_inset Flex Code
2304 \begin_layout Plain Layout
2310 command line option.
2311 The tests checks for errors reported by LyX.
2312 (However, error-free export is no guarantee for an error-free output document.)
2315 \begin_layout Paragraph
2316 \begin_inset CommandInset label
2318 name "par:when-to-run-an-export-test"
2322 Expectations of LyX developers
2325 \begin_layout Standard
2326 Because the export tests are integration tests and take a long time to run,
2327 LyX developers are rarely expected to run all of the tests.
2328 Here are some good practices to follow by developers:
2331 \begin_layout Itemize
2332 When making a non-trivial change to a .layout file, run the export and layout
2333 tests corresponding with that .layout file.
2336 \begin_layout Itemize
2337 When making non-trivial changes to a .lyx file, run the export tests correspondin
2338 g to that .lyx file.
2343 \begin_layout Plain Layout
2344 This rule is due to revision.
2348 \begin_layout Plain Layout
2349 There is an objection from the documentation maintainer that working on
2350 the documentation must not be complicated by having to consider non-standard
2354 \begin_layout Itemize
2355 successful compiling/testing an edited documentation file with pdflatex
2356 suffices to ensure it can be commited, not tests with other exports are
2360 \begin_layout Plain Layout
2361 If sudden failures with other exports due to “half-tested” documentation
2362 updates are a problem for the test maintainer, the test suite should use
2366 \begin_layout Itemize
2367 copied to a cache dir (autotests/samples/doc/, say) but not changed,
2370 \begin_layout Itemize
2371 updated regularely (but on a time chosen by the test suite maintainer) from
2372 the originals in lib/doc/
2375 \begin_layout Plain Layout
2379 \begin_layout Itemize
2380 no test will fail due to ongoing work on documentation,
2383 \begin_layout Itemize
2384 the documentation is still tested in full (with some delay),
2387 \begin_layout Itemize
2388 failures with non-default export can be examined and handled accordingly
2389 in one run with the cache update,
2392 \begin_layout Itemize
2393 “interesting failures” (like the nested-language+polyglossia problem in
2394 es/Customization can be separated and moved into dedicated test samples.
2402 \begin_layout Itemize
2403 When making non-trivial changes to LyX's \SpecialChar LaTeX
2405 touching the encoding code or package handling code that you expect will
2406 change the exported \SpecialChar LaTeX
2411 \begin_layout Standard
2412 \paragraph_spacing single
2413 Consider running all of the export tests before and after your change.
2414 If there are differences, please reconcile these (i.e.
2415 fix the bug or fix the tests)
2420 Ask for help if you're not sure what to.
2423 \begin_layout Standard
2424 If you do not want to run the tests,
2427 \begin_layout Itemize
2428 post the patch on the list and others will run the tests and eventually
2432 \begin_layout Itemize
2433 commit, but be prepared to fix eventually arising problems or to revert
2434 the commit if there is no easy fix.
2438 \begin_layout Itemize
2439 Understand how to interpret test failures.
2440 If your commit is found to have broken a test, you should be able to interpret
2441 the test results when made aware of them.
2443 \begin_inset CommandInset ref
2445 reference "subsec:Interpreting-export-tests"
2452 \begin_layout Paragraph
2453 \begin_inset CommandInset label
2455 name "par:export-test-output-formats"
2462 \begin_layout Standard
2463 The following output formats are currently tested for each sample document
2465 \begin_inset CommandInset ref
2467 reference "par:Export-test-filtering"
2474 \begin_layout Labeling
2475 \labelwidthstring 00.00.0000
2480 \begin_layout Labeling
2481 \labelwidthstring 00.00.0000
2482 lyx16 LyX 1.6 file format (lyx2lyx)
2485 \begin_layout Labeling
2486 \labelwidthstring 00.00.0000
2487 lyx21 LyX 2.1 file format (lyx2lyx)
2490 \begin_layout Labeling
2491 \labelwidthstring 00.00.0000
2492 xhtml LyXHTML (native LyX HTML export)
2496 \begin_layout Labeling
2497 \labelwidthstring 00.00.0000
2499 \begin_inset space ~
2503 \begin_inset space ~
2510 \begin_layout Labeling
2511 \labelwidthstring pdf5msystemFM
2512 dvi DVI (8-bit latex)
2515 \begin_layout Labeling
2516 \labelwidthstring pdf5msystemFM
2517 dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
2520 \begin_layout Labeling
2521 \labelwidthstring pdf5msystemFM
2522 dvi3_systemF DVI (LuaTeX with Unicode fonts)
2525 \begin_layout Labeling
2526 \labelwidthstring pdf5msystemFM
2530 \begin_layout Labeling
2531 \labelwidthstring pdf5msystemFM
2532 pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
2535 \begin_layout Labeling
2536 \labelwidthstring pdf5msystemFM
2537 pdf4_systemF PDF (XeTeX with Unicode fonts)
2540 \begin_layout Labeling
2541 \labelwidthstring pdf5msystemFM
2542 pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
2545 \begin_layout Labeling
2546 \labelwidthstring pdf5msystemFM
2547 pdf5_systemF PDF (LuaTeX with Unicode fonts)
2551 \begin_layout Labeling
2552 \labelwidthstring 00.00.0000
2554 \begin_inset space ~
2558 \begin_inset space ~
2562 \begin_inset space ~
2566 \begin_inset space ~
2573 \begin_layout Labeling
2574 \labelwidthstring pdf5msystemFM
2575 pdf DVI -> PS (dvips) -> PDF (ps2pdf)
2578 \begin_layout Labeling
2579 \labelwidthstring pdf5msystemFM
2580 pdf3 DVI -> PDF (dvipdfm)
2584 \begin_layout Labeling
2585 \labelwidthstring 00.00.0000
2587 \begin_inset space ~
2590 tested: (or only if set as default output format in the document source)
2594 \begin_layout Labeling
2595 \labelwidthstring pdf5msystemFM
2599 \begin_layout Labeling
2600 \labelwidthstring pdf5msystemFM
2601 luatex LaTeX (LuaTeX)
2604 \begin_layout Labeling
2605 \labelwidthstring pdf5msystemFM
2606 dviluatex LaTeX (dviluatex)
2609 \begin_layout Labeling
2610 \labelwidthstring pdf5msystemFM
2611 pdflatex LaTeX (pdflatex)
2614 \begin_layout Labeling
2615 \labelwidthstring pdf5msystemFM
2616 platex LaTeX (pLaTeX)
2619 \begin_layout Labeling
2620 \labelwidthstring pdf5msystemFM
2624 \begin_layout Labeling
2625 \labelwidthstring pdf5msystemFM
2626 eps3 EPS (encapsulated Postscript) (cropped)
2629 \begin_layout Labeling
2630 \labelwidthstring pdf5msystemFM
2631 ps DVI -> Postscript (dvips)
2634 \begin_layout Labeling
2635 \labelwidthstring pdf5msystemFM
2639 \begin_layout Labeling
2640 \labelwidthstring pdf5msystemFM
2641 text (nor text2, ..., text4)
2644 \begin_layout Labeling
2645 \labelwidthstring pdf5msystemFM
2649 \begin_layout Labeling
2650 \labelwidthstring pdf5msystemFM
2654 \begin_layout Labeling
2655 \labelwidthstring pdf5msystemFM
2659 \begin_layout Labeling
2660 \labelwidthstring pdf5msystemFM
2665 \begin_layout Paragraph
2666 \begin_inset CommandInset label
2668 name "par:Configuring-ctests"
2672 Configuring the tests
2675 \begin_layout Standard
2676 To enable the export autotests, add the
2677 \begin_inset Flex Code
2680 \begin_layout Plain Layout
2681 -DLYX_ENABLE_EXPORT_TESTS=ON
2690 \begin_layout Standard
2691 \begin_inset Flex Code
2694 \begin_layout Plain Layout
2695 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
2703 \begin_layout Standard
2705 This flag will increase the time for the cmake command by several seconds,
2706 mainly because of the process of inverting tests (see Section
2707 \begin_inset CommandInset ref
2709 reference "subsec:Interpreting-export-tests"
2716 \begin_layout Paragraph
2717 \begin_inset CommandInset label
2719 name "par:ctest-options"
2726 \begin_layout Standard
2727 To run all tests, in the build directory simply run the command
2728 \begin_inset Flex Code
2731 \begin_layout Plain Layout
2738 A full, up-to-date TeXLive installation is recommended to run the tests.
2739 Otherwise, some tests will fail.
2740 Tests with additional requirements are labeled
2741 \begin_inset Quotes eld
2744 unreliable:nonstandard
2745 \begin_inset Quotes erd
2752 \begin_layout Standard
2753 To run only some of the tests, use command line options (see examples below):
2756 \begin_layout Labeling
2757 \labelwidthstring -R
2758 \begin_inset Flex Code
2761 \begin_layout Plain Layout
2767 Run only the tests whose names match the given regular expression.
2770 \begin_layout Labeling
2771 \labelwidthstring -R
2772 \begin_inset Flex Code
2775 \begin_layout Plain Layout
2781 Run only the tests whose labels match the given regular expression.
2782 A test may have more that one label.
2786 \begin_layout Labeling
2787 \labelwidthstring -R
2788 \begin_inset Flex Code
2791 \begin_layout Plain Layout
2797 Exclude the tests whose names match the given regular expression.
2800 \begin_layout Labeling
2801 \labelwidthstring -R
2802 \begin_inset Flex Code
2805 \begin_layout Plain Layout
2811 Exclude the tests whose labels match the given regular expression.
2812 Cannot be combined with
2813 \begin_inset Flex Code
2816 \begin_layout Plain Layout
2825 \begin_layout Standard
2826 The following options help to find good selection patterns:
2829 \begin_layout Labeling
2830 \labelwidthstring -R
2831 \begin_inset Flex Code
2834 \begin_layout Plain Layout
2840 List the tests that would be run but not actually run them.
2845 \begin_layout Standard
2846 Useful in conjunction with the -R, -L, -E and -LE options, e.g., if you want
2847 to know how many tests there are or whether your
2848 \begin_inset Flex Code
2851 \begin_layout Plain Layout
2857 regular expression did what you expected.
2861 \begin_layout Labeling
2862 \labelwidthstring -R
2863 \begin_inset Flex Code
2866 \begin_layout Plain Layout
2867 \SpecialChar nobreakdash
2868 \SpecialChar nobreakdash
2874 print the list of all labels associated with the test set.
2875 Can also be combined with -R, -L, -E, ...
2879 \begin_layout Standard
2880 Other useful options are:
2883 \begin_layout Labeling
2884 \labelwidthstring -R
2885 \begin_inset Flex Code
2888 \begin_layout Plain Layout
2894 Run the tests in parallel using the given number of jobs.
2898 \begin_layout Standard
2899 We are still working on getting the tests to run in parallel.
2900 However, when running the tests in parallel, sometimes tests fail that
2901 pass when run sequentially.
2902 A reasonable approach is to first run the tests in parallel and then run
2903 the failed tests sequentially.
2906 \begin_layout Standard
2907 For example, to run 8 jobs at a time:
2910 \begin_layout Standard
2911 \begin_inset Flex Code
2914 \begin_layout Plain Layout
2923 \begin_layout Standard
2924 \begin_inset Flex Code
2927 \begin_layout Plain Layout
2928 ctest \SpecialChar nobreakdash
2929 \SpecialChar nobreakdash
2938 \begin_layout Standard
2939 When specifying a subset of the tests (e.g.
2941 \begin_inset Flex Code
2944 \begin_layout Plain Layout
2945 \SpecialChar nobreakdash
2951 ), the same subset must be specified when using the
2952 \begin_inset Flex Code
2955 \begin_layout Plain Layout
2956 \SpecialChar nobreakdash
2957 \SpecialChar nobreakdash
2963 option because it is the test numbers that are used to index which tests
2964 failed on the previous run.
2967 \begin_layout Standard
2969 Note that some tests cannot be run in parallel.
2970 These tests are marked in the code with the
2971 \begin_inset Flex Code
2974 \begin_layout Plain Layout
2985 \begin_layout Labeling
2986 \labelwidthstring -R
2987 \begin_inset Flex Code
2990 \begin_layout Plain Layout
2991 \SpecialChar nobreakdash
2992 \SpecialChar nobreakdash
2998 Set a global timeout on all tests that do not already have a timeout set
3003 \begin_layout Standard
3004 There have been bugs in LyX and in \SpecialChar LaTeX
3005 which cause compilation to hang, and
3006 without a timeout a test might never stop (in one case there was even a
3008 If a test times out, the
3009 \begin_inset Flex Code
3012 \begin_layout Plain Layout
3018 command exits with error, but you can distinguish between a timed out test
3019 and a failed test in the output reported at the end of the
3020 \begin_inset Flex Code
3023 \begin_layout Plain Layout
3033 \begin_layout Standard
3035 \begin_inset Flex Code
3038 \begin_layout Plain Layout
3044 ) the full list of command line options.
3047 \begin_layout Paragraph
3051 \begin_layout Itemize
3052 run only the export tests:
3053 \begin_inset Flex Code
3056 \begin_layout Plain Layout
3065 \begin_layout Itemize
3067 \begin_inset Flex Code
3070 \begin_layout Plain Layout
3071 ctest -L "inverted|suspended"
3079 \begin_layout Itemize
3080 list all export tests which match any of the labelling patterns:
3081 \begin_inset Flex Code
3084 \begin_layout Plain Layout
3095 \begin_layout Itemize
3096 exclude rarely used output formats and post-processing tests
3097 \begin_inset Flex Code
3100 \begin_layout Plain Layout
3101 ctest -L export -E "_(texF|dvi3|pdf3?)"
3109 \begin_layout Paragraph
3110 \begin_inset CommandInset label
3112 name "subsec:Interpreting-export-tests"
3116 Interpreting the export test results
3119 \begin_layout Standard
3120 A test can fail for several reasons, not all of them bad.
3123 \begin_layout Enumerate
3124 A new or edited sample document may be incompatible with some output formats.
3127 \begin_layout Enumerate
3128 A dependency is not met (e.g.
3129 the \SpecialChar LaTeX
3131 One hint that this is the case is that the corresponding
3132 \begin_inset Flex Code
3135 \begin_layout Plain Layout
3141 test will likely also fail.
3144 \begin_layout Enumerate
3145 An inverted test fails to fail (i.e.
3146 export that previously failed now works).
3149 \begin_layout Enumerate
3150 An external dependency was updated (e.g.
3155 \begin_layout Enumerate
3156 A recent code change introduced a bug.
3159 \begin_layout Enumerate
3160 \begin_inset CommandInset label
3166 A change in a document exposed a previously unknown bug or an incompatibility
3167 with an export format (e.g.
3168 Lua\SpecialChar LaTeX
3172 \begin_layout Standard
3173 Because the .lyx files are exported in several formats, it is not surprising
3174 that many of the exports fail.
3175 This expectation of failure is addressed by
3176 \begin_inset Quotes eld
3180 \begin_inset Quotes erd
3183 the tests, that is, by marking the test as
3184 \begin_inset Quotes eld
3188 \begin_inset Quotes erd
3191 if the export exits with error and as
3192 \begin_inset Quotes eld
3196 \begin_inset Quotes erd
3199 if the export succeeds
3204 It follows that these expected failures will not show up as failed tests
3205 in the test results and thus will not pollute the
3206 \begin_inset Quotes eld
3210 \begin_inset Quotes erd
3214 If the export actually succeeds, then the test will fail.
3215 The purpose of this failure is to get your attention—something has changed,
3216 possibly for the better.
3219 \begin_layout Standard
3220 We try to document why a test is inverted or ignored.
3221 See the comment (prefixed with
3222 \begin_inset Flex Code
3225 \begin_layout Plain Layout
3231 ) above the block in which the test is listed as inverted or ignored in
3233 \begin_inset Flex Code
3236 \begin_layout Plain Layout
3237 development/autotests/invertedTests
3243 \begin_inset Flex Code
3246 \begin_layout Plain Layout
3247 development/autotests/unreliableTests
3253 \begin_inset Flex Code
3256 \begin_layout Plain Layout
3257 development/autotests/ignoredTests
3266 \begin_layout Standard
3267 A good question is why do we enable the tests for non-default formats? The
3268 answer is that if a non-default route is broken it is often because a bug
3269 was introduced in LyX and not because a document-specific change was made
3270 that is not supported by the route.
3271 In other words, there is a high signal/noise ratio in the export tests
3272 for some non-default formats.
3276 \begin_layout Standard
3277 When a test or several tests fail, consider checking the files in the
3278 \begin_inset Flex Code
3281 \begin_layout Plain Layout
3287 subdirectory of your build directory.
3288 In this subdirectory are three files: the file
3289 \begin_inset Flex Code
3292 \begin_layout Plain Layout
3298 simply lists the tests that failed on your last
3299 \begin_inset Flex Code
3302 \begin_layout Plain Layout
3309 \begin_inset Flex Code
3312 \begin_layout Plain Layout
3318 file contains the output from the tests (and often has details explaining
3319 why a test failed); and the
3320 \begin_inset Flex Code
3323 \begin_layout Plain Layout
3329 file lists the times that it took to run the tests.
3332 \begin_layout Paragraph
3333 What action should you take if a test fails?
3336 \begin_layout Standard
3337 \paragraph_spacing single
3338 It is always good to check manually why something fails and if it passes
3339 if the PDF output is good.
3342 \begin_layout Itemize
3343 Generally, if a change breaks compilation for the target format (for the
3344 manuals pdf2) without solving some important other issue,
3346 fix or revert the commit
3348 that led to failure.
3351 \begin_layout Itemize
3352 If it is not possible to (immediately) fix the failure but there are reasons
3353 not to revert the commit (e.g.
3354 it fixes another more important issue),
3358 the failing test case (see
3359 \begin_inset CommandInset ref
3361 reference "par:Inverted-tests"
3368 \begin_layout Itemize
3373 test case fails because the export now works,
3377 the test by removing the pattern from the
3378 \begin_inset Quotes eld
3382 \begin_inset Quotes erd
3386 \begin_inset CommandInset ref
3388 reference "par:Inverted-tests"
3395 \begin_layout Itemize
3396 If the export did not fail previously but led to wrong output (PDF, say),
3400 \begin_layout Plain Layout
3401 Non-failing test with wrong output should be labeled as
3402 \begin_inset Quotes eld
3405 unreliable:wrong_output
3406 \begin_inset Quotes erd
3410 \begin_inset CommandInset ref
3412 reference "par:Unreliable-tests"
3421 it is in fact an improvement when the test now fails.
3426 the failing test case (see
3427 \begin_inset CommandInset ref
3429 reference "par:Inverted-tests"
3436 \begin_layout Itemize
3437 In case of tests failing due to missing requirements (tests labeled
3438 \begin_inset Quotes eld
3441 unreliable:nonstandard
3442 \begin_inset Quotes erd
3445 or testing on a system with only a subset of TeXLive installed), ignore
3446 the failure, ask for someone else to run the test, or install the missing
3447 resources and try again.
3450 \begin_layout Itemize
3451 Check the log file Testing/Temporary/LastTest.log.
3452 In case of latex-errors rerun the failing test with environment variable
3453 'LYX_DEBUG_LATEX' set to '1'.
3454 This will include latex messages in LastTest.log, so it should be easier
3455 to interpret the fail-reason.
3458 \begin_layout Paragraph
3459 \begin_inset CommandInset label
3461 name "par:Inverted-tests"
3468 \begin_layout Standard
3469 Test cases whose name matches a pattern in the file
3470 \begin_inset Flex Code
3473 \begin_layout Plain Layout
3474 development/autotests/invertedTests
3484 They get also the test property
3485 \begin_inset Flex Code
3488 \begin_layout Plain Layout
3495 they are reported as failing if the export works without error
3496 \begin_inset Flex URL
3499 \begin_layout Plain Layout
3501 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3509 \begin_layout Standard
3510 Add failing cases to this file, if they cannot be solved
3511 \begin_inset Quotes eld
3515 \begin_inset Quotes erd
3518 but it is expected that the export will work in a foreseeable future, e.g.
3519 low priority issues like failures to export to a non-target format (for
3520 the manuals everything except pdf2).
3523 \begin_layout Standard
3524 The following sublabels are currently present in
3525 \begin_inset Flex Code
3528 \begin_layout Plain Layout
3537 \begin_layout Description
3538 todo test failures that require attention:
3542 \begin_layout Itemize
3543 minor issues to explore and properly sort later,
3546 \begin_layout Itemize
3550 \begin_layout Itemize
3551 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3555 \begin_layout Description
3556 lyxbugs LyX bugs with a Trac number.
3559 \begin_layout Description
3560 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3564 \begin_layout Standard
3565 "Wontfix" if demonstrating correct use and OK in the default output format.
3569 \begin_layout Description
3570 texissues Export fails due to LaTeX limitations like non-ASCII characters
3571 in verbatim or listings, incompatible packages, ...
3575 \begin_layout Standard
3576 "Wontfix" if documents demonstrate correct use in the default output format:
3579 \begin_layout Itemize
3580 If the source can be made more robust without becoming "hackish", fix the
3584 \begin_layout Itemize
3585 if LyX could be enhanced to care for a permanent TeX limitation, file a
3586 ticket at trac and add a pattern under lyxbugs,
3589 \begin_layout Itemize
3590 otherwise, add a pattern here.
3594 \begin_layout Description
3595 attic Documents in the attic (kept for reference and format conversion test).
3597 \begin_inset Quotes eld
3601 \begin_inset Quotes erd
3607 \begin_layout Subparagraph
3611 \begin_layout Standard
3612 Test cases whose name additionally matches a pattern in the file
3613 \begin_inset Flex Code
3616 \begin_layout Plain Layout
3617 development/autotests/suspendedTests
3635 This means they are not executed using
3636 \begin_inset Flex Code
3639 \begin_layout Plain Layout
3646 \begin_inset Flex Code
3649 \begin_layout Plain Layout
3656 However, they also get the test property
3657 \begin_inset Flex Code
3660 \begin_layout Plain Layout
3667 they are reported as failing if the export works without error.
3668 From time to time they still have to be checked using
3669 \begin_inset Flex Code
3672 \begin_layout Plain Layout
3681 \begin_layout Standard
3682 These tests are suspended, because the export fails for known reasons which
3683 cannot ATM be resolved.
3684 But it is expected the reason might disappear in the future.
3685 Be it new TL or better handling in \SpecialChar LyX
3689 \begin_layout Standard
3690 For ctest commands without the
3691 \begin_inset Flex Code
3694 \begin_layout Plain Layout
3700 parameter nothing changes.
3701 Suspended or not, tests will be executed depending only on the selecting
3702 regular expression given to the ctest command (see
3703 \begin_inset CommandInset ref
3705 reference "par:ctest-options"
3712 \begin_layout Paragraph
3713 \begin_inset CommandInset label
3715 name "par:Unreliable-tests"
3722 \begin_layout Standard
3723 Test cases whose name matches a pattern in the file
3724 \begin_inset Flex Code
3727 \begin_layout Plain Layout
3728 development/autotests/unreliableTests
3740 \begin_layout Standard
3741 These tests are not executed using
3742 \begin_inset Flex Code
3745 \begin_layout Plain Layout
3752 \begin_inset Flex Code
3755 \begin_layout Plain Layout
3765 \begin_layout Standard
3766 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3767 or pass but should rather fail (wrong output).
3769 \begin_inset Note Note
3772 \begin_layout Plain Layout
3773 *invalid* tests (wrong output) are not *unreliable*.
3774 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3783 \begin_layout Standard
3784 The following sublabels are currently present in
3785 \begin_inset Flex Code
3788 \begin_layout Plain Layout
3797 \begin_layout Description
3798 nonstandard Documents with additional requirements, e.g.
3799 a class or package file not in TeXLive.
3801 \begin_inset Note Note
3804 \begin_layout Plain Layout
3806 \begin_inset Quotes eld
3810 \begin_inset Quotes erd
3814 \begin_inset Quotes eld
3818 \begin_inset Quotes erd
3829 \begin_layout Description
3830 erratic Tests depending on local configuration or the phase of the moon.
3834 \begin_layout Description
3835 varying_versions Tests depending on e.g.
3836 OS or version of a non-TeX-Live dependency.
3837 Note that a full, up-to-date TeX Live installation is required so this
3838 sublabel is about versions of other dependencies.
3841 \begin_layout Description
3843 \begin_inset space ~
3846 output Export does not fail but the resulting document has (undetected)
3851 \begin_layout Standard
3852 \paragraph_spacing single
3853 \begin_inset Note Note
3856 \begin_layout Plain Layout
3857 \paragraph_spacing single
3858 These tests are in a strict sense not unreliable but
3862 (not measuring what they should measure).
3871 \begin_layout Paragraph
3872 \begin_inset CommandInset label
3874 name "par:Export-test-filtering"
3878 Export test filtering
3881 \begin_layout Standard
3882 The assignment of a label to a test is controlled by a set of files with
3883 regular expressions that are matched against the test names.
3886 \begin_layout Description
3887 ignoredTests (small file)
3888 \begin_inset Newline newline
3891 Tests selected here are withdrawn in the configuration step (cf.
3893 \begin_inset CommandInset ref
3895 reference "par:Configuring-ctests"
3903 \begin_layout Labeling
3904 \labelwidthstring 00.00.0000
3905 Input Test of any export combination
3908 \begin_layout Labeling
3909 \labelwidthstring 00.00.0000
3910 Output Stop if tests not selected here
3914 \begin_layout Description
3915 unreliableTests: Tests selected pass or fail dependent on the system where
3917 Selected tests gain the label 'unreliable'.
3921 \begin_layout Labeling
3922 \labelwidthstring 00.00.0000
3923 Input Each test which passed 'ignoredTests'
3926 \begin_layout Labeling
3927 \labelwidthstring 00.00.0000
3928 Output Gain label 'unreliable', proceed with checking for 'inverted'.
3932 \begin_layout Description
3934 \begin_inset space \space{}
3941 \begin_layout Labeling
3942 \labelwidthstring 00.00.0000
3943 Input Each test which passed 'ignoredTests'
3946 \begin_layout Labeling
3947 \labelwidthstring 00.00.0000
3948 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3949 tests are reported as failing if the export works without error.) If no
3950 subselection applies, gain labels 'export' and 'inverted'.
3953 \begin_layout Standard
3954 The following filter perfoms a subselection of 'invertedTests':
3957 \begin_layout Description
3958 suspendedTests Tests selected here gain the label 'suspended' but _not_
3959 'export' or 'inverted', although in ctest they remain inverted.
3960 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3964 \begin_layout Labeling
3965 \labelwidthstring 00.00.0000
3966 Input Each test selected by 'invertedTests'
3969 \begin_layout Labeling
3970 \labelwidthstring 00.00.0000
3971 Output Selected test gains label 'suspended'.
3977 \begin_layout Standard
3978 The following table may clarify label assignement
3981 \begin_layout Standard
3982 \begin_inset space \hspace{}
3987 \begin_inset Tabular
3988 <lyxtabular version="3" rows="6" columns="8">
3989 <features tabularvalignment="middle">
3990 <column alignment="left" valignment="top" width="2cm">
3991 <column alignment="left" valignment="top" width="2.5cm">
3992 <column alignment="left" valignment="top" width="2cm">
3993 <column alignment="center" valignment="top" width="2.5cm">
3994 <column alignment="center" valignment="top">
3995 <column alignment="center" valignment="top">
3996 <column alignment="center" valignment="top">
3997 <column alignment="center" valignment="top">
3999 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4002 \begin_layout Plain Layout
4003 Test matching pattern in file:
4008 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4011 \begin_layout Plain Layout
4017 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4020 \begin_layout Plain Layout
4026 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4029 \begin_layout Plain Layout
4035 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4038 \begin_layout Plain Layout
4044 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4047 \begin_layout Plain Layout
4053 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4056 \begin_layout Plain Layout
4062 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4065 \begin_layout Plain Layout
4073 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4076 \begin_layout Plain Layout
4077 ignored\SpecialChar softhyphen
4083 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4086 \begin_layout Plain Layout
4087 unreliable\SpecialChar softhyphen
4093 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4096 \begin_layout Plain Layout
4097 inverted\SpecialChar softhyphen
4103 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4106 \begin_layout Plain Layout
4107 suspended\SpecialChar softhyphen
4113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4116 \begin_layout Plain Layout
4122 <cell alignment="center" valignment="top" topline="true" usebox="none">
4125 \begin_layout Plain Layout
4131 <cell alignment="center" valignment="top" topline="true" usebox="none">
4134 \begin_layout Plain Layout
4140 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4143 \begin_layout Plain Layout
4151 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4154 \begin_layout Plain Layout
4160 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4163 \begin_layout Plain Layout
4169 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4172 \begin_layout Plain Layout
4178 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4181 \begin_layout Plain Layout
4187 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4190 \begin_layout Plain Layout
4196 <cell alignment="center" valignment="top" topline="true" usebox="none">
4199 \begin_layout Plain Layout
4205 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4208 \begin_layout Plain Layout
4214 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4217 \begin_layout Plain Layout
4225 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4228 \begin_layout Plain Layout
4234 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4237 \begin_layout Plain Layout
4239 \begin_inset Newline newline
4243 \begin_inset Newline newline
4251 <cell multirow="3" alignment="left" valignment="middle" 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="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4310 \begin_layout Plain Layout
4316 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4319 \begin_layout Plain Layout
4325 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4328 \begin_layout Plain Layout
4334 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4337 \begin_layout Plain Layout
4343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4346 \begin_layout Plain Layout
4352 <cell alignment="center" valignment="top" topline="true" usebox="none">
4355 \begin_layout Plain Layout
4361 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4364 \begin_layout Plain Layout
4370 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4373 \begin_layout Plain Layout
4381 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4384 \begin_layout Plain Layout
4390 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4393 \begin_layout Plain Layout
4399 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4402 \begin_layout Plain Layout
4408 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4411 \begin_layout Plain Layout
4417 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4420 \begin_layout Plain Layout
4426 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4429 \begin_layout Plain Layout
4435 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4438 \begin_layout Plain Layout
4444 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4447 \begin_layout Plain Layout
4461 \begin_layout Standard
4462 \begin_inset Note Note
4465 \begin_layout Plain Layout
4467 \begin_inset Quotes eld
4471 \begin_inset Quotes erd
4474 filter, this would be far less complicated:
4477 \begin_layout Plain Layout
4478 \begin_inset Tabular
4479 <lyxtabular version="3" rows="6" columns="7">
4480 <features tabularvalignment="middle">
4481 <column alignment="left" valignment="top" width="0pt">
4482 <column alignment="left" valignment="top" width="0pt">
4483 <column alignment="left" valignment="top" width="0pt">
4484 <column alignment="center" valignment="top">
4485 <column alignment="center" valignment="top">
4486 <column alignment="center" valignment="top">
4487 <column alignment="center" valignment="top">
4489 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4492 \begin_layout Plain Layout
4493 Test matching pattern in file:
4498 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4501 \begin_layout Plain Layout
4507 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4510 \begin_layout Plain Layout
4516 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4519 \begin_layout Plain Layout
4525 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4528 \begin_layout Plain Layout
4534 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4537 \begin_layout Plain Layout
4543 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4546 \begin_layout Plain Layout
4554 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4557 \begin_layout Plain Layout
4563 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4566 \begin_layout Plain Layout
4572 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4575 \begin_layout Plain Layout
4581 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4584 \begin_layout Plain Layout
4590 <cell alignment="center" valignment="top" topline="true" usebox="none">
4593 \begin_layout Plain Layout
4599 <cell alignment="center" valignment="top" topline="true" usebox="none">
4602 \begin_layout Plain Layout
4608 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4611 \begin_layout Plain Layout
4619 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4622 \begin_layout Plain Layout
4628 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4631 \begin_layout Plain Layout
4637 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4640 \begin_layout Plain Layout
4646 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4649 \begin_layout Plain Layout
4655 <cell alignment="center" valignment="top" topline="true" usebox="none">
4658 \begin_layout Plain Layout
4664 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4667 \begin_layout Plain Layout
4673 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4676 \begin_layout Plain Layout
4684 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4687 \begin_layout Plain Layout
4693 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4696 \begin_layout Plain Layout
4702 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4705 \begin_layout Plain Layout
4711 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4714 \begin_layout Plain Layout
4720 <cell alignment="center" valignment="top" topline="true" usebox="none">
4723 \begin_layout Plain Layout
4729 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4732 \begin_layout Plain Layout
4738 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4741 \begin_layout Plain Layout
4749 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4752 \begin_layout Plain Layout
4758 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4761 \begin_layout Plain Layout
4767 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4770 \begin_layout Plain Layout
4776 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4779 \begin_layout Plain Layout
4785 <cell alignment="center" valignment="top" topline="true" usebox="none">
4788 \begin_layout Plain Layout
4794 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4797 \begin_layout Plain Layout
4803 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4806 \begin_layout Plain Layout
4814 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4817 \begin_layout Plain Layout
4823 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4826 \begin_layout Plain Layout
4832 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4835 \begin_layout Plain Layout
4841 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4844 \begin_layout Plain Layout
4850 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4853 \begin_layout Plain Layout
4859 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4862 \begin_layout Plain Layout
4868 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4871 \begin_layout Plain Layout
4890 \begin_layout Subsubsection
4894 \begin_layout Standard
4895 These tests check whether a .lyx file loads without any terminal messages.
4896 They correspond to the manual operations of simply opening a .lyx file on
4897 the terminal, exiting LyX once the file is loaded, and then checking whether
4898 there is any output from the terminal.
4899 These tests are useful for catching malformed .lyx files and parsing bugs.
4900 They can also be used to find a .lyx file in which an instance of something
4902 To do this, compile LyX with a local patch that outputs something to the
4903 terminal when an instance is found, and then run the check_load tests to
4904 see if any fail, which would mean that the situation occurs in the LyX
4905 documentation files corresponding to the failed tests.
4906 These tests are expectedly fragile: any LyX diagnostic message, which is
4907 not necessarily an error, would cause the tests to fail.
4908 Similarly, any message output by a library (e.g.
4909 Qt) would also cause failure.
4910 There are some messages that the check_load tests are instructed to ignore,
4911 which are stored in the file
4912 \begin_inset Flex Code
4915 \begin_layout Plain Layout
4916 development/autotests/filterCheckWarnings
4924 \begin_layout Standard
4925 Under cmake, the tests are labeled as 'load'.
4928 \begin_layout Subsubsection
4932 \begin_layout Standard
4933 Automated tests based on the "MonKey Testing" keytest program are enabled
4934 if the necessary dependencies are found and if the CMake flag
4935 \begin_inset Flex Code
4938 \begin_layout Plain Layout
4939 -DLYX_ENABLE_KEYTESTS=ON
4945 They are documented in the README document in
4946 \begin_inset Flex Code
4949 \begin_layout Plain Layout
4950 development/autotests
4955 subfolder of the \SpecialChar LyX
4956 source code distribution.
4959 \begin_layout Subsubsection
4963 \begin_layout Standard
4964 These tests combine lyx2lyx tests with check_load tests.
4965 They fail if either fails.
4968 \begin_layout Subsubsection
4972 \begin_layout Standard
4973 The URL tests are enabled with the
4974 \begin_inset Flex Code
4977 \begin_layout Plain Layout
4978 -DLYX_ENABLE_URLTESTS=ON
4983 CMake flag and are useful for finding broken links in our documentation
4985 If a URL test fails, to see which link in particular was reported as broken,
4987 \begin_inset Flex Code
4990 \begin_layout Plain Layout
4997 These tests are extremely fragile (e.g.
4998 a test can depend on your Internet connection) and a failed URL test should
4999 not be taken too seriously.
5000 URL tests are labeled as
5005 \begin_layout Paragraph
5009 \begin_layout Standard
5010 cmake is required to run the \SpecialChar LyX
5011 tests, running them is not implemented for
5015 \begin_layout Standard
5016 The appropriate commands are:
5019 \begin_layout Itemize
5025 \begin_inset Newline newline
5028 runs all tests with label
5033 \begin_layout Itemize
5036 ctest -R 'check_.*urls'
5039 \begin_inset Newline newline
5042 runs the tests 'check_accessible_urls'
5045 \begin_layout Standard
5046 Associated test results can be examined in ctest-log directory in files
5047 of the form 'LastFailed.*URLS.log'
5050 \begin_layout Section
5051 Development policies
5054 \begin_layout Standard
5055 This chapter lists some guidelines that should be followed.
5056 This list is not complete, and many guidelines are in separate chapters,
5058 \begin_inset Quotes eld
5061 When is an update of the .lyx file format number needed?
5062 \begin_inset Quotes erd
5066 \begin_inset CommandInset ref
5068 reference "sec:When-is-an"
5075 \begin_layout Subsection
5076 When to set a fixed milestone?
5079 \begin_layout Standard
5080 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5084 \begin_layout Enumerate
5085 Somebody is actively working on a fix.
5088 \begin_layout Enumerate
5089 The bug is so severe that it would block the release if it is not fixed.
5092 \begin_layout Standard
5093 If a bug is important, but nobody is working on it, and it is no showstopper,
5094 use a milestone like 2.1.x or 2.2.x.
5095 For all other bugs, do not set a milestone at all.
5098 \begin_layout Subsection
5099 Can we add rc entries in stable branch?
5102 \begin_layout Standard
5104 We are supposed to increase the prefs2prefs version number with such things.
5107 \begin_layout Section
5108 \begin_inset CommandInset label
5110 name "sec:Documentation-policies"
5114 Documentation policies
5117 \begin_layout Subsection
5121 \begin_layout Standard
5123 \begin_inset space ~
5126 rules in editing the docs:
5129 \begin_layout Enumerate
5130 \begin_inset CommandInset label
5132 name "enu:If-you-are"
5136 If you are not the maintainer of a doc file or a chapter/section, you MUST
5137 use change tracking so that the maintainer could review your changes
5140 \begin_layout Enumerate
5141 Respect the formatting of the document.
5142 The different files use different formatting styles.
5143 That is OK and has historic reasons nobody fully knows ;-).
5144 But it is important to be consistent within one file.
5147 \begin_layout Enumerate
5148 All changes you make to a file in one language MUST also go the file in
5149 the other actively maintained languages.
5150 Normally the maintainer does this for you, if you are the maintainer, you
5151 must do this by copying or changing the changed or added text to the other
5152 files so that the translators sees the blue underlined text and know what
5153 they have to translate and what was changed.
5156 \begin_layout Enumerate
5157 You MUST assure that the document is compilable as
5158 \begin_inset Quotes eld
5162 \begin_inset Quotes erd
5165 or the document's default output format after your changes.
5168 \begin_layout Enumerate
5169 All fixes (typos, compilation fixes, updates info etc.) go at first into
5170 the current GIT branch because the user should benefit from all fixes with
5171 every minor release.
5172 Feel free to commit directly to branch as long as you follow rule
5173 \begin_inset space ~
5177 \begin_inset CommandInset ref
5179 reference "enu:If-you-are"
5184 You can immediately commit to master as well.
5187 \begin_layout Enumerate
5188 \begin_inset CommandInset label
5190 name "enu:The-fileformat-of"
5194 The fileformat of a file must not be changed unless you document a new feature
5195 in LyX that requires a new fileformat.
5196 The reason for this rule is to keep it easy for the doc maintainers to
5197 port/backport changes to from master/branch.
5200 \begin_layout Standard
5201 The main documentation consists of these files:
5204 \begin_layout Description
5205 splash.lyx it is the first file you see after an installation.
5206 We assume that a new user sees this.
5207 It is therefore designed to be as simple as possible.
5208 Therefore please don't add any new formatting, only fix typos etc.
5209 Splash.lyx is up to date for \SpecialChar LyX
5210 2.1.x, currently maintained by Uwe Stöhr.
5213 \begin_layout Description
5214 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5216 It therefore uses a limited set of formatting.
5217 For example a standard document class.
5218 Since new users will first learn about the formatting possibilities of
5220 please keep this file that simple.
5221 Intro.lyx is up to date for \SpecialChar LyX
5222 2.1.x, currently maintained by Uwe Stöhr.
5225 \begin_layout Description
5226 Tutorial.lyx our tutorial.
5227 It must be always up to date.
5228 Normally there is nothing to add since we don't want to overwhelm new users
5229 with too much details.
5230 The will learn these details while using \SpecialChar LyX
5231 and we have special manuals.
5232 Tutorial.lyx is up to date for \SpecialChar LyX
5233 2.1.x, currently maintained by Uwe Stöhr.
5236 \begin_layout Description
5237 UserGuide.lyx our main user guide.
5238 It covers a mixture of basic and detailed information.
5239 Some information is also in the Math and EmbeddedObjects manual so that
5240 the UserGuide refers to these files.
5241 UserGuide.lyx is up to date for \SpecialChar LyX
5242 2.1.x, currently maintained by Uwe Stöhr.
5245 \begin_layout Description
5246 EmbeddedObjects.lyx a special manual to explain things like tables floats
5249 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5250 2.1.x, currently maintained by Uwe
5254 \begin_layout Description
5255 Math.lyx a special manual to explain everything regarding math in all detail.
5256 Math.lyx is up to date for \SpecialChar LyX
5257 2.1.x, currently maintained by Uwe Stöhr.
5260 \begin_layout Description
5261 Additional.lyx this manual covers information that would be too much detail
5262 for the UserGuide or would make the UserGuide uncompilable or only compilable
5263 when installing a lot of special \SpecialChar LaTeX
5265 What should be in the UserGuide or better in Additional is a matter of
5267 it is up to you to decide that.
5268 Additional.lyx is not completely up to date for \SpecialChar LyX
5271 \begin_inset space ~
5274 8 is up to date and currently maintained by Uwe Stöhr.
5275 It certainly needs a rewrite and update.
5276 For example many info in chapter
5277 \begin_inset space ~
5280 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5284 \begin_layout Description
5285 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5287 output formats, operating systems, languages etc.
5288 It is currently completely out of date and needs a major rewrite and update.
5289 If you do this please assure that your information are given for all OSes
5290 and \SpecialChar LaTeX
5291 distributions (meaning be as objective as possible).