\font_tt_scale 100 100
\graphics default
\default_output_format pdf2
-\output_sync 0
+\output_sync 1
\bibtex_command default
\index_command default
\paperfontsize 12
\end_layout
\begin_layout Enumerate
+\begin_inset CommandInset label
+LatexCommand label
+name "enu:Describe_format"
+
+\end_inset
+
Describe the new format in
\begin_inset Flex Code
status collapsed
\end_layout
\begin_layout Enumerate
+\begin_inset CommandInset label
+LatexCommand label
+name "enu:Add-an-entry"
+
+\end_inset
+
Add an entry to both format lists (for conversion and reversion) in
\begin_inset Newline newline
\end_inset
\end_inset
.
- Then, revert the change to
+ Look at the resulting changes using the command
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-LFUNs.lyx
+git diff
\end_layout
\end_inset
- because that file is meant to be generated separately:
+.
+ If anything looks surprising, please investigate.
+ Keep in mind that the case of
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-git checkout lib/doc/LFUNs.lyx
-\end_layout
-
-\end_inset
-
-
-\begin_inset Note Note
-status collapsed
-
-\begin_layout Plain Layout
-TODO: this step should be done within updatedocs.py
+LFUNs.lyx
\end_layout
\end_inset
-.
- Look at the resulting changes using the command
+ is special, because it is first generated with
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-git diff
+gen_lfuns.py
\end_layout
\end_inset
-.
- If anything looks surprising, please investigate.
+ before being converted to the latest format.
Finally, commit using
\begin_inset Flex Code
status collapsed
\end_layout
\begin_layout Standard
+A change to the functionality of existing LFUNs can require a conversion
+ of
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+.bind
+\end_layout
+
+\end_inset
+
+ and
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+.ui
+\end_layout
+
+\end_inset
+
+ files, and therefore an increment of the LFUN format, as well as a conversion
+ of Info insets in
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+.lyx
+\end_layout
+
+\end_inset
+
+ files for manuals.
+ The latter cannot be done automatically and requires also a \SpecialChar LyX
+ format increase
+ (think of e.g.
+ someone who might have made a set of \SpecialChar LyX
+ teaching manuals for use in their
+ own group)
+\begin_inset Foot
+status open
+
+\begin_layout Plain Layout
+\begin_inset Flex URL
+status open
+
+\begin_layout Plain Layout
+
+http://www.lyx.org/trac/ticket/9794
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Enumerate
+Increment the LFUN file format number in
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+src/LyXAction.h
+\end_layout
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Enumerate
+Implement the LFUN conversion in
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+lib/scripts/prefs2prefs_lfuns.py
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Enumerate
See step
\begin_inset CommandInset ref
LatexCommand ref
.
\end_layout
+\begin_layout Enumerate
+Update Info insets in
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+.lyx
+\end_layout
+
+\end_inset
+
+ files.
+ To do so, increment the \SpecialChar LyX
+ format and proceed as in
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "subsec:update_lyx_files"
+
+\end_inset
+
+, steps
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "enu:Describe_format"
+
+\end_inset
+
+-
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "enu:updatefiles"
+
+\end_inset
+
+.
+ In the lyx2lyx implementation (
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "enu:Add-an-entry"
+
+\end_inset
+
+th step), implement a conversion similar to the one in
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+prefs2prefs_lfuns.py
+\end_layout
+
+\end_inset
+
+ above, as well as a corresponding reversion; for this one can use
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+convert_info_insets
+\end_layout
+
+\end_inset
+
+ from
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+lib/lyx2lyx/lyx2lyx_tools.py
+\end_layout
+
+\end_inset
+
+.
+
+\end_layout
+
\begin_layout Subsection
Backporting new styles to the stable version
\end_layout
\end_layout
\begin_layout Subsection
-ctest automatic tests (cmake only)
+ctest automatic tests
\end_layout
\begin_layout Standard
status collapsed
\begin_layout Plain Layout
-development/autotests
+development/autotests/
\end_layout
\end_inset
subfolder of the \SpecialChar LyX
source code distribution.
+\begin_inset Foot
+status open
+
+\begin_layout Plain Layout
+The README document in this folder only describes the
+\begin_inset Quotes eld
+\end_inset
+
+keytests
+\begin_inset Quotes erd
+\end_inset
+
+ subset of autotests!
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+These tests can be run by the commands
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest
+\end_layout
+
+\end_inset
+
+ in the
+\emph on
+ build directory
+\emph default
+ (all platforms) or (when using a make based build system and not MSVC)
+
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+make test
+\end_layout
+
+\end_inset
+
+ in the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+autotests/
+\end_layout
+
+\end_inset
+
+ subfolder of the
+\emph on
+ build directory
+\emph default
+.
+ The test logs are written to the
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-cmake
+Testing/Temporary/
\end_layout
\end_inset
- is required to run the automatic \SpecialChar LyX
- tests, running them is not implemented
- for autotools.
+ subfolder of the
+\emph on
+
+\emph default
+build directory.
\end_layout
+\begin_layout Subsubsection
+Export tests
+\end_layout
+
\begin_layout Standard
-The \SpecialChar LyX
- tests can be run by the commands
+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
+
+\begin_layout Standard
+The export tests
+\begin_inset Quotes eld
+\end_inset
+
+reuse
+\begin_inset Quotes erd
+\end_inset
+
+ documentation, template, and example documents.
+ In addition, there are a number of dedicated sample documents in the
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-ctest
+autotests/export/
\end_layout
\end_inset
- (all platforms) or
+ subfolder of the \SpecialChar LyX
+ source code distribution.
+ All samples are (after copying and eventual processing by scripts) exported
+ to various output formats via the
\begin_inset Flex Code
status collapsed
-\begin_layout Plain Layout
-make test
+\begin_layout Plain Layout
+—export-to
+\end_layout
+
+\end_inset
+
+ command line option.
+ The tests checks for errors reported by LyX.
+ (However, error-free export is no guarantee for an error-free output document.)
+\end_layout
+
+\begin_layout Paragraph
+Expectations of LyX developers
+\end_layout
+
+\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.
+
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+This rule is due to revision.
+
+\end_layout
+
+\begin_layout Plain Layout
+There is an objection from the documentation maintainer that working on
+ the documentation must not be complicated by having to consider non-standard
+ exports.
+\end_layout
+
+\begin_layout Itemize
+successful compiling/testing an edited documentation file with pdflatex
+ suffices to ensure it can be commited, not tests with other exports are
+ required.
+\end_layout
+
+\begin_layout Plain Layout
+If sudden failures with other exports due to “half-tested” documentation
+ updates are a problem for the test maintainer, the test suite should use
+ copies that are
+\end_layout
+
+\begin_layout Itemize
+copied to a cache dir (autotests/samples/doc/, say) but not changed,
+\end_layout
+
+\begin_layout Itemize
+updated regularely (but on a time chosen by the test suite maintainer) from
+ the originals in lib/doc/
+\end_layout
+
+\begin_layout Plain Layout
+This way,
+\end_layout
+
+\begin_layout Itemize
+no test will fail due to ongoing work on documentation,
+\end_layout
+
+\begin_layout Itemize
+the documentation is still tested in full (with some delay),
+\end_layout
+
+\begin_layout Itemize
+failures with non-default export can be examined and handled accordingly
+ in one run with the cache update,
+\end_layout
+
+\begin_layout Itemize
+“interesting failures” (like the nested-language+polyglossia problem in
+ es/Customization can be separated and moved into dedicated test samples.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Itemize
+When making non-trivial changes to LyX's \SpecialChar LaTeX
+ export code (e.g.
+ touching the encoding code or package handling code that you expect will
+ change the exported \SpecialChar LaTeX
+ in some way):
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+\paragraph_spacing single
+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.
+\end_layout
+
+\begin_layout Standard
+If you do not want to run the tests,
+\end_layout
+
+\begin_layout Itemize
+post the patch on the list and others will run the tests and eventually
+ ask for fixes, or
+\end_layout
+
+\begin_layout Itemize
+commit, but be prepared to fix eventually arising problems or to revert
+ the commit if there is no easy fix.
+\end_layout
+
+\end_deeper
+\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 "subsec:Interpreting-export-tests"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Paragraph
+\begin_inset CommandInset label
+LatexCommand label
+name "par:export-test-output-formats"
+
+\end_inset
+
+Output formats
+\end_layout
+
+\begin_layout Standard
+The following output formats are currently tested for each sample document
+ (see
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "par:Export-test-filtering"
+
+\end_inset
+
+ for exceptions):
+\end_layout
+
+\begin_layout Labeling
+\labelwidthstring 00.00.0000
+LyX:
+\end_layout
+
+\begin_deeper
+\begin_layout Labeling
+\labelwidthstring 00.00.0000
+lyx16 LyX 1.6 file format (lyx2lyx)
+\end_layout
+
+\begin_layout Labeling
+\labelwidthstring 00.00.0000
+lyx21 LyX 2.1 file format (lyx2lyx)
+\end_layout
+
+\begin_layout Labeling
+\labelwidthstring 00.00.0000
+xhtml LyXHTML (native LyX HTML export)
+\end_layout
+
+\end_deeper
+\begin_layout Labeling
+\labelwidthstring 00.00.0000
+LyX
+\begin_inset space ~
+\end_inset
+
++
+\begin_inset space ~
+\end_inset
+
+LaTeX:
+\end_layout
+
+\begin_deeper
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+dvi DVI (8-bit latex)
+\end_layout
+
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+dvi3_texF DVI (LuaTeX with 8-bit TeX fonts)
+\end_layout
+
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+dvi3_systemF DVI (LuaTeX with Unicode fonts)
+\end_layout
+
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+pdf2 PDF (pdflatex)
+\end_layout
+
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+pdf4_texF PDF (XeTeX with 8-bit TeX fonts)
+\end_layout
+
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+pdf4_systemF PDF (XeTeX with Unicode fonts)
+\end_layout
+
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+pdf5_texF PDF (LuaTeX with 8-bit TeX fonts)
+\end_layout
+
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+pdf5_systemF PDF (LuaTeX with Unicode fonts)
\end_layout
+\end_deeper
+\begin_layout Labeling
+\labelwidthstring 00.00.0000
+LyX
+\begin_inset space ~
\end_inset
- (when using a make based build system and not MSVC) in the
-\begin_inset Flex Code
-status collapsed
++
+\begin_inset space ~
+\end_inset
-\begin_layout Plain Layout
-autotests
-\end_layout
+LaTeX
+\begin_inset space ~
+\end_inset
++
+\begin_inset space ~
\end_inset
- subfolder of the build directory.
+postprocessing:
\end_layout
-\begin_layout Subsubsection
-Export tests
+\begin_deeper
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+pdf DVI -> PS (dvips) -> PDF (ps2pdf)
\end_layout
-\begin_layout Standard
-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.
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+pdf3 DVI -> PDF (dvipdfm)
\end_layout
-\begin_layout Standard
-The export tests
-\begin_inset Quotes eld
-\end_inset
-
-reuse
-\begin_inset Quotes erd
+\end_deeper
+\begin_layout Labeling
+\labelwidthstring 00.00.0000
+not
+\begin_inset space ~
\end_inset
- documentation, template, and example files trying to export them to all
- supported output formats.
- In addition, there are a number of dedicated sample documents under
-\begin_inset Flex Code
-status collapsed
-
-\begin_layout Plain Layout
-autotests/export/
+tested: (or only if set as default output format in the document source)
\end_layout
-\end_inset
+\begin_deeper
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+latex LaTeX (plain)
+\end_layout
-.
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+luatex LaTeX (LuaTeX)
\end_layout
-\begin_layout Paragraph
-Expectations of LyX developers
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+dviluatex LaTeX (dviluatex)
\end_layout
-\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:
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+pdflatex LaTeX (pdflatex)
\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.
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+platex LaTeX (pLaTeX)
\end_layout
-\begin_layout Itemize
-When making non-trivial changes to a .lyx file, run the export tests correspondin
-g to that .lyx file.
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+xetex LaTeX (XeTeX)
\end_layout
-\begin_layout Itemize
-When making non-trivial changes to LyX's \SpecialChar LaTeX
- export code (e.g.
- touching the encoding code or package handling code that you expect will
- change the exported \SpecialChar LaTeX
- in some way):
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+eps3 EPS (encapsulated Postscript) (cropped)
\end_layout
-\begin_deeper
-\begin_layout Standard
-\paragraph_spacing single
-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.
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+ps DVI -> Postscript (dvips)
\end_layout
-\begin_layout Standard
-If you do not want to run the tests,
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+odf
\end_layout
-\begin_layout Itemize
-post the patch on the list and others will run the tests and eventually
- ask for fixes, or
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+text (nor text2, ..., text4)
\end_layout
-\begin_layout Itemize
-commit, but be prepared to fix eventually arising problems or to revert
- the commit if there is no easy fix.
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+textparagraph
\end_layout
-\end_deeper
-\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 "subsec:Interpreting-export-tests"
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+word
+\end_layout
-\end_inset
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+word2
+\end_layout
-.
+\begin_layout Labeling
+\labelwidthstring pdf5msystemFM
+wordhtml
\end_layout
+\end_deeper
\begin_layout Paragraph
\begin_inset CommandInset label
LatexCommand label
\end_inset
+.
+ A full, up-to-date TeXLive installation is recommended to run the tests.
+ Otherwise, some tests will fail.
+ Tests with additional requirements are labeled
+\begin_inset Quotes eld
+\end_inset
+
+unreliable:nonstandard
+\begin_inset Quotes erd
+\end_inset
+
.
\end_layout
\begin_layout Standard
-To run only some of the tests, use command line options:
+To run only some of the tests, use command line options (see examples below):
\end_layout
\begin_layout Labeling
\end_layout
-\begin_deeper
-\begin_layout Standard
-For example, 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
-
-.
-\end_layout
-
-\end_deeper
\begin_layout Labeling
\labelwidthstring -R
\begin_inset Flex Code
pass when run sequentially.
A reasonable approach is to first run the tests in parallel and then run
the failed tests sequentially.
-
\end_layout
\begin_layout Standard
\end_layout
+\begin_layout Standard
+When specifying a subset of the tests (e.g.
+ using
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+\SpecialChar nobreakdash
+R <pattern>
+\end_layout
+
+\end_inset
+
+), the same subset must be specified when using the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+\SpecialChar nobreakdash
+\SpecialChar nobreakdash
+rerun-failed
+\end_layout
+
+\end_inset
+
+ option because it is the test numbers that are used to index which tests
+ failed on the previous run.
+\end_layout
+
\begin_layout Standard
\noindent
Note that some tests cannot be run in parallel.
) the full list of command line options.
\end_layout
+\begin_layout Paragraph
+Examples
+\end_layout
+
+\begin_layout Itemize
+run only the export tests:
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -L export
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Itemize
+run inverted tests:
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -L "inverted|suspended"
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Itemize
+list all export tests which match any of the labelling patterns:
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -N -R "
+\backslash
+..*_export/"
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Itemize
+exclude rarely used output formats and post-processing tests
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -L export -E "_(texF|dvi3|pdf3?)"
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
\begin_layout Paragraph
\begin_inset CommandInset label
LatexCommand label
\end_layout
\begin_layout Enumerate
-The .lyx file could have been added recently and some formats are not expected
- to work well.
+A new or edited sample document may be incompatible with some output formats.
\end_layout
\begin_layout Enumerate
development/autotests/suspiciousTests
\end_layout
+\end_inset
+
+,
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+development/autotests/unreliableTests
+\end_layout
+
\end_inset
and
\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
).
\end_layout
+\begin_layout Itemize
+In case of tests failing due to missing requirements (when only a subset
+ of TeXLive is installed or a test labeled
+\begin_inset Quotes eld
+\end_inset
+
+unreliable:nonstandard
+\begin_inset Quotes erd
+\end_inset
+
+ fails), ignore the failure, ask for someone else to run the test, or install
+ the missing ressources and try again.
+\end_layout
+
\begin_layout Paragraph
\begin_inset CommandInset label
LatexCommand label
\end_deeper
\begin_layout Paragraph
+\begin_inset CommandInset label
+LatexCommand label
+name "par:Export-test-filtering"
+
+\end_inset
+
Export test filtering
\end_layout
Under cmake, the tests are labeled as 'load'.
\end_layout
+\begin_layout Subsubsection
+Keytests
+\end_layout
+
+\begin_layout Standard
+Automated tests based on the "MonKey Testing" keytest program.
+ They are documented in the README document in
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+development/autotests
+\end_layout
+
+\end_inset
+
+ subfolder of the \SpecialChar LyX
+ source code distribution.
+ T
+\end_layout
+
\begin_layout Subsubsection
lyx21 tests
\end_layout
projects / lyx.git / blobdiff