-#LyX 2.1 created this file. For more info see http://www.lyx.org/
-\lyxformat 474
+#LyX 2.2 created this file. For more info see http://www.lyx.org/
+\lyxformat 501
\begin_document
\begin_header
-\textclass scrbook
-\options fleqn,bibliography=totoc,index=totoc,BCOR7.5mm,titlepage,captions=tableheading
+\origin /systemlyxdir/doc/
+\textclass scrartcl
+\options BCOR8mm,captions=tableheading
\use_default_options false
\begin_modules
logicalmkup
-theorems-ams
-theorems-ams-extended
-multicol
-shapepar
\end_modules
\maintain_unincluded_children false
\begin_local_layout
\language_package default
\inputencoding auto
\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_math auto
+\font_roman "lmodern" "default"
+\font_sans "lmss" "default"
+\font_typewriter "lmtt" "default"
+\font_math "auto" "auto"
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
+\font_sf_scale 100 100
+\font_tt_scale 100 100
\graphics default
\default_output_format default
\output_sync 0
\begin_body
\begin_layout Title
-Developing LyX
+Developing \SpecialChar LyX
+
\end_layout
\begin_layout Subtitle
\end_layout
\begin_layout Author
-by the LyX Team
+by the \SpecialChar LyX
+ Team
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
\noindent
-If you have comments or error corrections, please send them to the LyX Documenta
-tion mailing list,
+If you have comments or error corrections, please send them to the \SpecialChar LyX
+ Documentatio
+n mailing list,
\begin_inset Flex Code
status collapsed
\end_layout
-\begin_layout Chapter
+\begin_layout Section
Introduction
\end_layout
\begin_layout Standard
-This manual documents some aspects of LyX development.
+This manual documents some aspects of \SpecialChar LyX
+ development.
It is currently rather incomplete, but will hopefully be extended in the
future.
Meanwhile, additional information can be found in the
\end_inset
- subfolder of the LyX source code distribution.
- This document is not translated, since the development language of LyX
- is english.
- If you want to use LyX you don't need to read this manual.
- However, if you want to learn more about how LyX is developed, or even
- want to participate in LyX development, you may find some interesting informati
-on.
+ subfolder of the \SpecialChar LyX
+ source code distribution.
+ This document is not translated, since the development language of \SpecialChar LyX
+ is
+ english.
+ If you want to use \SpecialChar LyX
+ you don't need to read this manual.
+ However, if you want to learn more about how \SpecialChar LyX
+ is developed, or even want
+ to participate in \SpecialChar LyX
+ development, you may find some interesting information.
\end_layout
-\begin_layout Chapter
+\begin_layout Section
File formats
\end_layout
\begin_layout Standard
-LyX uses several custom file formats for configuration files and documents.
+\SpecialChar LyX
+ uses several custom file formats for configuration files and documents.
This chapter contains some background concerning these file formats.
Several file formats are also described in detail in the regular user documenta
tion.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
File Format Numbers
\end_layout
-\begin_layout Section
+\begin_layout Subsection
When is an update of the .lyx file format number needed?
\begin_inset CommandInset label
LatexCommand label
\begin_inset space ~
\end_inset
-style in any layout file or module shipped with LyX, or new shipped layout
+style in any layout file or module shipped with \SpecialChar LyX
+, or new shipped layout
file or module.
These requirements are currently under discussion and might change in the
future.
If you are still unsure, please ask on the development list.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
How to update the file format number of .lyx files
\end_layout
Implement and test the new feature, including the reading and writing of
.lyx files.
Note that any file produced at this stage does not use a valid format,
- so do not use this version of LyX for working on any important documents.
+ so do not use this version of \SpecialChar LyX
+ for working on any important documents.
\end_layout
\begin_layout Enumerate
\end_layout
\begin_layout Enumerate
-Update the LyX file format number in
+Update the \SpecialChar LyX
+ file format number in
\begin_inset Flex Code
status collapsed
If possible, try to produce a proper reversion, using ERT if needed, but
for some features this might be too complicated.
In this case, the minimum requirement of the reversion routine is that
- it produces a valid document which can be read by an older LyX.
+ it produces a valid document which can be read by an older \SpecialChar LyX
+.
If absolutely needed, even data loss is allowed for the reversion.
\end_layout
\begin_layout Enumerate
Since tex2lyx has several implicit file format dependencies caused by sharing
- code with LyX, updating the file format of .lyx files produced by tex2lyx
- at the same time as updating the main .lyx file format is strongly recommended.
- Therefore, a compiler warning will be issued if the LyX and tex2lyx .lyx
- file format numbers differ.
+ code with \SpecialChar LyX
+, updating the file format of .lyx files produced by tex2lyx at
+ the same time as updating the main .lyx file format is strongly recommended.
+ Therefore, a compiler warning will be issued if the \SpecialChar LyX
+ and tex2lyx .lyx file
+ format numbers differ.
In many cases the tex2lyx update requires only the first and last item
of the list below:
+\begin_inset Separator parbreak
+\end_inset
+
+
\end_layout
\begin_deeper
Note that it is perfectly fine if you do not add full tex2lyx support for
a new feature: The updating recommendation above is only issued for the
syntax of the produced .lyx file.
- It is no problem if some features supported by LyX are still output as
- ERT by tex2lyx, since the problems in the past that resulted in the update
+ It is no problem if some features supported by \SpecialChar LyX
+ are still output as ERT
+ by tex2lyx, since the problems in the past that resulted in the update
recommendation were related to mixed version syntax, not ERT.
\end_layout
-\begin_layout Section
+\begin_layout Enumerate
+It would be nice if you could create a .lyx test file which contains instances
+ of all changed or added features.
+ This could then be used to test lyx2lyx and tex2lyx.
+ Unfortunately it has not yet been decided how to collect such examples,
+ so please ask on the development list if you want to create one.
+\end_layout
+
+\begin_layout Subsection
Backporting new styles to the stable version
\end_layout
\begin_layout Standard
-Starting with the stable LyX 2.1 branch, there is a mechanism in place to
- backport new styles to the stable version without the need to update the
- file format.
+Starting with the stable \SpecialChar LyX
+ 2.1 branch, there is a mechanism in place to backport
+ new styles to the stable version without the need to update the file format.
The basic idea is that the new style definition is automatically copied
to the document preamble, so that it can even be used by older minor revisions
that did not yet include the style.
version.
\end_layout
-\begin_layout Chapter
+\begin_layout Standard
+\begin_inset Newpage newpage
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
Tests
\end_layout
easily, and some tests of this kind exist.
\end_layout
-\begin_layout Section
-LyX tests
+\begin_layout Subsection
+\SpecialChar LyX
+ tests
\end_layout
\begin_layout Standard
\end_inset
- subfolder of the LyX source code distribution.
+ subfolder of the \SpecialChar LyX
+ source code distribution.
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Running the tests
\end_layout
\begin_layout Standard
-The LyX tests can be run by the commands
+cmake is required to run the \SpecialChar LyX
+ tests, running them is not implemented for
+ autotools.
+ The \SpecialChar LyX
+ tests can be run by the commands
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-make test
+ctest
\end_layout
\end_inset
- (cmake) in the
+ (all platforms) or
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-autotests
+make test
\end_layout
\end_inset
- subfolder of the build directory.
-\begin_inset Note Note
-status open
+ (when using a make based build system and not MSVC) in the
+\begin_inset Flex Code
+status collapsed
\begin_layout Plain Layout
-FIXME: Is this possible with autotools?
+autotests
\end_layout
\end_inset
-
+ subfolder of the build directory.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
tex2lyx tests
\end_layout
\end_inset
- subfolder of the LyX source code distribution.
+ subfolder of the \SpecialChar LyX
+ source code distribution.
The actual testing is performed by the simple python script
\begin_inset Flex Code
status collapsed
\end_inset
- contains the LaTeX code that should be tested.
+ contains the \SpecialChar LaTeX
+ code that should be tested.
\begin_inset Flex Code
status collapsed
\end_inset
- by exporting the produced .lyx file with LyX again.
+ by exporting the produced .lyx file with \SpecialChar LyX
+ again.
This may be useful for roundtrip comparisons.
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Running the tests
\end_layout
\begin_layout Standard
-The tex2lyx tests can be run by the commands
+The tex2lyx tests can be run in several ways.
+ When in the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+src/tex2lyx
+\end_layout
+
+\end_inset
+
+ subfolder of the build directory, the commands
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest
+\end_layout
+
+\end_inset
+
+ (cmake, all platforms),
\begin_inset Flex Code
status collapsed
\end_inset
- (cmake) or
+ (cmake, when using a make based build system and not MSVC) or
\begin_inset Flex Code
status collapsed
\end_inset
- (autotools) in the
+ (autotools) will run the tex2lyx tests.
+ Alternatively, in the root of the build directory, the command
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-src/tex2lyx
+ctest -R tex2lyx
\end_layout
\end_inset
- subfolder of the build directory.
+ runs all tests whose names match the regex
+\begin_inset Quotes eld
+\end_inset
+
+tex2lyx
+\begin_inset Quotes erd
+\end_inset
+
+.
+ Another way to run the tex2lyx tests in the root build directory is to
+ instead use the command
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -L '(cmplyx|roundtrip)'
+\end_layout
+
+\end_inset
+
+, which runs all tests categorized with the label
+\begin_inset Quotes eld
+\end_inset
+
+roundtrip
+\begin_inset Quotes erd
+\end_inset
+
+ or
+\begin_inset Quotes eld
+\end_inset
+
+cmplyx
+\begin_inset Quotes erd
+\end_inset
+
+.
If a test fails, the differences between the expected and actual results
are output in unified diff format.
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Updating test references
\begin_inset CommandInset label
LatexCommand label
\end_inset
- subdirectory of the build directory
+ subdirectory of the build directory.
\begin_inset Foot
status collapsed
\end_inset
+ On Windows do the following:
+\end_layout
+
+\begin_layout Itemize
+Assure that the path to the python.exe is in your system PATH variable.
+\end_layout
+
+\begin_layout Itemize
+Double-click on the file
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+updatetex2lyxtests.vcxproj
+\end_layout
+
+\end_inset
+
+ in the build directory or in the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+src/tex2lyx/test
+\end_layout
+
+\end_inset
+
+ subdirectory of your build directory.
+\end_layout
+
+\begin_layout Itemize
+In the appearing MSVC program right-click on the project
+\family sans
+updatetex2lyxtests
+\family default
+ in the project explorer and chose
+\family sans
+Create
+\family default
.
- For convenience, these commands also produce re-exported roundtrip .lyx.tex
+\end_layout
+
+\begin_layout Standard
+For convenience, these commands also produce re-exported roundtrip .lyx.tex
files.
Please examine the changed output carefully before committing the changed
files to the repository: Since the test machinery does not do a roundtrip
\end_inset
.tex, and does not compare the produced dvi or pdf output, it assumes that
- the stored .lyx reference produces correct output if processed by LyX.
+ the stored .lyx reference produces correct output if processed by \SpecialChar LyX
+.
There is only one chance to detect wrong output: before committing a new
reference.
Once it is committed, it is quite difficult to verify whether it is correct.
\emph on
do not
\emph default
- update the test references by opening them with LyX or directly running
- lyx2lyx on them.
- This would not work, since lyx2lyx and LyX produce slightly different files
+ update the test references by opening them with \SpecialChar LyX
+ or directly running lyx2lyx
+ on them.
+ This would not work, since lyx2lyx and \SpecialChar LyX
+ produce slightly different files
regarding insignificant whitespace and line breaks.
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Adding a new test
\end_layout
list and ask for committing if you do not have commit rights.
\end_layout
-\begin_layout Chapter
-Development policies
+\begin_layout Subsection
+Export tests
\end_layout
\begin_layout Standard
-This chapter lists some guidelines that should be followed.
- This list is not complete, and many guidelines are in separate chapters,
- such as
-\begin_inset Quotes eld
-\end_inset
+The export tests are integration tests.
+ They take longer to run and are more likely to break than the tex2lyx tests.
+ Nevertheless, they have caught many regressions and without a better alternativ
+e it is important to keep them up-to-date and understand how they work.
+\end_layout
-When is an update of the .lyx file format number needed?
-\begin_inset Quotes erd
-\end_inset
+\begin_layout Subsubsection
+Expectations of LyX developers
+\end_layout
- in Section
+\begin_layout Standard
+Because the export tests are integration tests and take a long time to run,
+ LyX developers are rarely expected to run all of the tests.
+ Here are some good practices to follow by developers:
+\end_layout
+
+\begin_layout Itemize
+When making a non-trivial change to a .layout file, run the export and layout
+ tests corresponding with that .layout file.
+\end_layout
+
+\begin_layout Itemize
+When making non-trivial changes to a .lyx file, run the export tests correspondin
+g to that .lyx file.
+\end_layout
+
+\begin_layout Itemize
+When making non-trivial changes to LyX's LaTeX export code (e.g.
+ touching the encoding code or package handling code that you expect will
+ change the exported LaTeX in some way), consider running all of the export
+ tests before and after your change.
+ If there are differences, please reconcile these (i.e.
+ fix the bug or fix the tests)
+\emph on
+before
+\emph default
+ committing.
+ Ask for help if you're not sure what to do or if you do not want to run
+ the tests, post the patch on the list and others will run the tests.
+\end_layout
+
+\begin_layout Itemize
+Understand how to interpret test failures.
+ If your commit is found to have broken a test, you should be able to interpret
+ the test results when made aware of them.
+ See Section
\begin_inset CommandInset ref
LatexCommand ref
-reference "sec:When-is-an"
+reference "subsec:Interpreting-export-tests"
\end_inset
.
\end_layout
-\begin_layout Section
-When to set a fixed milestone?
+\begin_layout Subsubsection
+Configuring the tests
\end_layout
\begin_layout Standard
-Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
- holds:
-\end_layout
+To enable these tests when using CMake, add the
+\begin_inset Flex Code
+status collapsed
-\begin_layout Enumerate
-Somebody is actively working on a fix.
+\begin_layout Plain Layout
+-DLYX_ENABLE_EXPORT_TESTS=ON
\end_layout
-\begin_layout Enumerate
-The bug is so severe that it would block the release if it is not fixed.
+\end_inset
+
+ flag.
+ For example:
\end_layout
\begin_layout Standard
-If a bug is important, but nobody is working on it, and it is no showstopper,
- use a milestone like 2.1.x or 2.2.x.
- For all other bugs, do not set a milestone at all.
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
\end_layout
-\begin_layout Section
-Can we add rc entries in stable branch?
+\end_inset
+
+
\end_layout
\begin_layout Standard
-No.
- We are supposed to increase the prefs2prefs version number with such things.
+\noindent
+This flag will increase the time for the cmake command by several seconds,
+ mainly because of the process of inverting tests (see Section
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "subsec:Interpreting-export-tests"
+
+\end_inset
+
+).
\end_layout
-\begin_layout Chapter
-Documentation policies
+\begin_layout Subsubsection
+Running the tests
\end_layout
\begin_layout Standard
-The main documentation consists of these files:
+To run all tests, in the build directory simply run the command
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest
\end_layout
-\begin_layout Description
-splash.lyx it is the first file you see after an installation.
- We assume that a new user sees this.
- It is therefore designed to be as simple as possible.
- Therefore please don't add any new formatting, only fix typos etc.
- Splash.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
+\end_inset
+
+.
+ To run only some of the tests, use the command
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -R <pattern>
\end_layout
-\begin_layout Description
-Intro.lyx This is the manual new users will read to learn LyX.
+\end_inset
+
+, where
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+<pattern>
+\end_layout
+
+\end_inset
+
+ is a regular expression that matches test names.
+ To run only the export tests, you can use
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -L export
+\end_layout
+
+\end_inset
+
+.
+ For the list of test categories available in addition to
+\begin_inset Quotes eld
+\end_inset
+
+export
+\begin_inset Quotes erd
+\end_inset
+
+, run
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest \SpecialChar nobreakdash
+\SpecialChar nobreakdash
+print-labels
+\end_layout
+
+\end_inset
+
+.
+ It is often useful to list the tests without running them (e.g.
+ if you want to know how many tests there are or whether your
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+<pattern>
+\end_layout
+
+\end_inset
+
+ regular expression did what you expected).
+ This can be done with the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+-N
+\end_layout
+
+\end_inset
+
+ or
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+\SpecialChar nobreakdash
+\SpecialChar nobreakdash
+show-only
+\end_layout
+
+\end_inset
+
+ argument.
+ We are still working on getting the tests to run in parallel which is supported
+ by the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest
+\end_layout
+
+\end_inset
+
+ command with the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+-j <jobs>
+\end_layout
+
+\end_inset
+
+ or
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+\SpecialChar nobreakdash
+\SpecialChar nobreakdash
+parallel <jobs>
+\end_layout
+
+\end_inset
+
+ argument.
+ However, when running the tests in parallel, sometimes tests fail that
+ pass when run sequentially.
+ A reasonable approach is to first run the tests in parallel and then run
+ the failed tests sequentially.
+ For example, to run 8 jobs at a time:
+\end_layout
+
+\begin_layout Standard
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -j8
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest \SpecialChar nobreakdash
+\SpecialChar nobreakdash
+rerun-failed
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+Note that some tests cannot be run in parallel.
+ These tests are marked in the code with the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+\noindent
+RUN_SERIAL ON
+\end_layout
+
+\end_inset
+
+ CMake property.
+\end_layout
+
+\begin_layout Standard
+In some situations the option
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+\SpecialChar nobreakdash
+\SpecialChar nobreakdash
+timeout <seconds>
+\end_layout
+
+\end_inset
+
+ is useful.
+ There have been bugs in LyX and in LaTeX which cause compilation to hang,
+ and without a timeout a test might never stop (in one case there was even
+ a memory leak).
+ If a test times out, the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest
+\end_layout
+
+\end_inset
+
+ command exits with error, but you can distinguish between a timed out test
+ and a failed test in the output reported at the end of the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest
+\end_layout
+
+\end_inset
+
+ command.
+\end_layout
+
+\begin_layout Subsubsection
+\begin_inset CommandInset label
+LatexCommand label
+name "subsec:Interpreting-export-tests"
+
+\end_inset
+
+Interpreting the export test results
+\end_layout
+
+\begin_layout Standard
+A test can fail for several reasons, not all of them bad.
+\end_layout
+
+\begin_layout Enumerate
+The .lyx file could have been added recently and some formats are not expected
+ to work well.
+\end_layout
+
+\begin_layout Enumerate
+A dependency is not met (e.g.
+ the LaTeX class file).
+ One hint that this is the case is that the corresponding
+\begin_inset Flex Code
+status open
+
+\begin_layout Plain Layout
+check_load
+\end_layout
+
+\end_inset
+
+ test will likely also fail.
+\end_layout
+
+\begin_layout Enumerate
+An export that previously failed to compile now compiles.
+\end_layout
+
+\begin_layout Enumerate
+An external dependency was updated (e.g.
+ TeX Live).
+\end_layout
+
+\begin_layout Enumerate
+A recent code change introduced a bug.
+\end_layout
+
+\begin_layout Enumerate
+\begin_inset CommandInset label
+LatexCommand label
+name "enu:exposed"
+
+\end_inset
+
+A change in a document exposed the incompatibility of that class with an
+ export format (e.g.
+ LuaTeX).
+\end_layout
+
+\begin_layout Standard
+Because the .lyx files are exported in several formats, it is not surprising
+ that many of the exports fail.
+ This expectation of failure is addressed by
+\begin_inset Quotes eld
+\end_inset
+
+inverting
+\begin_inset Quotes erd
+\end_inset
+
+ the tests, that is, by marking the test as
+\begin_inset Quotes eld
+\end_inset
+
+passing
+\begin_inset Quotes erd
+\end_inset
+
+ if the export exits with error and as
+\begin_inset Quotes eld
+\end_inset
+
+failing
+\begin_inset Quotes erd
+\end_inset
+
+ if the export succeeds
+\emph on
+.
+
+\emph default
+ It follows that these expected failures will not show up as failed tests
+ in the test results and thus will not pollute the
+\begin_inset Quotes eld
+\end_inset
+
+good
+\begin_inset Quotes erd
+\end_inset
+
+ tests.
+ If the export actually succeeds, then the test will fail.
+ The purpose of this failure is to get your attention—something has changed,
+ possibly for the better.
+\end_layout
+
+\begin_layout Standard
+We try to document why a test is inverted or ignored.
+ See the comment (prefixed with
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+#
+\end_layout
+
+\end_inset
+
+) above the block in which the test is listed as inverted or ignored in
+ the files
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+development/autotests/revertedTests
+\end_layout
+
+\end_inset
+
+ and
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+development/autotests/ignoredTests
+\end_layout
+
+\end_inset
+
+.
+ It is possible that an export goes from succeeding to failing just because
+ the document was changed and the document was never expected to work with
+ a certain export format in the first case.
+ Once this is confirmed to be the situation, the test can be inverted.
+\end_layout
+
+\begin_layout Standard
+A good question is why do we enable the tests for non-default formats? The
+ answer is that if a non-default route is broken it is often because a bug
+ was introduced in LyX and not because a document-specific change was made
+ that is not supported by the route.
+ In other words, there is a high signal/noise ratio in the export tests
+ for the non-default formats.
+
+\end_layout
+
+\begin_layout Standard
+What action should you take if a test fails? First, check manually that
+ when the compilation succeeded before the resulting PDF was good.
+ In fact, sometimes it is an improvement when a test fails.
+ If you check manually, it might be the case that the export was succeeding
+ before but showing garbled text in a PDF output.
+ Now it might fail with a clear message of "language xyz not supported".
+ It is always good to check manually why something fails and if it passes
+ if the PDF output is good.
+\end_layout
+
+\begin_layout Standard
+Sometimes a test is fixed by accident.
+ We should uninvert a test (remove it from the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+revertedTests
+\end_layout
+
+\end_inset
+
+ file) in order to preserve the fix.
+\end_layout
+
+\begin_layout Standard
+When a test or several tests fail, consider checking the files in the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+Testing/Temporary/
+\end_layout
+
+\end_inset
+
+ subdirectory of your build directory.
+ In this subdirectory are three files: the file
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+LastTestsFailed.log
+\end_layout
+
+\end_inset
+
+ simply lists the tests that failed on your last
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest
+\end_layout
+
+\end_inset
+
+ command; the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+LastTest.log
+\end_layout
+
+\end_inset
+
+ file contains the output from the tests (and often has details explaining
+ why a test failed); and the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+CTestCostData.txt
+\end_layout
+
+\end_inset
+
+ file lists the times that it took to run the tests.
+\end_layout
+
+\begin_layout Subsubsection
+Suspended tests
+\end_layout
+
+\begin_layout Standard
+Some inverted tests are 'suspended'.
+ This means, they are not executed using
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -L export
+\end_layout
+
+\end_inset
+
+ or
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -L reverted
+\end_layout
+
+\end_inset
+
+.
+ From time to time they still have to be checked.
+\end_layout
+
+\begin_layout Standard
+These tests are suspended, because they fail for known reasons which cannot
+ ATM be resolved.
+ But it is expected the reason might disappear in the future.
+ Be it new TL or better handling in \SpecialChar LyX
+.
+\end_layout
+
+\begin_layout Standard
+For ctest commands without the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+-L
+\end_layout
+
+\end_inset
+
+ parameter nothing changes.
+ Suspended or not, tests will be executed depending only on the regexes
+ parameters given to the ctest command.
+\end_layout
+
+\begin_layout Subsection
+check_load tests
+\end_layout
+
+\begin_layout Standard
+These tests check whether a .lyx file loads without any terminal messages.
+ They correspond to the manual operations of simply opening a .lyx file on
+ the terminal, exiting LyX once the file is loaded, and then checking whether
+ there is any output from the terminal.
+ These tests are useful for catching malformed .lyx files and parsing bugs.
+ They can also be used to find a .lyx file in which an instance of something
+ happens.
+ To do this, compile LyX with a local patch that outputs something to the
+ terminal when an instance is found, and then run the check_load tests to
+ see if any fail, which would mean that the situation occurs in the LyX
+ documentation files corresponding to the failed tests.
+ These tests are expectedly fragile: any LyX diagnostic message, which is
+ not necessarily an error, would cause the tests to fail.
+ Similarly, any message output by a library (e.g.
+ Qt) would also cause failure.
+ There are some messages that the check_load tests are instructed to ignore,
+ which are stored in the file
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+development/autotests/filterCheckWarnings
+\end_layout
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Subsection
+URL tests
+\end_layout
+
+\begin_layout Standard
+The URL tests are enabled with the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+-DLYX_ENABLE_URLTESTS=ON
+\end_layout
+
+\end_inset
+
+ CMake flag and are useful for finding broken links in our documentation
+ files.
+ If a URL test fails, to see which link in particular was reported as broken,
+ see the output in
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+LastTest.log
+\end_layout
+
+\end_inset
+
+.
+ These tests are extremely fragile (e.g.
+ a test can depend on your Internet connection) and a failed URL test should
+ not be taken too seriously.
+\end_layout
+
+\begin_layout Section
+Development policies
+\end_layout
+
+\begin_layout Standard
+This chapter lists some guidelines that should be followed.
+ This list is not complete, and many guidelines are in separate chapters,
+ such as
+\begin_inset Quotes eld
+\end_inset
+
+When is an update of the .lyx file format number needed?
+\begin_inset Quotes erd
+\end_inset
+
+ in Section
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:When-is-an"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Subsection
+When to set a fixed milestone?
+\end_layout
+
+\begin_layout Standard
+Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
+ holds:
+\end_layout
+
+\begin_layout Enumerate
+Somebody is actively working on a fix.
+\end_layout
+
+\begin_layout Enumerate
+The bug is so severe that it would block the release if it is not fixed.
+\end_layout
+
+\begin_layout Standard
+If a bug is important, but nobody is working on it, and it is no showstopper,
+ use a milestone like 2.1.x or 2.2.x.
+ For all other bugs, do not set a milestone at all.
+\end_layout
+
+\begin_layout Subsection
+Can we add rc entries in stable branch?
+\end_layout
+
+\begin_layout Standard
+No.
+ We are supposed to increase the prefs2prefs version number with such things.
+\end_layout
+
+\begin_layout Section
+Documentation policies
+\end_layout
+
+\begin_layout Standard
+The main documentation consists of these files:
+\end_layout
+
+\begin_layout Description
+splash.lyx it is the first file you see after an installation.
+ We assume that a new user sees this.
+ It is therefore designed to be as simple as possible.
+ Therefore please don't add any new formatting, only fix typos etc.
+ Splash.lyx is up to date for \SpecialChar LyX
+ 2.1.x, currently maintained by Uwe Stöhr.
+\end_layout
+
+\begin_layout Description
+Intro.lyx This is the manual new users will read to learn \SpecialChar LyX
+.
It therefore uses a limited set of formatting.
For example a standard document class.
Since new users will first learn about the formatting possibilities of
- LyX please keep this file that simple.
- Intro.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
+ \SpecialChar LyX
+ please keep this file that simple.
+ Intro.lyx is up to date for \SpecialChar LyX
+ 2.1.x, currently maintained by Uwe Stöhr.
\end_layout
\begin_layout Description
It must be always up to date.
Normally there is nothing to add since we don't want to overwhelm new users
with too much details.
- The will learn these details while using LyX and we have special manuals.
- Tutorial.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
+ The will learn these details while using \SpecialChar LyX
+ and we have special manuals.
+ Tutorial.lyx is up to date for \SpecialChar LyX
+ 2.1.x, currently maintained by Uwe Stöhr.
\end_layout
\begin_layout Description
It covers a mixture of basic and detailed information.
Some information is also in the Math and EmbeddedObjects manual so that
the UserGuide refers to these files.
- UserGuide.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
+ UserGuide.lyx is up to date for \SpecialChar LyX
+ 2.1.x, currently maintained by Uwe Stöhr.
\end_layout
\begin_layout Description
EmbeddedObjects.lyx a special manual to explain things like tables floats
boxes etc.
in all detail.
- EmbeddedObjects.lyx is up to date for LyX 2.1.x, currently maintained by Uwe
+ EmbeddedObjects.lyx is up to date for \SpecialChar LyX
+ 2.1.x, currently maintained by Uwe
Stöhr.
\end_layout
\begin_layout Description
Math.lyx a special manual to explain everything regarding math in all detail.
- Math.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
+ Math.lyx is up to date for \SpecialChar LyX
+ 2.1.x, currently maintained by Uwe Stöhr.
\end_layout
\begin_layout Description
Additional.lyx this manual covers information that would be too much detail
for the UserGuide or would make the UserGuide uncompilable or only compilable
- when installing a lot of special LaTeX-packages.
+ when installing a lot of special \SpecialChar LaTeX
+-packages.
What should be in the UserGuide or better in Additional is a matter of
taste.
it is up to you to decide that.
- Additional.lyx is not completely up to date for LyX 2.1.x.
+ Additional.lyx is not completely up to date for \SpecialChar LyX
+ 2.1.x.
Only chapter
\begin_inset space ~
\end_inset
\end_layout
\begin_layout Description
-Customization.lyx this manual covers information how to customize LyX for
- certain output formats, operating systems, languages etc.
+Customization.lyx this manual covers information how to customize \SpecialChar LyX
+ for certain
+ output formats, operating systems, languages etc.
It is currently completely out of date and needs a major rewrite and update.
If you do this please assure that your information are given for all OSes
- and LaTeX distributions (meaning be as objective as possible).
+ and \SpecialChar LaTeX
+ distributions (meaning be as objective as possible).
\end_layout
\begin_layout Standard
projects / lyx.git / blobdiff