mirror of
https://git.lyx.org/repos/lyx.git
synced 2024-11-13 22:49:20 +00:00
1103 lines
24 KiB
Plaintext
1103 lines
24 KiB
Plaintext
#LyX 2.1 created this file. For more info see http://www.lyx.org/
|
|
\lyxformat 474
|
|
\begin_document
|
|
\begin_header
|
|
\textclass scrbook
|
|
\options fleqn,bibliography=totoc,index=totoc,BCOR7.5mm,titlepage,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
|
|
Format 7
|
|
InsetLayout CharStyle:MenuItem
|
|
LyxType charstyle
|
|
LabelString menu
|
|
LatexType command
|
|
LatexName menuitem
|
|
Font
|
|
Family Sans
|
|
EndFont
|
|
Preamble
|
|
\newcommand*{\menuitem}[1]{{\sffamily #1}}
|
|
EndPreamble
|
|
End
|
|
\end_local_layout
|
|
\language english
|
|
\language_package default
|
|
\inputencoding auto
|
|
\fontencoding global
|
|
\font_roman default
|
|
\font_sans default
|
|
\font_typewriter default
|
|
\font_math auto
|
|
\font_default_family default
|
|
\use_non_tex_fonts false
|
|
\font_sc false
|
|
\font_osf false
|
|
\font_sf_scale 100
|
|
\font_tt_scale 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 3
|
|
\tocdepth 3
|
|
\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 LyX
|
|
\end_layout
|
|
|
|
\begin_layout Subtitle
|
|
Version 2.2.x
|
|
\end_layout
|
|
|
|
\begin_layout Author
|
|
by the 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,
|
|
\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 Chapter
|
|
Introduction
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
This manual documents some aspects of 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 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.
|
|
\end_layout
|
|
|
|
\begin_layout Chapter
|
|
File formats
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
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
|
|
File Format Numbers
|
|
\end_layout
|
|
|
|
\begin_layout Section
|
|
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 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 Section
|
|
How to update the file format number of .lyx files
|
|
\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 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 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
|
|
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 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.
|
|
In many cases the tex2lyx update requires only the first and last item
|
|
of the list below:
|
|
\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 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 lyxl2yx 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 Section
|
|
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.
|
|
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 Chapter
|
|
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 Section
|
|
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 LyX source code distribution.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
Running the tests
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The LyX tests can be run by the commands
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
make test
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
(cmake) in the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
autotests
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
subfolder of the build directory.
|
|
\begin_inset Note Note
|
|
status open
|
|
|
|
\begin_layout Plain Layout
|
|
FIXME: Is this possible with autotools?
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
|
|
\end_layout
|
|
|
|
\begin_layout Section
|
|
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 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 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 LyX again.
|
|
This may be useful for roundtrip comparisons.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
Running the tests
|
|
\end_layout
|
|
|
|
\begin_layout Standard
|
|
The tex2lyx tests can be run by the commands
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
make test
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
(cmake) or
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
make alltests
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
(autotools) in the
|
|
\begin_inset Flex Code
|
|
status collapsed
|
|
|
|
\begin_layout Plain Layout
|
|
src/tex2lyx
|
|
\end_layout
|
|
|
|
\end_inset
|
|
|
|
subfolder of the build directory.
|
|
If a test fails, the differences between the expected and actual results
|
|
are output in unified diff format.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
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
|
|
|
|
.
|
|
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 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 LyX or directly running
|
|
lyx2lyx on them.
|
|
This would not work, since lyx2lyx and LyX produce slightly different files
|
|
regarding insignificant whitespace and line breaks.
|
|
\end_layout
|
|
|
|
\begin_layout Subsection
|
|
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 Chapter
|
|
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 Section
|
|
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 Section
|
|
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 Chapter
|
|
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 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 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.
|
|
\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 LyX and we have special manuals.
|
|
Tutorial.lyx is up to date for 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 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
|
|
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.
|
|
\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.
|
|
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.
|
|
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 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).
|
|
\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
|