1 #LyX 2.2 created this file. For more info see http://www.lyx.org/
5 \origin /systemlyxdir/doc/
7 \options BCOR8mm,captions=tableheading
8 \use_default_options false
12 \maintain_unincluded_children false
15 InsetLayout CharStyle:MenuItem
24 \newcommand*{\menuitem}[1]{{\sffamily #1}}
29 \language_package default
32 \font_roman "lmodern" "default"
33 \font_sans "lmss" "default"
34 \font_typewriter "lmtt" "default"
35 \font_math "auto" "auto"
36 \font_default_family default
37 \use_non_tex_fonts false
40 \font_sf_scale 100 100
41 \font_tt_scale 100 100
43 \default_output_format default
45 \bibtex_command default
46 \index_command default
50 \pdf_title "LyX's Development manual"
51 \pdf_author "LyX Team"
52 \pdf_subject "LyX's development documentation"
53 \pdf_keywords "LyX, Documentation, Development"
55 \pdf_bookmarksnumbered true
56 \pdf_bookmarksopen true
57 \pdf_bookmarksopenlevel 1
62 \pdf_pdfusetitle false
63 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
66 \use_package amsmath 1
67 \use_package amssymb 1
70 \use_package mathdots 1
71 \use_package mathtools 0
73 \use_package stackrel 0
74 \use_package stmaryrd 0
75 \use_package undertilde 0
77 \cite_engine_type default
81 \paperorientation portrait
85 \notefontcolor #0000ff
92 \paragraph_separation indent
93 \paragraph_indentation default
94 \quotes_language english
97 \paperpagestyle headings
98 \tracking_changes false
108 Developing \SpecialChar LyX
112 \begin_layout Subtitle
117 by the \SpecialChar LyX
122 \begin_layout Plain Layout
124 If you have comments or error corrections, please send them to the \SpecialChar LyX
127 \begin_inset Flex Code
130 \begin_layout Plain Layout
132 <lyx-docs@lists.lyx.org>
145 \begin_layout Standard
146 \begin_inset CommandInset toc
147 LatexCommand tableofcontents
154 \begin_layout Section
158 \begin_layout Standard
159 This manual documents some aspects of \SpecialChar LyX
161 It is currently rather incomplete, but will hopefully be extended in the
163 Meanwhile, additional information can be found in the
164 \begin_inset Flex Code
167 \begin_layout Plain Layout
173 subfolder of the \SpecialChar LyX
174 source code distribution.
175 This document is not translated, since the development language of \SpecialChar LyX
178 If you want to use \SpecialChar LyX
179 you don't need to read this manual.
180 However, if you want to learn more about how \SpecialChar LyX
181 is developed, or even want
182 to participate in \SpecialChar LyX
183 development, you may find some interesting information.
186 \begin_layout Section
190 \begin_layout Standard
192 uses several custom file formats for configuration files and documents.
193 This chapter contains some background concerning these file formats.
194 Several file formats are also described in detail in the regular user documenta
198 \begin_layout Subsection
202 \begin_layout Subsection
203 When is an update of the .lyx file format number needed?
204 \begin_inset CommandInset label
206 name "sec:When-is-an"
213 \begin_layout Standard
214 When you are working on a new feature you may ask yourself whether it needs
215 an update of the .lyx file format number.
216 Whether an update is needed or not is not always obvious.
217 Below you can find a list of reasons for file format updates with explanations:
220 \begin_layout Description
229 setting Whenever you introduce a new setting that is stored in the document
230 header, a file format update is needed.
231 This is also true if you add a new valid value to an existing setting,
233 \begin_inset space \thinspace{}
237 \begin_inset space \space{}
240 a new language that is stored in
241 \begin_inset Flex Code
244 \begin_layout Plain Layout
255 \begin_layout Description
264 setting If a certain setting becomes obsolete and gets removed, a file format
268 \begin_layout Description
273 inset Of course a new inset requires a file format update.
276 \begin_layout Description
281 style in any layout file or module shipped with \SpecialChar LyX
282 , or new shipped layout
284 These requirements are currently under discussion and might change in the
288 \begin_layout Description
301 package Any new math package that is automatically loaded needs a file format
303 The reason for this is that there is no true ERT inset for math formulas:
304 Each command is parsed, and if a user happens to defne a local command
305 with the same name as a command that triggers an automatic load of a package,
306 he needs to be able to switch off the automatic loading of that package.
307 This switch is stored by the
308 \begin_inset Flex Code
311 \begin_layout Plain Layout
320 \begin_layout Standard
321 If you are still unsure, please ask on the development list.
324 \begin_layout Subsection
325 How to update the file format number of .lyx files
326 \begin_inset CommandInset label
328 name "subsec:update_lyx_files"
335 \begin_layout Standard
336 Once you came to the conclusion that a file format update is needed you
337 should use the following procedure to perform the update:
340 \begin_layout Enumerate
341 Implement and test the new feature, including the reading and writing of
343 Note that any file produced at this stage does not use a valid format,
344 so do not use this version of \SpecialChar LyX
345 for working on any important documents.
348 \begin_layout Enumerate
349 Describe the new format in
350 \begin_inset Flex Code
353 \begin_layout Plain Layout
362 \begin_layout Enumerate
363 Update the \SpecialChar LyX
364 file format number in
365 \begin_inset Flex Code
368 \begin_layout Plain Layout
377 \begin_layout Enumerate
378 Update the range of file formats in the array
379 \begin_inset Flex Code
382 \begin_layout Plain Layout
389 \begin_inset Flex Code
392 \begin_layout Plain Layout
401 \begin_layout Enumerate
402 Add an entry to both format lists (for conversion and reversion) in
403 \begin_inset Newline newline
407 \begin_inset Flex Code
410 \begin_layout Plain Layout
411 lib/lyx2lyx/lyx_2_2.py
417 Add a conversion routine if needed (e.
418 \begin_inset space \thinspace{}
422 \begin_inset space \space{}
425 a new header setting always needs a conversion that adds the new setting,
426 a new document language does not need one).
427 Add a reversion routine if needed.
428 While the conversion routine is required to produce a document that is
429 equivalent to the old version, the requirements of the reversion are not
431 If possible, try to produce a proper reversion, using ERT if needed, but
432 for some features this might be too complicated.
433 In this case, the minimum requirement of the reversion routine is that
434 it produces a valid document which can be read by an older \SpecialChar LyX
436 If absolutely needed, even data loss is allowed for the reversion.
439 \begin_layout Enumerate
440 Since tex2lyx has several implicit file format dependencies caused by sharing
441 code with \SpecialChar LyX
442 , updating the file format of .lyx files produced by tex2lyx at
443 the same time as updating the main .lyx file format is strongly recommended.
444 Therefore, a compiler warning will be issued if the \SpecialChar LyX
445 and tex2lyx .lyx file
446 format numbers differ.
447 In many cases the tex2lyx update requires only the first and last item
449 \begin_inset Separator parbreak
456 \begin_layout Enumerate
457 Update the tex2lyx file format number in
458 \begin_inset Flex Code
461 \begin_layout Plain Layout
470 \begin_layout Enumerate
471 If the lyx2lyx conversion from the old to the new format is empty, or if
472 tex2lyx does not yet output the changed feature, you do not need any further
474 Otherwise, search for the changed feature in tex2lyx, and adjust the output
475 according to the lyx2lyx changes.
478 \begin_layout Enumerate
479 Update the tex2lyx test references as described in
480 \begin_inset CommandInset ref
481 LatexCommand formatted
482 reference "sec:Updating-test-references"
490 \begin_layout Enumerate
491 If you did not implement full tex2lyx support of the new feature, add a
493 \begin_inset Flex Code
496 \begin_layout Plain Layout
502 describing the missing bits.
503 Note that it is perfectly fine if you do not add full tex2lyx support for
504 a new feature: The updating recommendation above is only issued for the
505 syntax of the produced .lyx file.
506 It is no problem if some features supported by \SpecialChar LyX
507 are still output as ERT
508 by tex2lyx, since the problems in the past that resulted in the update
509 recommendation were related to mixed version syntax, not ERT.
512 \begin_layout Enumerate
513 It would be nice if you could create a .lyx test file which contains instances
514 of all changed or added features.
515 This could then be used to test lyx2lyx and tex2lyx.
516 Unfortunately it has not yet been decided how to collect such examples,
517 so please ask on the development list if you want to create one.
520 \begin_layout Enumerate
521 \begin_inset CommandInset label
523 name "enu:updatefiles"
527 Update LyX's .lyx documentation files to the new format.
528 The developer who makes the change knows best what changes to expect when
529 inspecting the resulting diff.
530 Because of this, you might be able to catch a bug in the lyx2lyx code that
531 updates the format just by taking a quick scan through the large diff that
533 \begin_inset Note Note
536 \begin_layout Plain Layout
537 Another advantage is that if later we suspect a bug in lyx2lyx we can easily
538 see which layout update made an unexpected change by looking at the git
539 log of a .lyx file that suffers the problem.
545 To do this, first make sure that there are no changes to the git repository
546 that you will not want to commit (this is needed because it will be convenient
547 to commit with the command
548 \begin_inset Flex Code
551 \begin_layout Plain Layout
558 Then run the following command in the root folder of the source:
559 \begin_inset Flex Code
562 \begin_layout Plain Layout
563 python development/tools/updatedocs.py
569 Then, revert the change to
570 \begin_inset Flex Code
573 \begin_layout Plain Layout
579 because that file is meant to be generated separately:
580 \begin_inset Flex Code
583 \begin_layout Plain Layout
584 git checkout lib/doc/LFUNs.lyx
590 \begin_inset Note Note
593 \begin_layout Plain Layout
594 TODO: this step should be done within updatedocs.py
600 Look at the resulting changes using the command
601 \begin_inset Flex Code
604 \begin_layout Plain Layout
611 If anything looks surprising, please investigate.
612 Finally, commit using
613 \begin_inset Flex Code
616 \begin_layout Plain Layout
625 \begin_layout Subsection
626 Updating the file format number of layout files
629 \begin_layout Standard
631 \begin_inset CommandInset ref
633 reference "enu:updatefiles"
638 \begin_inset CommandInset ref
640 reference "subsec:update_lyx_files"
645 \begin_inset Flex Code
648 \begin_layout Plain Layout
654 command, use this command:
655 \begin_inset Flex Code
658 \begin_layout Plain Layout
659 python development/tools/updatelayouts.py
667 \begin_layout Subsection
668 Updating the file format number of bind/ui files
671 \begin_layout Standard
673 \begin_inset CommandInset ref
675 reference "enu:updatefiles"
680 \begin_inset CommandInset ref
682 reference "subsec:update_lyx_files"
687 \begin_inset Flex Code
690 \begin_layout Plain Layout
696 command, use this command:
697 \begin_inset Flex Code
700 \begin_layout Plain Layout
701 bash development/tools/updatelfuns.sh
709 \begin_layout Subsection
710 Backporting new styles to the stable version
713 \begin_layout Standard
714 Starting with the stable \SpecialChar LyX
715 2.1 branch, there is a mechanism in place to backport
716 new styles to the stable version without the need to update the file format.
717 The basic idea is that the new style definition is automatically copied
718 to the document preamble, so that it can even be used by older minor revisions
719 that did not yet include the style.
720 To backport a new style to the stable version, the following steps are
724 \begin_layout Enumerate
726 \begin_inset Flex Code
729 \begin_layout Plain Layout
735 to the style definition in the development version.
738 \begin_layout Enumerate
739 Copy the style definition to the stable version, but use
740 \begin_inset Flex Code
743 \begin_layout Plain Layout
750 If needed adjust the format to the one used by the stable version (see
751 the customization manual for details of the layout file format).
754 \begin_layout Enumerate
755 For each update of the style in a later stable version, increase the argument
757 \begin_inset Flex Code
760 \begin_layout Plain Layout
766 by one (in the stable version, the development version should not be touched).
769 \begin_layout Standard
770 For details about the
771 \begin_inset Flex Code
774 \begin_layout Plain Layout
780 flag see the customization manual.
782 \begin_inset Flex Code
785 \begin_layout Plain Layout
791 support is needed for backported styles: Since the style of the development
792 version has an infinite version number, it will always be used.
793 Furthermore, since its version number is less than one, the style will
794 not be written anymore to the document header for files saved by the new
798 \begin_layout Standard
799 \begin_inset Newpage newpage
805 \begin_layout Section
809 \begin_layout Standard
810 Automated tests are an important tool to detect bugs and regressions in
811 software development.
812 Some projects like gcc even require each bug fix to be accompanied by a
813 test case for the automatic test suite, that would detect this bug.
814 Testing interactive features automatically is of course very hard, but
815 core functionality like document import and export can be tested quite
816 easily, and some tests of this kind exist.
819 \begin_layout Subsection
824 \begin_layout Standard
825 Some tests are located in the
826 \begin_inset Flex Code
829 \begin_layout Plain Layout
830 development/autotests
835 subfolder of the \SpecialChar LyX
836 source code distribution.
839 \begin_layout Subsubsection
843 \begin_layout Standard
844 cmake is required to run the \SpecialChar LyX
845 tests, running them is not implemented for
848 tests can be run by the commands
849 \begin_inset Flex Code
852 \begin_layout Plain Layout
859 \begin_inset Flex Code
862 \begin_layout Plain Layout
868 (when using a make based build system and not MSVC) in the
869 \begin_inset Flex Code
872 \begin_layout Plain Layout
878 subfolder of the build directory.
881 \begin_layout Subsection
885 \begin_layout Standard
886 The tex2lyx tests are located in the
887 \begin_inset Flex Code
890 \begin_layout Plain Layout
896 subfolder of the \SpecialChar LyX
897 source code distribution.
898 The actual testing is performed by the simple python script
899 \begin_inset Flex Code
902 \begin_layout Plain Layout
903 src/tex2lyx/test/runtests.py
909 Each test consists of two files:
910 \begin_inset Flex Code
913 \begin_layout Plain Layout
919 contains the \SpecialChar LaTeX
920 code that should be tested.
922 \begin_inset Flex Code
925 \begin_layout Plain Layout
931 contains the expected output of tex2lyx.
932 When a test is run, the actual produced output is compared with the stored
934 The test passes if both are identical.
935 The test machinery is also able to generate a file
936 \begin_inset Flex Code
939 \begin_layout Plain Layout
945 by exporting the produced .lyx file with \SpecialChar LyX
947 This may be useful for roundtrip comparisons.
950 \begin_layout Subsubsection
954 \begin_layout Standard
955 The tex2lyx tests can be run in several ways.
957 \begin_inset Flex Code
960 \begin_layout Plain Layout
966 subfolder of the build directory, the commands
967 \begin_inset Flex Code
970 \begin_layout Plain Layout
976 (cmake, all platforms),
977 \begin_inset Flex Code
980 \begin_layout Plain Layout
986 (cmake, when using a make based build system and not MSVC) or
987 \begin_inset Flex Code
990 \begin_layout Plain Layout
996 (autotools) will run the tex2lyx tests.
997 Alternatively, in the root of the build directory, the command
998 \begin_inset Flex Code
1001 \begin_layout Plain Layout
1007 runs all tests whose names match the regex
1008 \begin_inset Quotes eld
1012 \begin_inset Quotes erd
1016 Another way to run the tex2lyx tests in the root build directory is to
1017 instead use the command
1018 \begin_inset Flex Code
1021 \begin_layout Plain Layout
1022 ctest -L '(cmplyx|roundtrip)'
1027 , which runs all tests categorized with the label
1028 \begin_inset Quotes eld
1032 \begin_inset Quotes erd
1036 \begin_inset Quotes eld
1040 \begin_inset Quotes erd
1044 If a test fails, the differences between the expected and actual results
1045 are output in unified diff format.
1048 \begin_layout Subsubsection
1049 Updating test references
1050 \begin_inset CommandInset label
1052 name "sec:Updating-test-references"
1059 \begin_layout Standard
1060 In some cases a changed tex2lyx output is not a test failure, but wanted,
1062 \begin_inset space \thinspace{}
1066 \begin_inset space \space{}
1069 if a tex2lyx bug was fixed, or a new feature was added.
1070 In these cases the stored references need to be updated.
1071 To do so if using autotools, call
1072 \begin_inset Flex Code
1075 \begin_layout Plain Layout
1082 \begin_inset Flex Code
1085 \begin_layout Plain Layout
1091 subdirectory of the build directory.
1092 If instead using CMake, call
1093 \begin_inset Flex Code
1096 \begin_layout Plain Layout
1097 make updatetex2lyxtests
1102 in the build directory or in the
1103 \begin_inset Flex Code
1106 \begin_layout Plain Layout
1112 subdirectory of the build directory.
1116 \begin_layout Plain Layout
1117 Note that this is a case where a make target in the build directory can
1118 affect the source directory, which might not be advisable.
1123 On Windows do the following:
1126 \begin_layout Itemize
1127 Assure that the path to the python.exe is in your system PATH variable.
1130 \begin_layout Itemize
1131 Double-click on the file
1132 \begin_inset Flex Code
1135 \begin_layout Plain Layout
1136 updatetex2lyxtests.vcxproj
1141 in the build directory or in the
1142 \begin_inset Flex Code
1145 \begin_layout Plain Layout
1151 subdirectory of your build directory.
1154 \begin_layout Itemize
1155 In the appearing MSVC program right-click on the project
1159 in the project explorer and chose
1166 \begin_layout Standard
1167 For convenience, these commands also produce re-exported roundtrip .lyx.tex
1169 Please examine the changed output carefully before committing the changed
1170 files to the repository: Since the test machinery does not do a roundtrip
1172 \begin_inset Formula $\Rightarrow$
1176 \begin_inset Formula $\Rightarrow$
1179 .tex, and does not compare the produced dvi or pdf output, it assumes that
1180 the stored .lyx reference produces correct output if processed by \SpecialChar LyX
1182 There is only one chance to detect wrong output: before committing a new
1184 Once it is committed, it is quite difficult to verify whether it is correct.
1187 \begin_layout Standard
1192 update the test references by opening them with \SpecialChar LyX
1193 or directly running lyx2lyx
1195 This would not work, since lyx2lyx and \SpecialChar LyX
1196 produce slightly different files
1197 regarding insignificant whitespace and line breaks.
1200 \begin_layout Subsubsection
1204 \begin_layout Standard
1205 In many cases tests for new features may be added to one of the existing
1206 test files, but sometimes this is not possible or not wanted.
1207 Then a new test file needs to be added:
1210 \begin_layout Enumerate
1212 \begin_inset Flex Code
1215 \begin_layout Plain Layout
1216 src/tex2lyx/test/<test name>.tex
1221 and run tex2lyx in roundtrip mode to produce the file
1222 \begin_inset Flex Code
1225 \begin_layout Plain Layout
1226 src/tex2lyx/test/<test name>.lyx.lyx
1232 This file will be the new reference.
1235 \begin_layout Enumerate
1236 Once you confirmed that the tex2lyx output is correct, add the new files
1237 to the corresponding lists in
1238 \begin_inset Flex Code
1241 \begin_layout Plain Layout
1242 src/tex2lyx/test/runtests.py
1248 \begin_inset Flex Code
1251 \begin_layout Plain Layout
1252 src/tex2lyx/Makefile.am
1258 \begin_inset Flex Code
1261 \begin_layout Plain Layout
1262 src/tex2lyx/test/CMakeLists.txt
1270 \begin_layout Enumerate
1271 Commit the changes to the repository, or send a patch to the development
1272 list and ask for committing if you do not have commit rights.
1275 \begin_layout Subsection
1276 Export tests (cmake only)
1279 \begin_layout Standard
1280 The export tests are integration tests.
1281 They take longer to run and are more likely to break than the tex2lyx tests.
1282 Nevertheless, they have caught many regressions and without a better alternativ
1283 e it is important to keep them up-to-date and understand how they work.
1286 \begin_layout Standard
1287 The export tests require the
1288 \begin_inset Flex Code
1291 \begin_layout Plain Layout
1297 command that comes with the
1298 \begin_inset Flex Code
1301 \begin_layout Plain Layout
1310 \begin_layout Subsubsection
1311 Expectations of LyX developers
1314 \begin_layout Standard
1315 Because the export tests are integration tests and take a long time to run,
1316 LyX developers are rarely expected to run all of the tests.
1317 Here are some good practices to follow by developers:
1320 \begin_layout Itemize
1321 When making a non-trivial change to a .layout file, run the export and layout
1322 tests corresponding with that .layout file.
1325 \begin_layout Itemize
1326 When making non-trivial changes to a .lyx file, run the export tests correspondin
1327 g to that .lyx file.
1330 \begin_layout Itemize
1331 When making non-trivial changes to LyX's LaTeX export code (e.g.
1332 touching the encoding code or package handling code that you expect will
1333 change the exported LaTeX in some way), consider running all of the export
1334 tests before and after your change.
1335 If there are differences, please reconcile these (i.e.
1336 fix the bug or fix the tests)
1341 Ask for help if you're not sure what to do or if you do not want to run
1342 the tests, post the patch on the list and others will run the tests.
1345 \begin_layout Itemize
1346 Understand how to interpret test failures.
1347 If your commit is found to have broken a test, you should be able to interpret
1348 the test results when made aware of them.
1350 \begin_inset CommandInset ref
1352 reference "subsec:Interpreting-export-tests"
1359 \begin_layout Subsubsection
1360 Configuring the tests
1363 \begin_layout Standard
1364 To enable these tests, add the
1365 \begin_inset Flex Code
1368 \begin_layout Plain Layout
1369 -DLYX_ENABLE_EXPORT_TESTS=ON
1378 \begin_layout Standard
1379 \begin_inset Flex Code
1382 \begin_layout Plain Layout
1383 cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
1391 \begin_layout Standard
1393 This flag will increase the time for the cmake command by several seconds,
1394 mainly because of the process of inverting tests (see Section
1395 \begin_inset CommandInset ref
1397 reference "subsec:Interpreting-export-tests"
1404 \begin_layout Subsubsection
1408 \begin_layout Standard
1409 To run all tests, in the build directory simply run the command
1410 \begin_inset Flex Code
1413 \begin_layout Plain Layout
1420 To run only some of the tests, use the command
1421 \begin_inset Flex Code
1424 \begin_layout Plain Layout
1431 \begin_inset Flex Code
1434 \begin_layout Plain Layout
1440 is a regular expression that matches test names.
1441 To run only the export tests, you can use
1442 \begin_inset Flex Code
1445 \begin_layout Plain Layout
1452 For the list of test categories available in addition to
1453 \begin_inset Quotes eld
1457 \begin_inset Quotes erd
1461 \begin_inset Flex Code
1464 \begin_layout Plain Layout
1465 ctest \SpecialChar nobreakdash
1466 \SpecialChar nobreakdash
1473 It is often useful to list the tests without running them (e.g.
1474 if you want to know how many tests there are or whether your
1475 \begin_inset Flex Code
1478 \begin_layout Plain Layout
1484 regular expression did what you expected).
1485 This can be done with the
1486 \begin_inset Flex Code
1489 \begin_layout Plain Layout
1496 \begin_inset Flex Code
1499 \begin_layout Plain Layout
1500 \SpecialChar nobreakdash
1501 \SpecialChar nobreakdash
1508 We are still working on getting the tests to run in parallel which is supported
1510 \begin_inset Flex Code
1513 \begin_layout Plain Layout
1520 \begin_inset Flex Code
1523 \begin_layout Plain Layout
1530 \begin_inset Flex Code
1533 \begin_layout Plain Layout
1534 \SpecialChar nobreakdash
1535 \SpecialChar nobreakdash
1542 However, when running the tests in parallel, sometimes tests fail that
1543 pass when run sequentially.
1544 A reasonable approach is to first run the tests in parallel and then run
1545 the failed tests sequentially.
1546 For example, to run 8 jobs at a time:
1549 \begin_layout Standard
1550 \begin_inset Flex Code
1553 \begin_layout Plain Layout
1562 \begin_layout Standard
1563 \begin_inset Flex Code
1566 \begin_layout Plain Layout
1567 ctest \SpecialChar nobreakdash
1568 \SpecialChar nobreakdash
1577 \begin_layout Standard
1579 Note that some tests cannot be run in parallel.
1580 These tests are marked in the code with the
1581 \begin_inset Flex Code
1584 \begin_layout Plain Layout
1594 \begin_layout Standard
1595 In some situations the option
1596 \begin_inset Flex Code
1599 \begin_layout Plain Layout
1600 \SpecialChar nobreakdash
1601 \SpecialChar nobreakdash
1608 There have been bugs in LyX and in LaTeX which cause compilation to hang,
1609 and without a timeout a test might never stop (in one case there was even
1611 If a test times out, the
1612 \begin_inset Flex Code
1615 \begin_layout Plain Layout
1621 command exits with error, but you can distinguish between a timed out test
1622 and a failed test in the output reported at the end of the
1623 \begin_inset Flex Code
1626 \begin_layout Plain Layout
1635 \begin_layout Standard
1637 \begin_inset Flex Code
1640 \begin_layout Plain Layout
1646 ) the full list of command line options.
1649 \begin_layout Subsubsection
1650 \begin_inset CommandInset label
1652 name "subsec:Interpreting-export-tests"
1656 Interpreting the export test results
1659 \begin_layout Standard
1660 A test can fail for several reasons, not all of them bad.
1663 \begin_layout Enumerate
1664 The .lyx file could have been added recently and some formats are not expected
1668 \begin_layout Enumerate
1669 A dependency is not met (e.g.
1670 the LaTeX class file).
1671 One hint that this is the case is that the corresponding
1672 \begin_inset Flex Code
1675 \begin_layout Plain Layout
1681 test will likely also fail.
1684 \begin_layout Enumerate
1685 An inverted test fails to fail (i.e.
1686 export that previously failed now works).
1689 \begin_layout Enumerate
1690 An external dependency was updated (e.g.
1694 \begin_layout Enumerate
1695 A recent code change introduced a bug.
1698 \begin_layout Enumerate
1699 \begin_inset CommandInset label
1705 A change in a document exposed a previously unknown bug or an incompatibility
1706 with an export format (e.g.
1710 \begin_layout Standard
1711 Because the .lyx files are exported in several formats, it is not surprising
1712 that many of the exports fail.
1713 This expectation of failure is addressed by
1714 \begin_inset Quotes eld
1718 \begin_inset Quotes erd
1721 the tests, that is, by marking the test as
1722 \begin_inset Quotes eld
1726 \begin_inset Quotes erd
1729 if the export exits with error and as
1730 \begin_inset Quotes eld
1734 \begin_inset Quotes erd
1737 if the export succeeds
1742 It follows that these expected failures will not show up as failed tests
1743 in the test results and thus will not pollute the
1744 \begin_inset Quotes eld
1748 \begin_inset Quotes erd
1752 If the export actually succeeds, then the test will fail.
1753 The purpose of this failure is to get your attention—something has changed,
1754 possibly for the better.
1757 \begin_layout Standard
1758 We try to document why a test is inverted or ignored.
1759 See the comment (prefixed with
1760 \begin_inset Flex Code
1763 \begin_layout Plain Layout
1769 ) above the block in which the test is listed as inverted or ignored in
1771 \begin_inset Flex Code
1774 \begin_layout Plain Layout
1775 development/autotests/revertedTests
1781 \begin_inset Flex Code
1784 \begin_layout Plain Layout
1785 development/autotests/ignoredTests
1791 It is possible that an export goes from succeeding to failing just because
1792 the document was changed and the document was never expected to work with
1793 a certain export format in the first case.
1794 Once this is confirmed to be the situation, the test can be inverted.
1797 \begin_layout Standard
1798 A good question is why do we enable the tests for non-default formats? The
1799 answer is that if a non-default route is broken it is often because a bug
1800 was introduced in LyX and not because a document-specific change was made
1801 that is not supported by the route.
1802 In other words, there is a high signal/noise ratio in the export tests
1803 for some non-default formats.
1807 \begin_layout Standard
1808 What action should you take if a test fails? First, check manually that
1809 when the compilation succeeded before the resulting PDF was good.
1810 In fact, sometimes it is an improvement when a test fails.
1811 If you check manually, it might be the case that the export was succeeding
1812 before but showing garbled text in a PDF output.
1813 Now it might fail with a clear message of "language xyz not supported".
1814 It is always good to check manually why something fails and if it passes
1815 if the PDF output is good.
1818 \begin_layout Standard
1819 Sometimes a test is fixed as side-effect of some change.
1820 We should uninvert a test (remove it from the
1821 \begin_inset Flex Code
1824 \begin_layout Plain Layout
1830 file) in order to preserve the fix.
1833 \begin_layout Standard
1834 When a test or several tests fail, consider checking the files in the
1835 \begin_inset Flex Code
1838 \begin_layout Plain Layout
1844 subdirectory of your build directory.
1845 In this subdirectory are three files: the file
1846 \begin_inset Flex Code
1849 \begin_layout Plain Layout
1855 simply lists the tests that failed on your last
1856 \begin_inset Flex Code
1859 \begin_layout Plain Layout
1866 \begin_inset Flex Code
1869 \begin_layout Plain Layout
1875 file contains the output from the tests (and often has details explaining
1876 why a test failed); and the
1877 \begin_inset Flex Code
1880 \begin_layout Plain Layout
1886 file lists the times that it took to run the tests.
1889 \begin_layout Subsubsection
1893 \begin_layout Standard
1894 These tests are expected to always fail.
1897 \begin_layout Description
1898 reverted These tests are expected to fail, but are subject to be examined.
1899 It is expected that they will pass in a foreseeable future.
1900 They are labeled 'reverted'.
1903 \begin_layout Description
1904 suspended Some inverted tests are labeled 'suspended'.
1905 This means, they are not executed using
1906 \begin_inset Flex Code
1909 \begin_layout Plain Layout
1916 \begin_inset Flex Code
1919 \begin_layout Plain Layout
1926 From time to time they still have to be checked using
1927 \begin_inset Flex Code
1930 \begin_layout Plain Layout
1940 \begin_layout Standard
1941 These tests are suspended, because they fail for known reasons which cannot
1943 But it is expected the reason might disappear in the future.
1944 Be it new TL or better handling in \SpecialChar LyX
1948 \begin_layout Standard
1949 For ctest commands without the
1950 \begin_inset Flex Code
1953 \begin_layout Plain Layout
1959 parameter nothing changes.
1960 Suspended or not, tests will be executed depending only on the regexes
1961 parameters given to the ctest command.
1965 \begin_layout Subsubsection
1969 \begin_layout Description
1970 nonstandard Requires non-standard ressources (LaTeX packages and document
1971 classes, fonts, ...) that are not a requirement for running this test suite.
1975 \begin_layout Standard
1976 These tests are labeled as
1982 \begin_layout Description
1984 \begin_inset Quotes eld
1988 \begin_inset Quotes erd
1991 result, depending on local configuration, OS, TeX distribution, package
1992 versions, or the phase of the moon.
1996 \begin_layout Standard
1997 These tests are labeled as
2003 \begin_layout Subsection
2007 \begin_layout Standard
2008 These tests check whether a .lyx file loads without any terminal messages.
2009 They correspond to the manual operations of simply opening a .lyx file on
2010 the terminal, exiting LyX once the file is loaded, and then checking whether
2011 there is any output from the terminal.
2012 These tests are useful for catching malformed .lyx files and parsing bugs.
2013 They can also be used to find a .lyx file in which an instance of something
2015 To do this, compile LyX with a local patch that outputs something to the
2016 terminal when an instance is found, and then run the check_load tests to
2017 see if any fail, which would mean that the situation occurs in the LyX
2018 documentation files corresponding to the failed tests.
2019 These tests are expectedly fragile: any LyX diagnostic message, which is
2020 not necessarily an error, would cause the tests to fail.
2021 Similarly, any message output by a library (e.g.
2022 Qt) would also cause failure.
2023 There are some messages that the check_load tests are instructed to ignore,
2024 which are stored in the file
2025 \begin_inset Flex Code
2028 \begin_layout Plain Layout
2029 development/autotests/filterCheckWarnings
2037 \begin_layout Standard
2038 Under cmake, the tests are labeled as 'load'.
2041 \begin_layout Subsection
2042 URL tests (cmake only)
2045 \begin_layout Standard
2046 The URL tests are enabled with the
2047 \begin_inset Flex Code
2050 \begin_layout Plain Layout
2051 -DLYX_ENABLE_URLTESTS=ON
2056 CMake flag and are useful for finding broken links in our documentation
2058 If a URL test fails, to see which link in particular was reported as broken,
2060 \begin_inset Flex Code
2063 \begin_layout Plain Layout
2070 These tests are extremely fragile (e.g.
2071 a test can depend on your Internet connection) and a failed URL test should
2072 not be taken too seriously.
2073 URL tests are labeled as
2078 \begin_layout Subsubsection
2082 \begin_layout Standard
2083 cmake is required to run the \SpecialChar LyX
2084 tests, running them is not implemented for
2088 \begin_layout Standard
2089 The appropriate commands are:
2092 \begin_layout Itemize
2098 \begin_inset Newline newline
2101 runns all tests with label
2106 \begin_layout Itemize
2109 ctest -R 'check_.*urls'
2112 \begin_inset Newline newline
2115 runns the tests 'check_accessible_urls'
2118 \begin_layout Standard
2119 Associated test results can be examined in ctest-log directory in files
2120 of the form 'LastFailed.*URLS.log'
2123 \begin_layout Subsection
2124 Test labels (cmake only)
2127 \begin_layout Standard
2128 ctest label commands:
2131 \begin_layout Description
2132 \SpecialChar nobreakdash
2133 \SpecialChar nobreakdash
2134 print-labels shows all assigned labels
2137 \begin_layout Description
2138 \SpecialChar nobreakdash
2140 \begin_inset space ~
2143 labelname executes all tests to which this label is asigned to.
2144 A test may have more that one label.
2147 \begin_layout Description
2148 \SpecialChar nobreakdash
2150 \begin_inset space ~
2153 number executes tests in parallel using 'number' simultaneously processes.
2154 Some tests are marked as 'sequencial', for them this parameter has no effect.
2157 \begin_layout Section
2158 Development policies
2161 \begin_layout Standard
2162 This chapter lists some guidelines that should be followed.
2163 This list is not complete, and many guidelines are in separate chapters,
2165 \begin_inset Quotes eld
2168 When is an update of the .lyx file format number needed?
2169 \begin_inset Quotes erd
2173 \begin_inset CommandInset ref
2175 reference "sec:When-is-an"
2182 \begin_layout Subsection
2183 When to set a fixed milestone?
2186 \begin_layout Standard
2187 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
2191 \begin_layout Enumerate
2192 Somebody is actively working on a fix.
2195 \begin_layout Enumerate
2196 The bug is so severe that it would block the release if it is not fixed.
2199 \begin_layout Standard
2200 If a bug is important, but nobody is working on it, and it is no showstopper,
2201 use a milestone like 2.1.x or 2.2.x.
2202 For all other bugs, do not set a milestone at all.
2205 \begin_layout Subsection
2206 Can we add rc entries in stable branch?
2209 \begin_layout Standard
2211 We are supposed to increase the prefs2prefs version number with such things.
2214 \begin_layout Section
2215 Documentation policies
2218 \begin_layout Standard
2219 The main documentation consists of these files:
2222 \begin_layout Description
2223 splash.lyx it is the first file you see after an installation.
2224 We assume that a new user sees this.
2225 It is therefore designed to be as simple as possible.
2226 Therefore please don't add any new formatting, only fix typos etc.
2227 Splash.lyx is up to date for \SpecialChar LyX
2228 2.1.x, currently maintained by Uwe Stöhr.
2231 \begin_layout Description
2232 Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
2234 It therefore uses a limited set of formatting.
2235 For example a standard document class.
2236 Since new users will first learn about the formatting possibilities of
2238 please keep this file that simple.
2239 Intro.lyx is up to date for \SpecialChar LyX
2240 2.1.x, currently maintained by Uwe Stöhr.
2243 \begin_layout Description
2244 Tutorial.lyx our tutorial.
2245 It must be always up to date.
2246 Normally there is nothing to add since we don't want to overwhelm new users
2247 with too much details.
2248 The will learn these details while using \SpecialChar LyX
2249 and we have special manuals.
2250 Tutorial.lyx is up to date for \SpecialChar LyX
2251 2.1.x, currently maintained by Uwe Stöhr.
2254 \begin_layout Description
2255 UserGuide.lyx our main user guide.
2256 It covers a mixture of basic and detailed information.
2257 Some information is also in the Math and EmbeddedObjects manual so that
2258 the UserGuide refers to these files.
2259 UserGuide.lyx is up to date for \SpecialChar LyX
2260 2.1.x, currently maintained by Uwe Stöhr.
2263 \begin_layout Description
2264 EmbeddedObjects.lyx a special manual to explain things like tables floats
2267 EmbeddedObjects.lyx is up to date for \SpecialChar LyX
2268 2.1.x, currently maintained by Uwe
2272 \begin_layout Description
2273 Math.lyx a special manual to explain everything regarding math in all detail.
2274 Math.lyx is up to date for \SpecialChar LyX
2275 2.1.x, currently maintained by Uwe Stöhr.
2278 \begin_layout Description
2279 Additional.lyx this manual covers information that would be too much detail
2280 for the UserGuide or would make the UserGuide uncompilable or only compilable
2281 when installing a lot of special \SpecialChar LaTeX
2283 What should be in the UserGuide or better in Additional is a matter of
2285 it is up to you to decide that.
2286 Additional.lyx is not completely up to date for \SpecialChar LyX
2289 \begin_inset space ~
2292 8 is up to date and currently maintained by Uwe Stöhr.
2293 It certainly needs a rewrite and update.
2294 For example many info in chapter
2295 \begin_inset space ~
2298 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
2302 \begin_layout Description
2303 Customization.lyx this manual covers information how to customize \SpecialChar LyX
2305 output formats, operating systems, languages etc.
2306 It is currently completely out of date and needs a major rewrite and update.
2307 If you do this please assure that your information are given for all OSes
2308 and \SpecialChar LaTeX
2309 distributions (meaning be as objective as possible).
2312 \begin_layout Standard
2314 \begin_inset space ~
2317 rules in editing the docs:
2320 \begin_layout Enumerate
2321 If you are not the maintainer of a doc file or a chapter/section, you MUST
2322 use change tracking so that the maintainer could review your changes
2325 \begin_layout Enumerate
2326 Respect the formatting of the document.
2327 The different files use different formatting styles.
2328 That is OK and has historic reasons nobody fully know ;-).
2329 But it is important to be consistent within one file.
2332 \begin_layout Enumerate
2333 All changes you make to a file in one language MUST also go the file in
2334 the other actively maintained languages.
2335 Normally the maintainer does this for you, if you are the maintainer, you
2336 must do this by copying or changing the changed or added text to the other
2337 files so that the translators sees the blue underlined text and know what
2338 they have to translate and what was changed.
2341 \begin_layout Enumerate
2342 You MUST assure that the document is compilable as
2343 \begin_inset Quotes eld
2347 \begin_inset Quotes erd