mirror of
https://git.lyx.org/repos/lyx.git
synced 2024-12-22 21:21:32 +00:00
2429 lines
49 KiB
Plaintext
2429 lines
49 KiB
Plaintext
#LyX 2.2 created this file. For more info see http://www.lyx.org/
|
|
\lyxformat 503
|
|
\begin_document
|
|
\begin_header
|
|
\origin /systemlyxdir/doc/
|
|
\textclass scrartcl
|
|
\options BCOR8mm,captions=tableheading
|
|
\use_default_options false
|
|
\begin_modules
|
|
logicalmkup
|
|
\end_modules
|
|
\maintain_unincluded_children false
|
|
\language english
|
|
\language_package default
|
|
\inputencoding auto
|
|
\fontencoding global
|
|
\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 100
|
|
\font_tt_scale 100 100
|
|
\graphics default
|
|
\default_output_format default
|
|
\output_sync 0
|
|
\bibtex_command default
|
|
\index_command default
|
|
\paperfontsize 12
|
|
\spacing single
|
|
\use_hyperref true
|
|
\pdf_title "LyX's Development manual"
|
|
\pdf_author "LyX Team"
|
|
\pdf_subject "LyX's development documentation"
|
|
\pdf_keywords "LyX, Documentation, Development"
|
|
\pdf_bookmarks true
|
|
\pdf_bookmarksnumbered true
|
|
\pdf_bookmarksopen true
|
|
\pdf_bookmarksopenlevel 1
|
|
\pdf_breaklinks false
|
|
\pdf_pdfborder false
|
|
\pdf_colorlinks true
|
|
\pdf_backref false
|
|
\pdf_pdfusetitle false
|
|
\pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
|
|
\papersize a4paper
|
|
\use_geometry false
|
|
\use_package amsmath 1
|
|
\use_package amssymb 1
|
|
\use_package cancel 0
|
|
\use_package esint 0
|
|
\use_package mathdots 1
|
|
\use_package mathtools 0
|
|
\use_package mhchem 1
|
|
\use_package stackrel 0
|
|
\use_package stmaryrd 0
|
|
\use_package undertilde 0
|
|
\cite_engine basic
|
|
\cite_engine_type default
|
|
\biblio_style plain
|
|
\use_bibtopic false
|
|
\use_indices false
|
|
\paperorientation portrait
|
|
\suppress_date false
|
|
\justification true
|
|
\use_refstyle 0
|
|
\notefontcolor #0000ff
|
|
\index Index
|
|
\shortcut idx
|
|
\color #008000
|
|
\end_index
|
|
\secnumdepth 4
|
|
\tocdepth 4
|
|
\paragraph_separation indent
|
|
\paragraph_indentation default
|
|
\quotes_language english
|
|
\papercolumns 1
|
|
\papersides 2
|
|
\paperpagestyle headings
|
|
\tracking_changes false
|
|
\output_changes false
|
|
\html_math_output 0
|
|
\html_css_as_file 0
|
|
\html_be_strict true
|
|
\end_header
|
|
|
|
\begin_body
|
|
|
|
\begin_layout Title
|
|
Developing \SpecialChar LyX
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Subtitle
|
|
Version 2.2.x
|
|
\end_layout
|
|
|
|
\begin_layout Author
|
|
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 \SpecialChar LyX
|
|
Documentatio
|
|
n mailing list,
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
\noindent
|
|
<lyx-docs@lists.lyx.org>
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
\begin_inset CommandInset toc
|
|
LatexCommand tableofcontents
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Section
|
|
Introduction
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
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
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
development
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
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 Section
|
|
File formats
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
\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 Subsection
|
|
File Format Numbers
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
When is an update of the .lyx file format number needed?
|
|
\begin_inset CommandInset label
|
|
LatexCommand label
|
|
name "sec:When-is-an"
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
When you are working on a new feature you may ask yourself whether it needs
|
|
an update of the .lyx file format number.
|
|
Whether an update is needed or not is not always obvious.
|
|
Below you can find a list of reasons for file format updates with explanations:
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
New
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
document
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
setting Whenever you introduce a new setting that is stored in the document
|
|
header, a file format update is needed.
|
|
This is also true if you add a new valid value to an existing setting,
|
|
e.
|
|
\begin_inset space \thinspace{}
|
|
\end_inset
|
|
|
|
g.
|
|
\begin_inset space \space{}
|
|
\end_inset
|
|
|
|
a new language that is stored in
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
|
|
\backslash
|
|
language
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
Removed
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
document
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
setting If a certain setting becomes obsolete and gets removed, a file format
|
|
update is needed.
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
New
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
inset Of course a new inset requires a file format update.
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
New
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
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.
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
Automatically
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
loaded
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
math
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
package Any new math package that is automatically loaded needs a file format
|
|
update.
|
|
The reason for this is that there is no true ERT inset for math formulas:
|
|
Each command is parsed, and if a user happens to defne a local command
|
|
with the same name as a command that triggers an automatic load of a package,
|
|
he needs to be able to switch off the automatic loading of that package.
|
|
This switch is stored by the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
use_package
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
header setting.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
If you are still unsure, please ask on the development list.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
How to update the file format number of .lyx files
|
|
\begin_inset CommandInset label
|
|
LatexCommand label
|
|
name "subsec:update_lyx_files"
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Once you came to the conclusion that a file format update is needed you
|
|
should use the following procedure to perform the update:
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
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 \SpecialChar LyX
|
|
for working on any important documents.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Describe the new format in
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
development/FORMAT
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Update the \SpecialChar LyX
|
|
file format number in
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/version.h
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Update the range of file formats in the array
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
format_relation
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
in
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
lib/lyx2lyx/LyX.py
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Add an entry to both format lists (for conversion and reversion) in
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
lib/lyx2lyx/lyx_2_2.py
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
Add a conversion routine if needed (e.
|
|
\begin_inset space \thinspace{}
|
|
\end_inset
|
|
|
|
g.
|
|
\begin_inset space \space{}
|
|
\end_inset
|
|
|
|
a new header setting always needs a conversion that adds the new setting,
|
|
a new document language does not need one).
|
|
Add a reversion routine if needed.
|
|
While the conversion routine is required to produce a document that is
|
|
equivalent to the old version, the requirements of the reversion are not
|
|
that strict.
|
|
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 \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 \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
|
|
\begin_layout Enumerate
|
|
Update the tex2lyx file format number in
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/version.h
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
If the lyx2lyx conversion from the old to the new format is empty, or if
|
|
tex2lyx does not yet output the changed feature, you do not need any further
|
|
tex2lyx changes.
|
|
Otherwise, search for the changed feature in tex2lyx, and adjust the output
|
|
according to the lyx2lyx changes.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Update the tex2lyx test references as described in
|
|
\begin_inset CommandInset ref
|
|
LatexCommand formatted
|
|
reference "sec:Updating-test-references"
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\end_deeper
|
|
\begin_layout Enumerate
|
|
If you did not implement full tex2lyx support of the new feature, add a
|
|
line to
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/tex2lyx/TODO.txt
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
describing the missing bits.
|
|
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 \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 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 Enumerate
|
|
\begin_inset CommandInset label
|
|
LatexCommand label
|
|
name "enu:updatefiles"
|
|
|
|
\end_inset
|
|
|
|
Update LyX's .lyx documentation files to the new format.
|
|
The developer who makes the change knows best what changes to expect when
|
|
inspecting the resulting diff.
|
|
Because of this, you might be able to catch a bug in the lyx2lyx code that
|
|
updates the format just by taking a quick scan through the large diff that
|
|
is the result
|
|
\begin_inset Note Note
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
Another advantage is that if later we suspect a bug in lyx2lyx we can easily
|
|
see which layout update made an unexpected change by looking at the git
|
|
log of a .lyx file that suffers the problem.
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
To do this, first make sure that there are no changes to the git repository
|
|
that you will not want to commit (this is needed because it will be convenient
|
|
to commit with the command
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
git commit -a
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
).
|
|
Then run the following command in the root folder of the source:
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
python development/tools/updatedocs.py
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
Then, revert the change to
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
LFUNs.lyx
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
because that file is meant to be generated separately:
|
|
\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
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
Look at the resulting changes using the command
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
git diff
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
If anything looks surprising, please investigate.
|
|
Finally, commit using
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
git commit -a
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
Updating the file format number of layout files
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
See step
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "enu:updatefiles"
|
|
|
|
\end_inset
|
|
|
|
in section
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "subsec:update_lyx_files"
|
|
|
|
\end_inset
|
|
|
|
but instead of the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
updatedocs.py
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
command, use this command:
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
python development/tools/updatelayouts.py
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
Updating the file format number of bind/ui files
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
See step
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "enu:updatefiles"
|
|
|
|
\end_inset
|
|
|
|
in section
|
|
\begin_inset CommandInset ref
|
|
LatexCommand ref
|
|
reference "subsec:update_lyx_files"
|
|
|
|
\end_inset
|
|
|
|
but instead of the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
updatedocs.py
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
command, use this command:
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
bash development/tools/updatelfuns.sh
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
Backporting new styles to the stable version
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
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.
|
|
To backport a new style to the stable version, the following steps are
|
|
needed:
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Add the line
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
ForceLocal -1
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
to the style definition in the development version.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Copy the style definition to the stable version, but use
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
ForceLocal 1
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
instead.
|
|
If needed adjust the format to the one used by the stable version (see
|
|
the customization manual for details of the layout file format).
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
For each update of the style in a later stable version, increase the argument
|
|
of
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
ForceLocal
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
by one (in the stable version, the development version should not be touched).
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
For details about the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
ForceLocal
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
flag see the customization manual.
|
|
No
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
lyx2lyx
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
support is needed for backported styles: Since the style of the development
|
|
version has an infinite version number, it will always be used.
|
|
Furthermore, since its version number is less than one, the style will
|
|
not be written anymore to the document header for files saved by the new
|
|
version.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
\begin_inset Newpage newpage
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Section
|
|
Tests
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Automated tests are an important tool to detect bugs and regressions in
|
|
software development.
|
|
Some projects like gcc even require each bug fix to be accompanied by a
|
|
test case for the automatic test suite, that would detect this bug.
|
|
Testing interactive features automatically is of course very hard, but
|
|
core functionality like document import and export can be tested quite
|
|
easily, and some tests of this kind exist.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
\SpecialChar LyX
|
|
tests
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Some tests are located in the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
development/autotests
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
subfolder of the \SpecialChar LyX
|
|
source code distribution.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Running the tests
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
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
|
|
ctest
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
(all platforms) or
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
make test
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
(when using a make based build system and not MSVC) in the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
autotests
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
subfolder of the build directory.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
tex2lyx tests
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The tex2lyx tests are located in the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/tex2lyx/test
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
subfolder of the \SpecialChar LyX
|
|
source code distribution.
|
|
The actual testing is performed by the simple python script
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/tex2lyx/test/runtests.py
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
Each test consists of two files:
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
<test name>.tex
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
contains the \SpecialChar LaTeX
|
|
code that should be tested.
|
|
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
<test name>.lyx.lyx
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
contains the expected output of tex2lyx.
|
|
When a test is run, the actual produced output is compared with the stored
|
|
reference output.
|
|
The test passes if both are identical.
|
|
The test machinery is also able to generate a file
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
<test name>.lyx.tex
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
by exporting the produced .lyx file with \SpecialChar LyX
|
|
again.
|
|
This may be useful for roundtrip comparisons.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Running the tests
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
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
|
|
|
|
\begin_layout Plain Layout
|
|
make test
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
(cmake, when using a make based build system and not MSVC) or
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
make alltests
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
(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
|
|
ctest -R tex2lyx
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
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 Subsubsection
|
|
Updating test references
|
|
\begin_inset CommandInset label
|
|
LatexCommand label
|
|
name "sec:Updating-test-references"
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
In some cases a changed tex2lyx output is not a test failure, but wanted,
|
|
e.
|
|
\begin_inset space \thinspace{}
|
|
\end_inset
|
|
|
|
g.
|
|
\begin_inset space \space{}
|
|
\end_inset
|
|
|
|
if a tex2lyx bug was fixed, or a new feature was added.
|
|
In these cases the stored references need to be updated.
|
|
To do so if using autotools, call
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
make updatetests
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
in the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/tex2lyx
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
subdirectory of the build directory.
|
|
If instead using CMake, call
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
make updatetex2lyxtests
|
|
\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 the build directory.
|
|
\begin_inset Foot
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
Note that this is a case where a make target in the build directory can
|
|
affect the source directory, which might not be advisable.
|
|
\end_layout
|
|
|
|
\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
|
|
.
|
|
\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
|
|
test .tex
|
|
\begin_inset Formula $\Rightarrow$
|
|
\end_inset
|
|
|
|
.lyx
|
|
\begin_inset Formula $\Rightarrow$
|
|
\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 \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.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Please
|
|
\emph on
|
|
do not
|
|
\emph default
|
|
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 Subsubsection
|
|
Adding a new test
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
In many cases tests for new features may be added to one of the existing
|
|
test files, but sometimes this is not possible or not wanted.
|
|
Then a new test file needs to be added:
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Create the new file
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/tex2lyx/test/<test name>.tex
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
and run tex2lyx in roundtrip mode to produce the file
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/tex2lyx/test/<test name>.lyx.lyx
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
This file will be the new reference.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Once you confirmed that the tex2lyx output is correct, add the new files
|
|
to the corresponding lists in
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/tex2lyx/test/runtests.py
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
,
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/tex2lyx/Makefile.am
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
and
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/tex2lyx/test/CMakeLists.txt
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Commit the changes to the repository, or send a patch to the development
|
|
list and ask for committing if you do not have commit rights.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
Export tests (cmake only)
|
|
\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.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The export tests require the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
ctest
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
command that comes with the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
cmake
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
build system
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
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.
|
|
\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 "subsec:Interpreting-export-tests"
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Configuring the tests
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
To enable these tests, add the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
-DLYX_ENABLE_EXPORT_TESTS=ON
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
flag.
|
|
For example:
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
cmake -DLYX_ENABLE_EXPORT_TESTS=ON /path/to/source
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
\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 Subsubsection
|
|
Running the tests
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
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
|
|
|
|
\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
|
|
|
|
\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 Standard
|
|
See the manual (
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
man ctest
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
) the full list of command line options.
|
|
\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 inverted test fails to fail (i.e.
|
|
export that previously failed now works).
|
|
\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 a previously unknown bug or an incompatibility
|
|
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 some 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 as side-effect of some change.
|
|
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
|
|
Inverted tests
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
These tests are expected to always fail.
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
reverted These tests are expected to fail, but are subject to be examined.
|
|
It is expected that they will pass in a foreseeable future.
|
|
They are labeled 'reverted'.
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
suspended Some inverted tests are labeled '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 using
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
ctest -L suspended
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
.
|
|
\end_layout
|
|
|
|
\begin_deeper
|
|
\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
|
|
|
|
\end_deeper
|
|
\begin_layout Subsubsection
|
|
Unreliable tests
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
nonstandard Requires non-standard ressources (LaTeX packages and document
|
|
classes, fonts, ...) that are not a requirement for running this test suite.
|
|
\end_layout
|
|
|
|
\begin_deeper
|
|
\begin_layout Standard
|
|
These tests are labeled as
|
|
\family typewriter
|
|
'nonstandard'.
|
|
\end_layout
|
|
|
|
\end_deeper
|
|
\begin_layout Description
|
|
erratic Tests with
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
arbitrary
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
result, depending on local configuration, OS, TeX distribution, package
|
|
versions, or the phase of the moon.
|
|
\end_layout
|
|
|
|
\begin_deeper
|
|
\begin_layout Standard
|
|
These tests are labeled as
|
|
\family typewriter
|
|
'erratic'.
|
|
\end_layout
|
|
|
|
\end_deeper
|
|
\begin_layout Subsection
|
|
Export test filtering
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
There are files which control the assignment of a label to a test.
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
ignoredTests (smal file)
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
Tests selected here are withdrawn
|
|
\end_layout
|
|
|
|
\begin_deeper
|
|
\begin_layout Labeling
|
|
\labelwidthstring 00.00.0000
|
|
Input Test of any export combination
|
|
\end_layout
|
|
|
|
\begin_layout Labeling
|
|
\labelwidthstring 00.00.0000
|
|
Output Stop if tests not selected here
|
|
\end_layout
|
|
|
|
\end_deeper
|
|
\begin_layout Description
|
|
unreliableTests: Tests selected either pass or fail, but that is dependent
|
|
on the system where the test is run.
|
|
Selected tests gain the label 'unreliable'.
|
|
\end_layout
|
|
|
|
\begin_deeper
|
|
\begin_layout Labeling
|
|
\labelwidthstring 00.00.0000
|
|
Input Each test which passed 'ignoredTests'
|
|
\end_layout
|
|
|
|
\begin_layout Labeling
|
|
\labelwidthstring 00.00.0000
|
|
Output Stop if test selected, gain label 'unreliable'.
|
|
\end_layout
|
|
|
|
\end_deeper
|
|
\begin_layout Description
|
|
suspiciousTests
|
|
\begin_inset space \space{}
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_deeper
|
|
\begin_layout Labeling
|
|
\labelwidthstring 00.00.0000
|
|
Input Each test which passed 'unreliableTests'
|
|
\end_layout
|
|
|
|
\begin_layout Labeling
|
|
\labelwidthstring 00.00.0000
|
|
Output Stop if not selected.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The following file is meant as subselections of 'suspiciousTests'.
|
|
If neither subselection applies, test gains labels 'export' and 'reverted'
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
suspendedTests Tests selected here gain the label 'suspended' but _not_
|
|
'export' or 'reverted'.
|
|
\end_layout
|
|
|
|
\begin_deeper
|
|
\begin_layout Labeling
|
|
\labelwidthstring 00.00.0000
|
|
Input Each test selected by 'suspiciousTests'
|
|
\end_layout
|
|
|
|
\begin_layout Labeling
|
|
\labelwidthstring 00.00.0000
|
|
Output Selected test gains label 'suspended'.
|
|
|
|
\end_layout
|
|
|
|
\end_deeper
|
|
\end_deeper
|
|
\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 Standard
|
|
Under cmake, the tests are labeled as 'load'.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
URL tests (cmake only)
|
|
\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.
|
|
URL tests are labeled as
|
|
\family typewriter
|
|
'url'.
|
|
\end_layout
|
|
|
|
\begin_layout Subsubsection
|
|
Running URL tests
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
cmake is required to run the \SpecialChar LyX
|
|
tests, running them is not implemented for
|
|
autotools.
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The appropriate commands are:
|
|
\end_layout
|
|
|
|
\begin_layout Itemize
|
|
|
|
\family typewriter
|
|
ctest -L url
|
|
\family default
|
|
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
runns all tests with label
|
|
\family typewriter
|
|
'url'
|
|
\end_layout
|
|
|
|
\begin_layout Itemize
|
|
|
|
\family typewriter
|
|
ctest -R 'check_.*urls'
|
|
\family default
|
|
|
|
\begin_inset Newline newline
|
|
\end_inset
|
|
|
|
runns the tests 'check_accessible_urls'
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
Associated test results can be examined in ctest-log directory in files
|
|
of the form 'LastFailed.*URLS.log'
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
Test labels (cmake only)
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
ctest label commands:
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
\SpecialChar nobreakdash
|
|
\SpecialChar nobreakdash
|
|
print-labels shows all assigned labels
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
\SpecialChar nobreakdash
|
|
L
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
labelname executes all tests to which this label is asigned to.
|
|
A test may have more that one label.
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
\SpecialChar nobreakdash
|
|
j
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
number executes tests in parallel using 'number' simultaneously processes.
|
|
Some tests are marked as 'sequencial', for them this parameter has no effect.
|
|
\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
|
|
\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
|
|
Tutorial.lyx our tutorial.
|
|
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 \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
|
|
UserGuide.lyx our main user guide.
|
|
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 \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 \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 \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 \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 \SpecialChar LyX
|
|
2.1.x.
|
|
Only chapter
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
8 is up to date and currently maintained by Uwe Stöhr.
|
|
It certainly needs a rewrite and update.
|
|
For example many info in chapter
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
|
|
manual.
|
|
\end_layout
|
|
|
|
\begin_layout Description
|
|
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 \SpecialChar LaTeX
|
|
distributions (meaning be as objective as possible).
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
There are only 4
|
|
\begin_inset space ~
|
|
\end_inset
|
|
|
|
rules in editing the docs:
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
If you are not the maintainer of a doc file or a chapter/section, you MUST
|
|
use change tracking so that the maintainer could review your changes
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
Respect the formatting of the document.
|
|
The different files use different formatting styles.
|
|
That is OK and has historic reasons nobody fully know ;-).
|
|
But it is important to be consistent within one file.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
All changes you make to a file in one language MUST also go the file in
|
|
the other actively maintained languages.
|
|
Normally the maintainer does this for you, if you are the maintainer, you
|
|
must do this by copying or changing the changed or added text to the other
|
|
files so that the translators sees the blue underlined text and know what
|
|
they have to translate and what was changed.
|
|
\end_layout
|
|
|
|
\begin_layout Enumerate
|
|
You MUST assure that the document is compilable as
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
PDF (pdflatex)
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
after your changes.
|
|
\end_layout
|
|
|
|
\end_body
|
|
\end_document
|