1 #LyX 2.3 created this file. For more info see http://www.lyx.org/
5 \save_transient_properties true
6 \origin /buildlyxdir/doc/
8 \options BCOR8mm,captions=tableheading
9 \use_default_options false
13 \maintain_unincluded_children false
15 \language_package default
18 \font_roman "lmodern" "default"
19 \font_sans "lmss" "default"
20 \font_typewriter "lmtt" "default"
21 \font_math "auto" "auto"
22 \font_default_family default
23 \use_non_tex_fonts false
26 \font_sf_scale 100 100
27 \font_tt_scale 100 100
29 \use_dash_ligatures true
31 \default_output_format pdf2
33 \bibtex_command default
34 \index_command default
38 \pdf_title "LyX's Development manual"
39 \pdf_author "LyX Team"
40 \pdf_subject "LyX's development documentation"
41 \pdf_keywords "LyX, Documentation, Development"
43 \pdf_bookmarksnumbered true
44 \pdf_bookmarksopen true
45 \pdf_bookmarksopenlevel 1
50 \pdf_pdfusetitle false
51 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
54 \use_package amsmath 1
55 \use_package amssymb 1
58 \use_package mathdots 1
59 \use_package mathtools 1
61 \use_package stackrel 1
62 \use_package stmaryrd 1
63 \use_package undertilde 1
65 \cite_engine_type default
69 \paperorientation portrait
74 \notefontcolor #0000ff
81 \paragraph_separation indent
82 \paragraph_indentation default
84 \math_numbering_side default
89 \paperpagestyle headings
90 \tracking_changes false
100 Developing \SpecialChar LyX
104 \begin_layout Subtitle
109 by the \SpecialChar LyX
114 \begin_layout Plain Layout
116 If you have comments or error corrections, please send them to the \SpecialChar LyX
119 \begin_inset Flex Code
122 \begin_layout Plain Layout
123 <lyx-docs@lists.lyx.org>
136 \begin_layout Standard
137 \begin_inset CommandInset toc
138 LatexCommand tableofcontents
145 \begin_layout Section
149 \begin_layout Standard
150 This manual documents some aspects of \SpecialChar LyX
152 It is currently rather incomplete, but will hopefully be extended in the
154 Meanwhile, additional information can be found in the
155 \begin_inset Flex Code
158 \begin_layout Plain Layout
164 subfolder of the \SpecialChar LyX
165 source code distribution.
166 This document is not translated, since the development language of \SpecialChar LyX
169 If you just want to use \SpecialChar LyX
170 , then you don't need to read this manual.
171 However, if you want to learn more about how \SpecialChar LyX
172 is developed, or even want
173 to participate in \SpecialChar LyX
174 development, you may find some interesting information
178 \begin_layout Section
182 \begin_layout Standard
184 uses several custom file formats for configuration files and documents.
185 This chapter contains some background concerning these file formats.
186 Several file formats are also described in detail in the regular user documenta
190 \begin_layout Subsection
194 \begin_layout Subsection
195 When is an update of the .lyx file format number needed?
196 \begin_inset CommandInset label
198 name "sec:When-is-an"
205 \begin_layout Standard
206 When you are working on a new feature you may ask yourself whether it needs
207 an update of the .lyx file format number.
208 Whether an update is needed or not is not always obvious.
213 Whenever there is the danger that a previous version of LyX cannot open
214 a file using the new feature, a file format update is needed.
217 \begin_layout Standard
218 The file format change allows lyx2lyx rules to implement backwards compatibility.
219 Below you can find a list of reasons for file format updates with explanations:
222 \begin_layout Description
231 setting Whenever you introduce a new setting that is stored in the document
232 header, a file format update is needed.
235 \begin_layout Description
244 setting If a certain setting becomes obsolete and gets removed, a file format
248 \begin_layout Description
274 \begin_inset space \thinspace{}
281 \begin_layout Description
282 \paragraph_spacing single
295 package The reason for this is that there is no true ERT inset for math
296 formulas: Each command is parsed, and if a user happens to define a local
297 command with the same name as a command that triggers an automatic load
298 of a package, they need to be able to switch off the automatic loading
300 This switch is stored by the
301 \begin_inset Flex Code
304 \begin_layout Plain Layout
313 \begin_layout Description
318 language that is stored in
319 \begin_inset Flex Code
322 \begin_layout Plain Layout
332 \begin_inset Note Note
335 \begin_layout Plain Layout
336 This requirement is under discussion.
345 \begin_layout Description
350 inset Of course a new inset requires a file format update.
353 \begin_layout Description
358 style If a new style or inset layout is added to any layout file or module
359 shipped with \SpecialChar LyX
360 , then a new file format is needed in the master (development)
362 It is possible to backport new styles to the stable version without a file
365 \begin_inset CommandInset ref
367 reference "subsec:Backporting-new-styles"
371 for more information.
374 \begin_layout Description
379 style If a style or inset layout is removed in any layout file or module
380 shipped with \SpecialChar LyX
381 , a new file format is required.
384 \begin_layout Standard
389 layouts and modules do
393 require a file format update (changed 03/16, see
394 \begin_inset CommandInset ref
396 reference "subsec:New-layouts"
404 \begin_layout Standard
405 If you are still unsure, please ask on the development list.
408 \begin_layout Subsection
409 \begin_inset CommandInset label
411 name "subsec:update_lyx_files"
415 How to update the file format number of .lyx files
418 \begin_layout Standard
419 Once you come to the conclusion that a file format update is needed, you
420 should use the following procedure to perform the update:
423 \begin_layout Enumerate
424 Implement and test the new feature, including the reading and writing of
426 Note that any file produced at this stage does not use a valid format,
427 so do not use this version of \SpecialChar LyX
428 for working on any important documents.
431 \begin_layout Enumerate
432 \begin_inset CommandInset label
434 name "enu:Describe_format"
438 Describe the new format in
439 \begin_inset Flex Code
442 \begin_layout Plain Layout
451 \begin_layout Enumerate
452 Update the \SpecialChar LyX
453 file format number in
454 \begin_inset Flex Code
457 \begin_layout Plain Layout
466 \begin_layout Enumerate
467 \begin_inset CommandInset label
469 name "enu:Add-an-entry"
473 Add an entry to both format lists (for conversion and reversion) in
474 \begin_inset Newline newline
478 \begin_inset Flex Code
481 \begin_layout Plain Layout
482 lib/lyx2lyx/lyx_2_3.py
488 Add a conversion routine if needed (e.
489 \begin_inset space \thinspace{}
492 g., a new header setting always needs a conversion that adds the new setting,
493 but a new document language does not need one).
494 Add a reversion routine if needed.
496 \begin_inset Newline newline
499 While the conversion routine is required to produce a document that is equivalen
500 t to the old version, the requirements of the reversion are not that strict.
501 If possible, try to produce a proper reversion, using ERT if needed, but
502 for some features this might be too complicated.
503 In this case, the minimum requirement of the reversion routine is that
504 it produces a valid document which can be read by an older \SpecialChar LyX
506 If absolutely needed, even data loss is allowed for the reversion.
507 (In that case, you might want to add a LyX comment that indicates what
508 you have had to do, so the user is at least warned).
511 \begin_layout Enumerate
512 Since tex2lyx has several implicit file format dependencies caused by sharing
513 code with \SpecialChar LyX
514 , updating the file format of .lyx files produced by tex2lyx at
515 the same time as updating the main .lyx file format is strongly recommended.
516 Therefore, a compiler warning will be issued if the \SpecialChar LyX
517 and tex2lyx .lyx file
518 format numbers differ.
519 In many cases the tex2lyx update requires only the first and last item
524 \begin_layout Enumerate
525 Update the tex2lyx file format number in
526 \begin_inset Flex Code
529 \begin_layout Plain Layout
538 \begin_layout Enumerate
539 If the lyx2lyx conversion from the old to the new format is empty, or if
540 tex2lyx does not yet output the changed feature, you do not need any further
542 Otherwise, search for the changed feature in tex2lyx, and adjust the output
543 according to the lyx2lyx changes.
546 \begin_layout Enumerate
547 Update the tex2lyx test references as described in
548 \begin_inset CommandInset ref
549 LatexCommand formatted
550 reference "sec:Updating-test-references"
558 \begin_layout Enumerate
559 If you did not implement full tex2lyx support for the new feature, add a
561 \begin_inset Flex Code
564 \begin_layout Plain Layout
570 describing the missing bits.
571 Note that it is perfectly fine if you do not add full tex2lyx support for
572 a new feature: The updating recommendation above is only issued for the
573 syntax of the produced .lyx file.
574 It is no problem if some features supported by \SpecialChar LyX
575 are still output as ERT
577 The problems in the past that resulted in the update recommendation were
578 related to mixed version syntax, not ERT.
581 \begin_layout Enumerate
582 It would be nice if you could create a .lyx test file which contains instances
583 of all changed or added features.
584 This could then be used to test lyx2lyx and tex2lyx.
585 Unfortunately, it has not yet been decided how to collect such examples,
586 so please ask on the development list if you want to create one.
589 \begin_layout Enumerate
590 \begin_inset CommandInset label
592 name "enu:updatefiles"
596 Test your lyx2lyx code by updating LyX's .lyx documentation files to the
598 The developer who makes the change knows best what changes to expect when
599 inspecting the resulting diff.
600 Because of this, you might be able to catch a bug in the lyx2lyx code that
601 updates the format just by taking a quick scan through the large diff that
603 \begin_inset Note Note
606 \begin_layout Plain Layout
607 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
608 see which layout update made an unexpected change by looking at the git
609 log of a .lyx file that suffers the problem.
614 To do this, first make sure that there are no changes to the git repository
615 that you will not want to commit (this is needed because it will be convenient
616 to commit with the command
617 \begin_inset Flex Code
620 \begin_layout Plain Layout
627 Then run the following command in the root folder of the source:
628 \begin_inset Flex Code
631 \begin_layout Plain Layout
632 python development/tools/updatedocs.py
638 Look at the resulting changes using the command
639 \begin_inset Flex Code
642 \begin_layout Plain Layout
649 If anything looks surprising, please investigate.
650 Keep in mind that the case of
651 \begin_inset Flex Code
654 \begin_layout Plain Layout
660 is special, because it is first generated with
661 \begin_inset Flex Code
664 \begin_layout Plain Layout
670 before being converted to the latest format.
671 \begin_inset Newline newline
675 \begin_inset Note Greyedout
678 \begin_layout Plain Layout
683 Only commit file format changes in the doc files if these files are using
684 the new feature of the new file format.
690 \begin_inset CommandInset ref
692 reference "enu:The-fileformat-of"
696 of the documentation policies described in sec.
701 \begin_inset CommandInset ref
703 reference "sec:Documentation-policies"
715 \begin_layout Enumerate
716 Finally, commit using
717 \begin_inset Flex Code
720 \begin_layout Plain Layout
729 \begin_layout Subsection
730 Updating the file format number of layout files
733 \begin_layout Standard
734 The procedure for updating the layout files is similar to that in step
735 \begin_inset CommandInset ref
737 reference "enu:updatefiles"
742 \begin_inset CommandInset ref
744 reference "subsec:update_lyx_files"
750 \begin_inset Flex Code
753 \begin_layout Plain Layout
754 python development/tools/updatelayouts.py
760 \begin_inset Flex Code
763 \begin_layout Plain Layout
772 \begin_layout Standard
773 Note that we do not automatically update any local layout used in the
774 \begin_inset Flex Code
777 \begin_layout Plain Layout
783 files shipped with \SpecialChar LyX
784 because users would then not be able to export to older
786 For example, if a 2.2.0 user exported a template to 2.1.x format and tried
787 to open the file in \SpecialChar LyX
788 2.1.x, there would be an error because the file would
789 contain a local layout whose format is too new.
790 The root reason for this is that we do not support converting layouts to
791 older layout formats, as we do for the
792 \begin_inset Flex Code
795 \begin_layout Plain Layout
804 \begin_layout Subsection
805 Updating the file format number of bind/ui files
808 \begin_layout Standard
809 A change to the functionality of existing LFUNs can require a conversion
811 \begin_inset Flex Code
814 \begin_layout Plain Layout
821 \begin_inset Flex Code
824 \begin_layout Plain Layout
830 files, and therefore an increment of the LFUN format, as well as a conversion
832 \begin_inset Flex Code
835 \begin_layout Plain Layout
842 The latter cannot be done automatically and also requires an update of
846 \begin_inset space \space{}
849 of someone who might have made a set of \SpecialChar LyX
850 teaching manuals for use in their
855 \begin_layout Plain Layout
856 \begin_inset Flex URL
859 \begin_layout Plain Layout
861 https://www.lyx.org/trac/ticket/9794
874 \begin_layout Standard
875 To update the LFUN format:
878 \begin_layout Enumerate
879 Increment the LFUN file format number in
880 \begin_inset Flex Code
883 \begin_layout Plain Layout
892 \begin_layout Enumerate
893 Implement the LFUN conversion in
894 \begin_inset Flex Code
897 \begin_layout Plain Layout
898 lib/scripts/prefs2prefs_lfuns.py
906 \begin_layout Enumerate
908 \begin_inset CommandInset ref
910 reference "enu:updatefiles"
915 \begin_inset CommandInset ref
917 reference "subsec:update_lyx_files"
922 \begin_inset Flex Code
925 \begin_layout Plain Layout
931 command, use this command:
932 \begin_inset Flex Code
935 \begin_layout Plain Layout
936 bash development/tools/updatelfuns.sh
943 \begin_inset Note Note
946 \begin_layout Plain Layout
947 This file should really be converted to python.
955 \begin_layout Enumerate
956 Update Info insets in
957 \begin_inset Flex Code
960 \begin_layout Plain Layout
967 To do so, increment the \SpecialChar LyX
968 format and proceed as in
969 \begin_inset CommandInset ref
971 reference "subsec:update_lyx_files"
976 \begin_inset CommandInset ref
978 reference "enu:Describe_format"
983 \begin_inset CommandInset ref
985 reference "enu:updatefiles"
990 In the lyx2lyx implementation (step
991 \begin_inset CommandInset ref
993 reference "enu:Add-an-entry"
997 ), implement a conversion similar to the one in
998 \begin_inset Flex Code
1001 \begin_layout Plain Layout
1002 prefs2prefs_lfuns.py
1007 above, as well as a corresponding reversion; for this one can use
1008 \begin_inset Flex Code
1011 \begin_layout Plain Layout
1018 \begin_inset Flex Code
1021 \begin_layout Plain Layout
1022 lib/lyx2lyx/lyx2lyx_tools.py
1031 \begin_layout Subsection
1032 Backporting new styles to the stable version
1033 \begin_inset CommandInset label
1035 name "subsec:Backporting-new-styles"
1042 \begin_layout Standard
1043 Starting with the stable \SpecialChar LyX
1044 2.1 branch, there is a mechanism in place to backport
1045 new styles to the stable version without the need to update the file format.
1046 The basic idea is that the new style definition is automatically copied
1047 to the document preamble so that it can even be used by older minor versions
1048 that did not yet include the style.
1049 To backport a new style to the stable version, the following steps are
1053 \begin_layout Enumerate
1055 \begin_inset Flex Code
1058 \begin_layout Plain Layout
1064 to the style definition in the development version.
1067 \begin_layout Enumerate
1068 Copy the style definition to the stable version, but use
1069 \begin_inset Flex Code
1072 \begin_layout Plain Layout
1079 If needed adjust the format to the one used by the stable version (see
1080 the customization manual for details of the layout file format).
1083 \begin_layout Enumerate
1084 For each update of the style in a later stable version, increase the argument
1086 \begin_inset Flex Code
1089 \begin_layout Plain Layout
1096 (In the stable version, the development version should not be touched.)
1099 \begin_layout Standard
1100 For details about the
1101 \begin_inset Flex Code
1104 \begin_layout Plain Layout
1110 flag see the customization manual.
1112 \begin_inset Flex Code
1115 \begin_layout Plain Layout
1121 support is needed for backported styles: Since the style of the development
1122 version has an infinite version number, it will always be used.
1123 Furthermore, since its version number is less than one, the style will
1124 not be written anymore to the document header for files saved by the new
1128 \begin_layout Section
1129 New layouts and modules
1132 \begin_layout Subsection
1133 \begin_inset CommandInset label
1135 name "subsec:New-layouts"
1142 \begin_layout Standard
1143 Adding a new layout file to the \SpecialChar LyX
1145 \begin_inset Quotes eld
1148 officially supported
1149 \begin_inset Quotes erd
1153 You should therefore think carefully about whether you really want to do
1154 this and discuss it on lyx-devel, since you will need to be prepared to
1155 update and fix the layout if necessary.
1156 If the layout is experimental or for a rarely used document class, then
1157 it may be better to add it to the relevant portion of the \SpecialChar LyX
1161 \begin_inset CommandInset href
1163 target "https://wiki.lyx.org/Layouts/Layouts"
1171 \begin_layout Standard
1172 In older versions of this document, it was stated that new layout files
1173 require a file format change.
1174 After some discussion, it was decided that this is not needed.
1178 \begin_layout Plain Layout
1180 \begin_inset CommandInset href
1182 name "the thread “Proposal for a guide on updating layouts”"
1183 target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202"
1197 For reference, here are the arguments on each side
1201 \begin_layout Description
1203 \begin_inset Quotes eld
1206 New layout files are a file format change
1207 \begin_inset Quotes erd
1213 \begin_layout Itemize
1214 All documents produced by 2.2.
1215 \begin_inset Formula $x$
1218 can always be edited and exported even if
1219 \begin_inset Formula $x$
1223 This is important for people using different machines, or exchanging work
1227 \begin_layout Description
1229 \begin_inset Quotes eld
1232 New layout files are not a file format change
1233 \begin_inset Quotes erd
1239 \begin_layout Itemize
1240 No new LaTeX classes can be supported in a stable version, and stable versions
1241 have a typical lifetime of 2–3 years.
1244 \begin_layout Itemize
1245 We have the same situation already with custom layout files: If a document
1246 using a custom layout file is moved between machines or people, then the
1247 layout file needs to be exchanged as well.
1248 If that is not done, then we have a fallback implemented so that such documents
1249 can still be edited, but not exported, and the user gets a warning.
1253 \begin_layout Itemize
1254 The lyx2lyx script cannot do anything useful in such a case.
1258 \begin_layout Standard
1259 If you have decided that you are going to add a new layout file to \SpecialChar LyX
1261 then, you should do the following:
1264 \begin_layout Enumerate
1265 Put your new layout file in
1266 \begin_inset Flex Code
1269 \begin_layout Plain Layout
1276 \begin_inset Flex Code
1279 \begin_layout Plain Layout
1280 git add lib/layouts/newlayout.layout
1285 ) so that it will be committed.
1288 \begin_layout Enumerate
1290 \begin_inset Flex Code
1293 \begin_layout Plain Layout
1299 , so that the new layout actually gets installed.
1302 \begin_layout Enumerate
1304 \begin_inset Flex Code
1307 \begin_layout Plain Layout
1308 lib/doc/LaTeXConfig.lyx
1313 containing in particular a line like
1321 \begin_layout Standard
1322 where [InsetInfo] is obtained by entering in the minibuffer (Alt+X)
1323 \begin_inset Flex Code
1326 \begin_layout Plain Layout
1327 info-insert textclass <name>
1333 This inset will automatically display a boxed
1334 \begin_inset Quotes eld
1338 \begin_inset Quotes erd
1342 \begin_inset Quotes eld
1346 \begin_inset Quotes erd
1349 depending on the availability of the package.
1353 \begin_layout Enumerate
1354 A template or example is strongly encouraged (but not necessarily required).
1355 It is also possible to provide both.
1357 \begin_inset Flex Code
1360 \begin_layout Plain Layout
1367 \begin_inset Flex Code
1370 \begin_layout Plain Layout
1379 \begin_layout Enumerate
1380 Reconfigure \SpecialChar LyX
1384 \begin_layout Enumerate
1385 Ensure the autotests for the new layout pass (see
1386 \begin_inset CommandInset ref
1388 reference "par:when-to-run-an-export-test"
1395 \begin_layout Subsection
1399 \begin_layout Standard
1400 Adding a new module is very similar to adding a new layout.
1401 Therefore, the previous section applies to new modules as well, with two
1405 \begin_layout Enumerate
1406 You only need to add an entry to
1407 \begin_inset Flex Code
1410 \begin_layout Plain Layout
1411 lib/doc/LaTeXConfig.lyx
1416 if the module requires a LaTeX package.
1417 In that case, the command for entering the InsetInfo is:
1418 \begin_inset Flex Code
1421 \begin_layout Plain Layout
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
2984 \begin_layout Labeling
2985 \labelwidthstring -R
2986 \begin_inset Flex Code
2989 \begin_layout Plain Layout
2990 \SpecialChar nobreakdash
2991 \SpecialChar nobreakdash
2997 Set a global timeout on all tests that do not already have a timeout set
3002 \begin_layout Standard
3003 There have been bugs in LyX and in \SpecialChar LaTeX
3004 which cause compilation to hang, and
3005 without a timeout a test might never stop (in one case there was even a
3007 If a test times out, the
3008 \begin_inset Flex Code
3011 \begin_layout Plain Layout
3017 command exits with error, but you can distinguish between a timed out test
3018 and a failed test in the output reported at the end of the
3019 \begin_inset Flex Code
3022 \begin_layout Plain Layout
3032 \begin_layout Standard
3034 \begin_inset Flex Code
3037 \begin_layout Plain Layout
3043 ) the full list of command line options.
3046 \begin_layout Paragraph
3050 \begin_layout Itemize
3051 run only the export tests:
3052 \begin_inset Flex Code
3055 \begin_layout Plain Layout
3064 \begin_layout Itemize
3066 \begin_inset Flex Code
3069 \begin_layout Plain Layout
3070 ctest -L "inverted|suspended"
3078 \begin_layout Itemize
3079 list all export tests which match any of the labelling patterns:
3080 \begin_inset Flex Code
3083 \begin_layout Plain Layout
3094 \begin_layout Itemize
3095 exclude rarely used output formats and post-processing tests
3096 \begin_inset Flex Code
3099 \begin_layout Plain Layout
3100 ctest -L export -E "_(texF|dvi3|pdf3?)"
3108 \begin_layout Paragraph
3109 \begin_inset CommandInset label
3111 name "subsec:Interpreting-export-tests"
3115 Interpreting the export test results
3118 \begin_layout Standard
3119 A test can fail for several reasons, not all of them bad.
3122 \begin_layout Enumerate
3123 A new or edited sample document may be incompatible with some output formats.
3126 \begin_layout Enumerate
3127 A dependency is not met (e.g.
3128 the \SpecialChar LaTeX
3130 One hint that this is the case is that the corresponding
3131 \begin_inset Flex Code
3134 \begin_layout Plain Layout
3140 test will likely also fail.
3143 \begin_layout Enumerate
3144 An inverted test fails to fail (i.e.
3145 export that previously failed now works).
3148 \begin_layout Enumerate
3149 An external dependency was updated (e.g.
3154 \begin_layout Enumerate
3155 A recent code change introduced a bug.
3158 \begin_layout Enumerate
3159 \begin_inset CommandInset label
3165 A change in a document exposed a previously unknown bug or an incompatibility
3166 with an export format (e.g.
3167 Lua\SpecialChar LaTeX
3171 \begin_layout Standard
3172 Because the .lyx files are exported in several formats, it is not surprising
3173 that many of the exports fail.
3174 This expectation of failure is addressed by
3175 \begin_inset Quotes eld
3179 \begin_inset Quotes erd
3182 the tests, that is, by marking the test as
3183 \begin_inset Quotes eld
3187 \begin_inset Quotes erd
3190 if the export exits with error and as
3191 \begin_inset Quotes eld
3195 \begin_inset Quotes erd
3198 if the export succeeds
3203 It follows that these expected failures will not show up as failed tests
3204 in the test results and thus will not pollute the
3205 \begin_inset Quotes eld
3209 \begin_inset Quotes erd
3213 If the export actually succeeds, then the test will fail.
3214 The purpose of this failure is to get your attention—something has changed,
3215 possibly for the better.
3218 \begin_layout Standard
3219 We try to document why a test is inverted or ignored.
3220 See the comment (prefixed with
3221 \begin_inset Flex Code
3224 \begin_layout Plain Layout
3230 ) above the block in which the test is listed as inverted or ignored in
3232 \begin_inset Flex Code
3235 \begin_layout Plain Layout
3236 development/autotests/invertedTests
3242 \begin_inset Flex Code
3245 \begin_layout Plain Layout
3246 development/autotests/unreliableTests
3252 \begin_inset Flex Code
3255 \begin_layout Plain Layout
3256 development/autotests/ignoredTests
3265 \begin_layout Standard
3266 A good question is why do we enable the tests for non-default formats? The
3267 answer is that if a non-default route is broken it is often because a bug
3268 was introduced in LyX and not because a document-specific change was made
3269 that is not supported by the route.
3270 In other words, there is a high signal/noise ratio in the export tests
3271 for some non-default formats.
3275 \begin_layout Standard
3276 When a test or several tests fail, consider checking the files in the
3277 \begin_inset Flex Code
3280 \begin_layout Plain Layout
3286 subdirectory of your build directory.
3287 In this subdirectory are three files: the file
3288 \begin_inset Flex Code
3291 \begin_layout Plain Layout
3297 simply lists the tests that failed on your last
3298 \begin_inset Flex Code
3301 \begin_layout Plain Layout
3308 \begin_inset Flex Code
3311 \begin_layout Plain Layout
3317 file contains the output from the tests (and often has details explaining
3318 why a test failed); and the
3319 \begin_inset Flex Code
3322 \begin_layout Plain Layout
3328 file lists the times that it took to run the tests.
3331 \begin_layout Paragraph
3332 What action should you take if a test fails?
3335 \begin_layout Standard
3336 \paragraph_spacing single
3337 It is always good to check manually why something fails and if it passes
3338 if the PDF output is good.
3341 \begin_layout Itemize
3342 Generally, if a change breaks compilation for the target format (for the
3343 manuals pdf2) without solving some important other issue,
3345 fix or revert the commit
3347 that led to failure.
3350 \begin_layout Itemize
3351 If it is not possible to (immediately) fix the failure but there are reasons
3352 not to revert the commit (e.g.
3353 it fixes another more important issue),
3357 the failing test case (see
3358 \begin_inset CommandInset ref
3360 reference "par:Inverted-tests"
3367 \begin_layout Itemize
3372 test case fails because the export now works, first confirm that the output
3373 of the corresponding export looks good (e.g., not garbled text).
3378 the test by removing the pattern from the
3379 \begin_inset Quotes eld
3383 \begin_inset Quotes erd
3387 \begin_inset CommandInset ref
3389 reference "par:Inverted-tests"
3396 \begin_layout Itemize
3397 If the export did not fail previously but led to wrong output (PDF, say),
3401 \begin_layout Plain Layout
3402 Non-failing test with wrong output should be labeled as
3403 \begin_inset Quotes eld
3406 unreliable:wrong_output
3407 \begin_inset Quotes erd
3411 \begin_inset CommandInset ref
3413 reference "par:Unreliable-tests"
3422 it is in fact an improvement when the test now fails.
3427 the failing test case (see
3428 \begin_inset CommandInset ref
3430 reference "par:Inverted-tests"
3437 \begin_layout Itemize
3438 In case of tests failing due to missing requirements (tests labeled
3439 \begin_inset Quotes eld
3442 unreliable:nonstandard
3443 \begin_inset Quotes erd
3446 or testing on a system with only a subset of TeXLive installed), ignore
3447 the failure, ask for someone else to run the test, or install the missing
3448 resources and try again.
3451 \begin_layout Itemize
3452 Check the log file Testing/Temporary/LastTest.log.
3453 In case of latex-errors rerun the failing test with environment variable
3454 'LYX_DEBUG_LATEX' set to '1'.
3455 This will include latex messages in LastTest.log, so it should be easier
3456 to interpret the fail-reason.
3459 \begin_layout Paragraph
3460 \begin_inset CommandInset label
3462 name "par:Inverted-tests"
3469 \begin_layout Standard
3470 Test cases whose name matches a pattern in the file
3471 \begin_inset Flex Code
3474 \begin_layout Plain Layout
3475 development/autotests/invertedTests
3485 They get also the test property
3486 \begin_inset Flex Code
3489 \begin_layout Plain Layout
3496 they are reported as failing if the export works without error
3497 \begin_inset Flex URL
3500 \begin_layout Plain Layout
3502 https://cmake.org/cmake/help/v3.0/command/set_tests_properties.html
3510 \begin_layout Standard
3511 Add failing cases to this file, if they cannot be solved
3512 \begin_inset Quotes eld
3516 \begin_inset Quotes erd
3519 but it is expected that the export will work in a foreseeable future, e.g.
3520 low priority issues like failures to export to a non-target format (for
3521 the manuals everything except pdf2).
3524 \begin_layout Standard
3525 The following sublabels are currently present in
3526 \begin_inset Flex Code
3529 \begin_layout Plain Layout
3538 \begin_layout Description
3539 todo test failures that require attention:
3543 \begin_layout Itemize
3544 minor issues to explore and properly sort later,
3547 \begin_layout Itemize
3551 \begin_layout Itemize
3552 LyX bugs to report at trac (move pattern to section "lyxbugs" once done).
3556 \begin_layout Description
3557 lyxbugs LyX bugs with a Trac number.
3560 \begin_layout Description
3561 ert Export failures due to "raw" LaTeX use in ERT or preamble code.
3565 \begin_layout Standard
3566 "Wontfix" if demonstrating correct use and OK in the default output format.
3570 \begin_layout Description
3571 texissues Export fails due to LaTeX limitations like non-ASCII characters
3572 in verbatim or listings, incompatible packages, ...
3576 \begin_layout Standard
3577 "Wontfix" if documents demonstrate correct use in the default output format:
3580 \begin_layout Itemize
3581 If the source can be made more robust without becoming "hackish", fix the
3585 \begin_layout Itemize
3586 if LyX could be enhanced to care for a permanent TeX limitation, file a
3587 ticket at trac and add a pattern under lyxbugs,
3590 \begin_layout Itemize
3591 otherwise, add a pattern here.
3595 \begin_layout Description
3596 attic Documents in the attic (kept for reference and format conversion test).
3598 \begin_inset Quotes eld
3602 \begin_inset Quotes erd
3608 \begin_layout Subparagraph
3612 \begin_layout Standard
3613 Test cases whose name additionally matches a pattern in the file
3614 \begin_inset Flex Code
3617 \begin_layout Plain Layout
3618 development/autotests/suspendedTests
3636 This means they are not executed using
3637 \begin_inset Flex Code
3640 \begin_layout Plain Layout
3647 \begin_inset Flex Code
3650 \begin_layout Plain Layout
3657 However, they also get the test property
3658 \begin_inset Flex Code
3661 \begin_layout Plain Layout
3668 they are reported as failing if the export works without error.
3669 From time to time they still have to be checked using
3670 \begin_inset Flex Code
3673 \begin_layout Plain Layout
3682 \begin_layout Standard
3683 These tests are suspended, because the export fails for known reasons which
3684 cannot ATM be resolved.
3685 But it is expected the reason might disappear in the future.
3686 Be it new TL or better handling in \SpecialChar LyX
3690 \begin_layout Standard
3691 For ctest commands without the
3692 \begin_inset Flex Code
3695 \begin_layout Plain Layout
3701 parameter nothing changes.
3702 Suspended or not, tests will be executed depending only on the selecting
3703 regular expression given to the ctest command (see
3704 \begin_inset CommandInset ref
3706 reference "par:ctest-options"
3713 \begin_layout Paragraph
3714 \begin_inset CommandInset label
3716 name "par:Unreliable-tests"
3723 \begin_layout Standard
3724 Test cases whose name matches a pattern in the file
3725 \begin_inset Flex Code
3728 \begin_layout Plain Layout
3729 development/autotests/unreliableTests
3741 \begin_layout Standard
3742 These tests are not executed using
3743 \begin_inset Flex Code
3746 \begin_layout Plain Layout
3753 \begin_inset Flex Code
3756 \begin_layout Plain Layout
3766 \begin_layout Standard
3767 They pass or fail for various reasons not related to LyX (nonstandard, erratic)
3768 or pass but should rather fail (wrong output).
3770 \begin_inset Note Note
3773 \begin_layout Plain Layout
3774 *invalid* tests (wrong output) are not *unreliable*.
3775 # Use "unfit" or "unapplicable" as better label and name of pattern file?
3784 \begin_layout Standard
3785 The following sublabels are currently present in
3786 \begin_inset Flex Code
3789 \begin_layout Plain Layout
3798 \begin_layout Description
3799 nonstandard Documents with additional requirements, e.g.
3800 a class or package file not in TeXLive.
3802 \begin_inset Note Note
3805 \begin_layout Plain Layout
3807 \begin_inset Quotes eld
3811 \begin_inset Quotes erd
3815 \begin_inset Quotes eld
3819 \begin_inset Quotes erd
3830 \begin_layout Description
3831 erratic Tests depending on local configuration or the phase of the moon.
3835 \begin_layout Description
3836 varying_versions Tests depending on e.g.
3837 OS or version of a non-TeX-Live dependency.
3838 Note that a full, up-to-date TeX Live installation is required so this
3839 sublabel is about versions of other dependencies.
3842 \begin_layout Description
3844 \begin_inset space ~
3847 output Export does not fail but the resulting document has (undetected)
3852 \begin_layout Standard
3853 \paragraph_spacing single
3854 \begin_inset Note Note
3857 \begin_layout Plain Layout
3858 \paragraph_spacing single
3859 These tests are in a strict sense not unreliable but
3863 (not measuring what they should measure).
3872 \begin_layout Paragraph
3873 \begin_inset CommandInset label
3875 name "par:Export-test-filtering"
3879 Export test filtering
3882 \begin_layout Standard
3883 The assignment of a label to a test is controlled by a set of files with
3884 regular expressions that are matched against the test names.
3887 \begin_layout Description
3888 ignoredTests (small file)
3889 \begin_inset Newline newline
3892 Tests selected here are withdrawn in the configuration step (cf.
3894 \begin_inset CommandInset ref
3896 reference "par:Configuring-ctests"
3904 \begin_layout Labeling
3905 \labelwidthstring 00.00.0000
3906 Input Test of any export combination
3909 \begin_layout Labeling
3910 \labelwidthstring 00.00.0000
3911 Output Stop if tests not selected here
3915 \begin_layout Description
3916 unreliableTests: Tests selected pass or fail dependent on the system where
3918 Selected tests gain the label 'unreliable'.
3922 \begin_layout Labeling
3923 \labelwidthstring 00.00.0000
3924 Input Each test which passed 'ignoredTests'
3927 \begin_layout Labeling
3928 \labelwidthstring 00.00.0000
3929 Output Gain label 'unreliable', proceed with checking for 'inverted'.
3933 \begin_layout Description
3935 \begin_inset space \space{}
3942 \begin_layout Labeling
3943 \labelwidthstring 00.00.0000
3944 Input Each test which passed 'ignoredTests'
3947 \begin_layout Labeling
3948 \labelwidthstring 00.00.0000
3949 Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e.
3950 tests are reported as failing if the export works without error.) If no
3951 subselection applies, gain labels 'export' and 'inverted'.
3954 \begin_layout Standard
3955 The following filter perfoms a subselection of 'invertedTests':
3958 \begin_layout Description
3959 suspendedTests Tests selected here gain the label 'suspended' but _not_
3960 'export' or 'inverted', although in ctest they remain inverted.
3961 ('ctest' knows only 'inverted' or not, labels are used only for test selection)
3965 \begin_layout Labeling
3966 \labelwidthstring 00.00.0000
3967 Input Each test selected by 'invertedTests'
3970 \begin_layout Labeling
3971 \labelwidthstring 00.00.0000
3972 Output Selected test gains label 'suspended'.
3978 \begin_layout Standard
3979 The following table may clarify label assignement
3982 \begin_layout Standard
3983 \begin_inset space \hspace{}
3988 \begin_inset Tabular
3989 <lyxtabular version="3" rows="6" columns="8">
3990 <features tabularvalignment="middle">
3991 <column alignment="left" valignment="top" width="2cm">
3992 <column alignment="left" valignment="top" width="2.5cm">
3993 <column alignment="left" valignment="top" width="2cm">
3994 <column alignment="center" valignment="top" width="2.5cm">
3995 <column alignment="center" valignment="top">
3996 <column alignment="center" valignment="top">
3997 <column alignment="center" valignment="top">
3998 <column alignment="center" valignment="top">
4000 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4003 \begin_layout Plain Layout
4004 Test matching pattern in file:
4009 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4012 \begin_layout Plain Layout
4018 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4021 \begin_layout Plain Layout
4027 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4030 \begin_layout Plain Layout
4036 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4039 \begin_layout Plain Layout
4045 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4048 \begin_layout Plain Layout
4054 <cell multicolumn="2" alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4057 \begin_layout Plain Layout
4063 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4066 \begin_layout Plain Layout
4074 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4077 \begin_layout Plain Layout
4078 ignored\SpecialChar softhyphen
4084 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4087 \begin_layout Plain Layout
4088 unreliable\SpecialChar softhyphen
4094 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4097 \begin_layout Plain Layout
4098 inverted\SpecialChar softhyphen
4104 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4107 \begin_layout Plain Layout
4108 suspended\SpecialChar softhyphen
4114 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4117 \begin_layout Plain Layout
4123 <cell alignment="center" valignment="top" topline="true" usebox="none">
4126 \begin_layout Plain Layout
4132 <cell alignment="center" valignment="top" topline="true" usebox="none">
4135 \begin_layout Plain Layout
4141 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4144 \begin_layout Plain Layout
4152 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4155 \begin_layout Plain Layout
4161 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4164 \begin_layout Plain Layout
4170 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4173 \begin_layout Plain Layout
4179 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4182 \begin_layout Plain Layout
4188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4191 \begin_layout Plain Layout
4197 <cell alignment="center" valignment="top" topline="true" usebox="none">
4200 \begin_layout Plain Layout
4206 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4209 \begin_layout Plain Layout
4215 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4218 \begin_layout Plain Layout
4226 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4229 \begin_layout Plain Layout
4235 <cell multirow="3" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4238 \begin_layout Plain Layout
4240 \begin_inset Newline newline
4244 \begin_inset Newline newline
4252 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4255 \begin_layout Plain Layout
4261 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4264 \begin_layout Plain Layout
4270 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4273 \begin_layout Plain Layout
4279 <cell alignment="center" valignment="top" topline="true" usebox="none">
4282 \begin_layout Plain Layout
4288 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4291 \begin_layout Plain Layout
4297 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4300 \begin_layout Plain Layout
4308 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4311 \begin_layout Plain Layout
4317 <cell multirow="4" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4320 \begin_layout Plain Layout
4326 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4329 \begin_layout Plain Layout
4335 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4338 \begin_layout Plain Layout
4344 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4347 \begin_layout Plain Layout
4353 <cell alignment="center" valignment="top" topline="true" usebox="none">
4356 \begin_layout Plain Layout
4362 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4365 \begin_layout Plain Layout
4371 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4374 \begin_layout Plain Layout
4382 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4385 \begin_layout Plain Layout
4391 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4394 \begin_layout Plain Layout
4400 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4403 \begin_layout Plain Layout
4409 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4412 \begin_layout Plain Layout
4418 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4421 \begin_layout Plain Layout
4427 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4430 \begin_layout Plain Layout
4436 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4439 \begin_layout Plain Layout
4445 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4448 \begin_layout Plain Layout
4462 \begin_layout Standard
4463 \begin_inset Note Note
4466 \begin_layout Plain Layout
4468 \begin_inset Quotes eld
4472 \begin_inset Quotes erd
4475 filter, this would be far less complicated:
4478 \begin_layout Plain Layout
4479 \begin_inset Tabular
4480 <lyxtabular version="3" rows="6" columns="7">
4481 <features tabularvalignment="middle">
4482 <column alignment="left" valignment="top" width="0pt">
4483 <column alignment="left" valignment="top" width="0pt">
4484 <column alignment="left" valignment="top" width="0pt">
4485 <column alignment="center" valignment="top">
4486 <column alignment="center" valignment="top">
4487 <column alignment="center" valignment="top">
4488 <column alignment="center" valignment="top">
4490 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4493 \begin_layout Plain Layout
4494 Test matching pattern in file:
4499 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4502 \begin_layout Plain Layout
4508 <cell multicolumn="2" alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
4511 \begin_layout Plain Layout
4517 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4520 \begin_layout Plain Layout
4526 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4529 \begin_layout Plain Layout
4535 <cell multicolumn="2" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4538 \begin_layout Plain Layout
4544 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4547 \begin_layout Plain Layout
4555 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4558 \begin_layout Plain Layout
4564 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4567 \begin_layout Plain Layout
4573 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4576 \begin_layout Plain Layout
4582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4585 \begin_layout Plain Layout
4591 <cell alignment="center" valignment="top" topline="true" usebox="none">
4594 \begin_layout Plain Layout
4600 <cell alignment="center" valignment="top" topline="true" usebox="none">
4603 \begin_layout Plain Layout
4609 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4612 \begin_layout Plain Layout
4620 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4623 \begin_layout Plain Layout
4629 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4632 \begin_layout Plain Layout
4638 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4641 \begin_layout Plain Layout
4647 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4650 \begin_layout Plain Layout
4656 <cell alignment="center" valignment="top" topline="true" usebox="none">
4659 \begin_layout Plain Layout
4665 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4668 \begin_layout Plain Layout
4674 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4677 \begin_layout Plain Layout
4685 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4688 \begin_layout Plain Layout
4694 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4697 \begin_layout Plain Layout
4703 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4706 \begin_layout Plain Layout
4712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4715 \begin_layout Plain Layout
4721 <cell alignment="center" valignment="top" topline="true" usebox="none">
4724 \begin_layout Plain Layout
4730 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4733 \begin_layout Plain Layout
4739 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4742 \begin_layout Plain Layout
4750 <cell multirow="4" alignment="left" valignment="middle" topline="true" leftline="true" usebox="none">
4753 \begin_layout Plain Layout
4759 <cell multirow="3" alignment="left" valignment="middle" topline="true" bottomline="true" leftline="true" usebox="none">
4762 \begin_layout Plain Layout
4768 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4771 \begin_layout Plain Layout
4777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4780 \begin_layout Plain Layout
4786 <cell alignment="center" valignment="top" topline="true" usebox="none">
4789 \begin_layout Plain Layout
4795 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4798 \begin_layout Plain Layout
4804 <cell alignment="center" valignment="top" topline="true" rightline="true" usebox="none">
4807 \begin_layout Plain Layout
4815 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4818 \begin_layout Plain Layout
4824 <cell multirow="4" alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4827 \begin_layout Plain Layout
4833 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4836 \begin_layout Plain Layout
4842 <cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
4845 \begin_layout Plain Layout
4851 <cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
4854 \begin_layout Plain Layout
4860 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4863 \begin_layout Plain Layout
4869 <cell alignment="center" valignment="top" topline="true" bottomline="true" rightline="true" usebox="none">
4872 \begin_layout Plain Layout
4891 \begin_layout Subsubsection
4895 \begin_layout Standard
4896 These tests check whether a .lyx file loads without any terminal messages.
4897 They correspond to the manual operations of simply opening a .lyx file on
4898 the terminal, exiting LyX once the file is loaded, and then checking whether
4899 there is any output from the terminal.
4900 These tests are useful for catching malformed .lyx files and parsing bugs.
4901 They can also be used to find a .lyx file in which an instance of something
4903 To do this, compile LyX with a local patch that outputs something to the
4904 terminal when an instance is found, and then run the check_load tests to
4905 see if any fail, which would mean that the situation occurs in the LyX
4906 documentation files corresponding to the failed tests.
4907 These tests are expectedly fragile: any LyX diagnostic message, which is
4908 not necessarily an error, would cause the tests to fail.
4909 Similarly, any message output by a library (e.g.
4910 Qt) would also cause failure.
4911 There are some messages that the check_load tests are instructed to ignore,
4912 which are stored in the file
4913 \begin_inset Flex Code
4916 \begin_layout Plain Layout
4917 development/autotests/filterCheckWarnings
4925 \begin_layout Standard
4926 Under cmake, the tests are labeled as 'load'.
4929 \begin_layout Subsubsection
4933 \begin_layout Standard
4934 Automated tests based on the "MonKey Testing" keytest program are enabled
4935 if the necessary dependencies are found and if the CMake flag
4936 \begin_inset Flex Code
4939 \begin_layout Plain Layout
4940 -DLYX_ENABLE_KEYTESTS=ON
4946 They are documented in the README document in
4947 \begin_inset Flex Code
4950 \begin_layout Plain Layout
4951 development/autotests
4956 subfolder of the \SpecialChar LyX
4957 source code distribution.
4960 \begin_layout Subsubsection
4964 \begin_layout Standard
4965 These tests combine lyx2lyx tests with check_load tests.
4966 They fail if either fails.
4969 \begin_layout Subsubsection
4973 \begin_layout Standard
4974 The URL tests are enabled with the
4975 \begin_inset Flex Code
4978 \begin_layout Plain Layout
4979 -DLYX_ENABLE_URLTESTS=ON
4984 CMake flag and are useful for finding broken links in our documentation
4986 If a URL test fails, to see which link in particular was reported as broken,
4988 \begin_inset Flex Code
4991 \begin_layout Plain Layout
4998 These tests are extremely fragile (e.g.
4999 a test can depend on your Internet connection) and a failed URL test should
5000 not be taken too seriously.
5001 URL tests are labeled as
5006 \begin_layout Paragraph
5010 \begin_layout Standard
5011 cmake is required to run the \SpecialChar LyX
5012 tests, running them is not implemented for
5016 \begin_layout Standard
5017 The appropriate commands are:
5020 \begin_layout Itemize
5026 \begin_inset Newline newline
5029 runs all tests with label
5034 \begin_layout Itemize
5037 ctest -R 'check_.*urls'
5040 \begin_inset Newline newline
5043 runs the tests 'check_accessible_urls'
5046 \begin_layout Standard
5047 Associated test results can be examined in ctest-log directory in files
5048 of the form 'LastFailed.*URLS.log'
5051 \begin_layout Section
5052 Development policies
5055 \begin_layout Standard
5056 This chapter lists some guidelines that should be followed.
5057 This list is not complete, and many guidelines are in separate chapters,
5059 \begin_inset Quotes eld
5062 When is an update of the .lyx file format number needed?
5063 \begin_inset Quotes erd
5067 \begin_inset CommandInset ref
5069 reference "sec:When-is-an"
5076 \begin_layout Subsection
5077 When to set a fixed milestone?
5080 \begin_layout Standard
5081 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
5085 \begin_layout Enumerate
5086 Somebody is actively working on a fix.
5089 \begin_layout Enumerate
5090 The bug is so severe that it would block the release if it is not fixed.
5093 \begin_layout Standard
5094 If a bug is important, but nobody is working on it, and it is no showstopper,
5095 use a milestone like 2.1.x or 2.2.x.
5096 For all other bugs, do not set a milestone at all.
5099 \begin_layout Subsection
5100 Can we add rc entries in stable branch?
5103 \begin_layout Standard
5105 We are supposed to increase the prefs2prefs version number with such things.
5108 \begin_layout Section
5109 \begin_inset CommandInset label
5111 name "sec:Documentation-policies"
5115 Documentation policies
5118 \begin_layout Subsection
5122 \begin_layout Standard
5124 \begin_inset space ~
5127 rules in editing the docs:
5130 \begin_layout Enumerate
5131 \begin_inset CommandInset label
5133 name "enu:If-you-are"
5137 If you are not the maintainer of a doc file or a chapter/section, you MUST
5138 use change tracking so that the maintainer could review your changes
5141 \begin_layout Enumerate
5142 Respect the formatting of the document.
5143 The different files use different formatting styles.
5144 That is OK and has historic reasons nobody fully knows ;-).
5145 But it is important to be consistent within one file.
5148 \begin_layout Enumerate
5149 All changes you make to a file in one language MUST also go the file in
5150 the other actively maintained languages.
5151 Normally the maintainer does this for you, if you are the maintainer, you
5152 must do this by copying or changing the changed or added text to the other
5153 files so that the translators sees the blue underlined text and know what
5154 they have to translate and what was changed.
5157 \begin_layout Enumerate
5158 You MUST assure that the document is compilable as
5159 \begin_inset Quotes eld
5163 \begin_inset Quotes erd
5166 or the document's default output format after your changes.
5169 \begin_layout Enumerate
5170 All fixes (typos, compilation fixes, updates info etc.) go at first into
5171 the current GIT branch because the user should benefit from all fixes with
5172 every minor release.
5173 Feel free to commit directly to branch as long as you follow rule
5174 \begin_inset space ~
5178 \begin_inset CommandInset ref
5180 reference "enu:If-you-are"
5185 You can immediately commit to master as well.
5188 \begin_layout Enumerate
5189 \begin_inset CommandInset label
5191 name "enu:The-fileformat-of"
5195 The fileformat of a file must not be changed unless you document a new feature
5196 in LyX that requires a new fileformat.
5197 The reason for this rule is to keep it easy for the doc maintainers to
5198 port/backport changes to from master/branch.
5201 \begin_layout Standard
5202 The main documentation consists of these files:
5205 \begin_layout Description
5206 Welcome.lyx it is the first file you see after an installation.
5207 We assume that a new user sees this.
5208 It is therefore designed to be as simple as possible.
5209 Therefore please don't add any new formatting, only fix typos etc.
5210 Welcome.lyx is up to date for \SpecialChar LyX
5211 2.1.x, currently maintained by Uwe Stöhr.
5214 \begin_layout Description
5215 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
5217 It therefore uses a limited set of formatting.
5218 For example a standard document class.
5219 Since new users will first learn about the formatting possibilities of
5221 please keep this file that simple.
5222 Intro.lyx is up to date for \SpecialChar LyX
5223 2.1.x, currently maintained by Uwe Stöhr.
5226 \begin_layout Description
5227 Tutorial.lyx our tutorial.
5228 It must be always up to date.
5229 Normally there is nothing to add since we don't want to overwhelm new users
5230 with too much details.
5231 The will learn these details while using \SpecialChar LyX
5232 and we have special manuals.
5233 Tutorial.lyx is up to date for \SpecialChar LyX
5234 2.1.x, currently maintained by Uwe Stöhr.
5237 \begin_layout Description
5238 UserGuide.lyx our main user guide.
5239 It covers a mixture of basic and detailed information.
5240 Some information is also in the Math and EmbeddedObjects manual so that
5241 the UserGuide refers to these files.
5242 UserGuide.lyx is up to date for \SpecialChar LyX
5243 2.1.x, currently maintained by Uwe Stöhr.
5246 \begin_layout Description
5247 EmbeddedObjects.lyx a special manual to explain things like tables floats
5250 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
5251 2.1.x, currently maintained by Uwe
5255 \begin_layout Description
5256 Math.lyx a special manual to explain everything regarding math in all detail.
5257 Math.lyx is up to date for \SpecialChar LyX
5258 2.1.x, currently maintained by Uwe Stöhr.
5261 \begin_layout Description
5262 Additional.lyx this manual covers information that would be too much detail
5263 for the UserGuide or would make the UserGuide uncompilable or only compilable
5264 when installing a lot of special \SpecialChar LaTeX
5266 What should be in the UserGuide or better in Additional is a matter of
5268 it is up to you to decide that.
5269 Additional.lyx is not completely up to date for \SpecialChar LyX
5272 \begin_inset space ~
5275 8 is up to date and currently maintained by Uwe Stöhr.
5276 It certainly needs a rewrite and update.
5277 For example many info in chapter
5278 \begin_inset space ~
5281 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
5285 \begin_layout Description
5286 Customization.lyx this manual covers information how to customize \SpecialChar LyX
5288 output formats, operating systems, languages etc.
5289 It is currently completely out of date and needs a major rewrite and update.
5290 If you do this please assure that your information are given for all OSes
5291 and \SpecialChar LaTeX
5292 distributions (meaning be as objective as possible).