1 #LyX 2.1 created this file. For more info see http://www.lyx.org/
6 \options fleqn,bibliography=totoc,index=totoc,BCOR7.5mm,titlepage,captions=tableheading
7 \use_default_options false
15 \maintain_unincluded_children false
18 InsetLayout CharStyle:MenuItem
27 \newcommand*{\menuitem}[1]{{\sffamily #1}}
32 \language_package default
37 \font_typewriter default
39 \font_default_family default
40 \use_non_tex_fonts false
46 \default_output_format default
48 \bibtex_command default
49 \index_command default
53 \pdf_title "LyX's Development manual"
54 \pdf_author "LyX Team"
55 \pdf_subject "LyX's development documentation"
56 \pdf_keywords "LyX, Documentation, Development"
58 \pdf_bookmarksnumbered true
59 \pdf_bookmarksopen false
60 \pdf_bookmarksopenlevel 1
65 \pdf_pdfusetitle false
66 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
69 \use_package amsmath 1
70 \use_package amssymb 1
72 \use_package mathdots 1
73 \use_package mathtools 0
75 \use_package stackrel 0
76 \use_package stmaryrd 0
77 \use_package undertilde 0
79 \cite_engine_type numerical
83 \paperorientation portrait
87 \notefontcolor #0000ff
94 \paragraph_separation indent
95 \paragraph_indentation default
96 \quotes_language english
99 \paperpagestyle headings
100 \tracking_changes false
101 \output_changes false
113 \begin_layout Subtitle
122 \begin_layout Plain Layout
124 If you have comments or error corrections, please send them to the LyX Documenta
126 \begin_inset Flex Code
129 \begin_layout Plain Layout
131 <lyx-docs@lists.lyx.org>
144 \begin_layout Standard
145 \begin_inset CommandInset toc
146 LatexCommand tableofcontents
153 \begin_layout Chapter
157 \begin_layout Standard
158 This manual documents some aspects of LyX development.
159 It is currently rather incomplete, but will hopefully be extended in the
161 Meanwhile, additional information can be found in the
162 \begin_inset Flex Code
165 \begin_layout Plain Layout
171 subfolder of the LyX source code distribution.
172 This document is not translated, since the development language of LyX
174 If you want to use LyX you don't need to read this manual.
175 However, if you want to learn more about how LyX is developed, or even
176 want to participate in LyX development, you may find some interesting informati
180 \begin_layout Chapter
184 \begin_layout Standard
185 LyX uses several custom file formats for configuration files and documents.
186 This chapter contains some background concerning these file formats.
187 Several file formats are also described in detail in the regular user documenta
191 \begin_layout Section
195 \begin_layout Section
196 When is an update of the .lyx file format number needed?
199 \begin_layout Standard
200 When you ware working on a new feature you may ask yourself whether it needs
201 an update of the .lyx file format number.
202 Whether an update is needed or not is not always obvious.
203 Below you can find a list of reasons for file format updates with explanations:
206 \begin_layout Description
215 setting Whenever you introduce a new setting that is stored in the document
216 header, a file format update is needed.
217 This is also true if you add a new valid value to an existing setting,
219 a new language that is stored in
220 \begin_inset Flex Code
223 \begin_layout Plain Layout
234 \begin_layout Description
243 setting If a certain setting becomes obsolete and gets removed, a file format
247 \begin_layout Description
252 inset Of course a new inset requires a file format update.
255 \begin_layout Description
260 style in any layout file or module shipped with LyX, or new shipped layout
262 These requirements are currently under discussion and might change in the
266 \begin_layout Description
279 package Any new math package that is automatically loaded needs a file format
281 The reason for this is that there is no true ERT inset for math formulas:
282 Each command is parsed, and if a user happens to defne a local command
283 with the same name as a command that triggers an automatic load of a package,
284 he needs to be able to switch off the automatic loading of that package.
285 This switch is stored by the
286 \begin_inset Flex Code
289 \begin_layout Plain Layout
298 \begin_layout Standard
299 If you are still unsure, please ask on the development list.
302 \begin_layout Section
303 How to update the file format number of .lyx files
306 \begin_layout Standard
307 Once you came to the conclusion that a file format update is needed you
308 should use the following procedure to perform the update:
311 \begin_layout Enumerate
312 Implement and test the new feature, including the reading and writing of
314 Note that any file produced at this stage does not use a valid format,
315 so do not use this version of LyX for working on any important documents.
318 \begin_layout Enumerate
319 Describe the new format in
320 \begin_inset Flex Code
323 \begin_layout Plain Layout
332 \begin_layout Enumerate
333 Update the LyX file format number in
334 \begin_inset Flex Code
337 \begin_layout Plain Layout
346 \begin_layout Enumerate
347 Add an entry to both format lists (for conversion and reversion) in
348 \begin_inset Flex Code
351 \begin_layout Plain Layout
352 lib/lyx2lyx_lyx2lyx_2_1.py
358 Add a conversion routine if needed (e.g.
359 a new header setting always needs a conversion that adds the new setting,
360 a new document language does not need one).
361 Add a reversion routine if needed.
362 While the conversion routine is required to produce a document that is
363 equivalent to the old version, the requirements of the reversion are not
365 If possible, try to produce a proper reversion, using ERT if needed, but
366 for some features this might be too complicated.
367 In this case, the minimum requirement of the reversion routine is that
368 it produces a valid document which can be read by an older LyX.
369 If absolutely needed, even data loss is allowed for the reversion.
372 \begin_layout Enumerate
373 Since tex2lyx has several implicit file format dependencies caused by sharing
374 code with LyX, updating the file format of .lyx files produced by tex2lyx
375 at the same time as updating the main .lyx file format is strongly recommended.
376 Therefore, a compiler warning will be issued if the LyX and tex2lyx .lyx
377 file format numbers differ.
378 In many cases the tex2lyx update requires only the first and last item
383 \begin_layout Enumerate
384 Update the tex2lyx file format number in
385 \begin_inset Flex Code
388 \begin_layout Plain Layout
397 \begin_layout Enumerate
398 If the lyx2lyx conversion from the old to the new format is empty, or if
399 tex2lyx does not yet output the changed feature, you do not need any further
401 Otherwise, search for the changed feature in tex2lyx, and adjust the output
402 according to the lyx2lyx changes.
405 \begin_layout Enumerate
406 Update the tex2lyx test references as described in
407 \begin_inset CommandInset ref
408 LatexCommand formatted
409 reference "sec:Updating-test-references"
417 \begin_layout Enumerate
418 If you did not implement full tex2lyx support of the new feature, add a
420 \begin_inset Flex Code
423 \begin_layout Plain Layout
429 describing the missing bits.
430 Note that it is perfectly fine if you do not add full tex2lyx support for
431 a new feature: The updating recommendation above is only issued for the
432 syntax of the produced .lyx file.
433 It is no problem if some features supported by LyX are still output as
434 ERT by tex2lyx, since the problems in the past that resulted in the update
435 recommendation were related to mixed version syntax, not ERT.
438 \begin_layout Chapter
442 \begin_layout Standard
443 Automated tests are an important tool to detect bugs and regressions in
444 software development.
445 Some projects like gcc even require each bug fix to be accompanied by a
446 test case for the automatic test suite, that would detect this bug.
447 Testing interactive features automatically is of course very hard, but
448 core functionality like document import and export can be tested quite
449 easily, and some tests of this kind exist.
452 \begin_layout Section
456 \begin_layout Standard
457 Some tests are located in the
458 \begin_inset Flex Code
461 \begin_layout Plain Layout
462 development/autotests
467 subfolder of the LyX source code distribution.
470 \begin_layout Subsection
474 \begin_layout Standard
475 The LyX tests can be run by the commands
476 \begin_inset Flex Code
479 \begin_layout Plain Layout
486 \begin_inset Flex Code
489 \begin_layout Plain Layout
495 subfolder of the build directory.
496 \begin_inset Note Note
499 \begin_layout Plain Layout
500 FIXME: Is this possible with autotools?
508 \begin_layout Section
512 \begin_layout Standard
513 The tex2lyx tests are located in the
514 \begin_inset Flex Code
517 \begin_layout Plain Layout
523 subfolder of the LyX source code distribution.
524 The actual testing is performed by the simple python script
525 \begin_inset Flex Code
528 \begin_layout Plain Layout
529 src/tex2lyx/test/runtests.py
535 Each test consists of two files:
536 \begin_inset Flex Code
539 \begin_layout Plain Layout
545 contains the LaTeX code that should be tested.
547 \begin_inset Flex Code
550 \begin_layout Plain Layout
556 contains the expected output of tex2lyx.
557 When a test is run, the actual produced output is compared with the stored
559 The test passes if both are identical.
560 The test machinery is also able to generate a file
561 \begin_inset Flex Code
564 \begin_layout Plain Layout
570 by exporting the produced .lyx file with LyX again.
571 This may be useful for roundtrip comparisons.
574 \begin_layout Subsection
578 \begin_layout Standard
579 The tex2lyx tests can be run by the commands
580 \begin_inset Flex Code
583 \begin_layout Plain Layout
590 \begin_inset Flex Code
593 \begin_layout Plain Layout
600 \begin_inset Flex Code
603 \begin_layout Plain Layout
609 subfolder of the build directory.
610 If a test fails, the differences between the expected and actual results
611 are output in unified diff format.
614 \begin_layout Subsection
615 Updating test references
616 \begin_inset CommandInset label
618 name "sec:Updating-test-references"
625 \begin_layout Standard
626 In some cases a changed tex2lyx output is not a test failure, but wanted,
628 if a tex2lyx bug was fixed, or a new feature was added.
629 In these cases the stored references need to be updated.
631 \begin_inset Flex Code
634 \begin_layout Plain Layout
641 \begin_inset Note Note
644 \begin_layout Plain Layout
645 FIXME: Add cmake command
651 \begin_inset Flex Code
654 \begin_layout Plain Layout
660 subfolder of the build directory.
661 For convenience, this command does also produce re-exported roundtrip .lyx.tex
663 Please examine the changed output carefully before committing the changed
664 files to the repository: Since the test machinery does not do a roundtrip
666 \begin_inset Formula $\Rightarrow$
670 \begin_inset Formula $\Rightarrow$
673 .tex, and does not compare the produced dvi or pdf output, it assumes that
674 the stored .lyx reference produces correct output if processed by LyX.
675 There is only one chance to detect wrong output: before committing a new
677 Once it is committed, it is quite difficult to verify whether it is correct.
680 \begin_layout Subsection
684 \begin_layout Standard
685 In many cases tests for new features may be added to one of the existing
686 test files, but sometimes this is not possible or not wanted.
687 Then a new test file needs to be added:
690 \begin_layout Enumerate
692 \begin_inset Flex Code
695 \begin_layout Plain Layout
696 src/tex2lyx/test/<test name>.tex
701 and run tex2lyx in roundtrip mode to produce the file
702 \begin_inset Flex Code
705 \begin_layout Plain Layout
706 src/tex2lyx/test/<test name>.lyx.lyx
712 This file will be the new reference.
715 \begin_layout Enumerate
716 Once you confirmed that the tex2lyx output is correct, add the new files
717 to the corresponding lists in
718 \begin_inset Flex Code
721 \begin_layout Plain Layout
722 src/tex2lyx/test/runtests.py
728 \begin_inset Flex Code
731 \begin_layout Plain Layout
732 src/tex2lyx/Makefile.am
738 \begin_inset Flex Code
741 \begin_layout Plain Layout
742 src/tex2lyx/test/CMakeLists.txt
750 \begin_layout Enumerate
751 Commit the changes to the repository, or send a patch to the development
752 list and ask for committing if you do not have commit rights.