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 true
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
73 \use_package mathdots 1
74 \use_package mathtools 0
76 \use_package stackrel 0
77 \use_package stmaryrd 0
78 \use_package undertilde 0
80 \cite_engine_type default
84 \paperorientation portrait
88 \notefontcolor #0000ff
95 \paragraph_separation indent
96 \paragraph_indentation default
97 \quotes_language english
100 \paperpagestyle headings
101 \tracking_changes false
102 \output_changes false
114 \begin_layout Subtitle
123 \begin_layout Plain Layout
125 If you have comments or error corrections, please send them to the LyX Documenta
127 \begin_inset Flex Code
130 \begin_layout Plain Layout
132 <lyx-docs@lists.lyx.org>
145 \begin_layout Standard
146 \begin_inset CommandInset toc
147 LatexCommand tableofcontents
154 \begin_layout Chapter
158 \begin_layout Standard
159 This manual documents some aspects of LyX development.
160 It is currently rather incomplete, but will hopefully be extended in the
162 Meanwhile, additional information can be found in the
163 \begin_inset Flex Code
166 \begin_layout Plain Layout
172 subfolder of the LyX source code distribution.
173 This document is not translated, since the development language of LyX
175 If you want to use LyX you don't need to read this manual.
176 However, if you want to learn more about how LyX is developed, or even
177 want to participate in LyX development, you may find some interesting informati
181 \begin_layout Chapter
185 \begin_layout Standard
186 LyX uses several custom file formats for configuration files and documents.
187 This chapter contains some background concerning these file formats.
188 Several file formats are also described in detail in the regular user documenta
192 \begin_layout Section
196 \begin_layout Section
197 When is an update of the .lyx file format number needed?
198 \begin_inset CommandInset label
200 name "sec:When-is-an"
207 \begin_layout Standard
208 When you are working on a new feature you may ask yourself whether it needs
209 an update of the .lyx file format number.
210 Whether an update is needed or not is not always obvious.
211 Below you can find a list of reasons for file format updates with explanations:
214 \begin_layout Description
223 setting Whenever you introduce a new setting that is stored in the document
224 header, a file format update is needed.
225 This is also true if you add a new valid value to an existing setting,
227 \begin_inset space \thinspace{}
231 \begin_inset space \space{}
234 a new language that is stored in
235 \begin_inset Flex Code
238 \begin_layout Plain Layout
249 \begin_layout Description
258 setting If a certain setting becomes obsolete and gets removed, a file format
262 \begin_layout Description
267 inset Of course a new inset requires a file format update.
270 \begin_layout Description
275 style in any layout file or module shipped with LyX, or new shipped layout
277 These requirements are currently under discussion and might change in the
281 \begin_layout Description
294 package Any new math package that is automatically loaded needs a file format
296 The reason for this is that there is no true ERT inset for math formulas:
297 Each command is parsed, and if a user happens to defne a local command
298 with the same name as a command that triggers an automatic load of a package,
299 he needs to be able to switch off the automatic loading of that package.
300 This switch is stored by the
301 \begin_inset Flex Code
304 \begin_layout Plain Layout
313 \begin_layout Standard
314 If you are still unsure, please ask on the development list.
317 \begin_layout Section
318 How to update the file format number of .lyx files
321 \begin_layout Standard
322 Once you came to the conclusion that a file format update is needed you
323 should use the following procedure to perform the update:
326 \begin_layout Enumerate
327 Implement and test the new feature, including the reading and writing of
329 Note that any file produced at this stage does not use a valid format,
330 so do not use this version of LyX for working on any important documents.
333 \begin_layout Enumerate
334 Describe the new format in
335 \begin_inset Flex Code
338 \begin_layout Plain Layout
347 \begin_layout Enumerate
348 Update the LyX file format number in
349 \begin_inset Flex Code
352 \begin_layout Plain Layout
361 \begin_layout Enumerate
362 Add an entry to both format lists (for conversion and reversion) in
363 \begin_inset Newline newline
367 \begin_inset Flex Code
370 \begin_layout Plain Layout
371 lib/lyx2lyx/lyx_2_2.py
377 Add a conversion routine if needed (e.
378 \begin_inset space \thinspace{}
382 \begin_inset space \space{}
385 a new header setting always needs a conversion that adds the new setting,
386 a new document language does not need one).
387 Add a reversion routine if needed.
388 While the conversion routine is required to produce a document that is
389 equivalent to the old version, the requirements of the reversion are not
391 If possible, try to produce a proper reversion, using ERT if needed, but
392 for some features this might be too complicated.
393 In this case, the minimum requirement of the reversion routine is that
394 it produces a valid document which can be read by an older LyX.
395 If absolutely needed, even data loss is allowed for the reversion.
398 \begin_layout Enumerate
399 Since tex2lyx has several implicit file format dependencies caused by sharing
400 code with LyX, updating the file format of .lyx files produced by tex2lyx
401 at the same time as updating the main .lyx file format is strongly recommended.
402 Therefore, a compiler warning will be issued if the LyX and tex2lyx .lyx
403 file format numbers differ.
404 In many cases the tex2lyx update requires only the first and last item
409 \begin_layout Enumerate
410 Update the tex2lyx file format number in
411 \begin_inset Flex Code
414 \begin_layout Plain Layout
423 \begin_layout Enumerate
424 If the lyx2lyx conversion from the old to the new format is empty, or if
425 tex2lyx does not yet output the changed feature, you do not need any further
427 Otherwise, search for the changed feature in tex2lyx, and adjust the output
428 according to the lyx2lyx changes.
431 \begin_layout Enumerate
432 Update the tex2lyx test references as described in
433 \begin_inset CommandInset ref
434 LatexCommand formatted
435 reference "sec:Updating-test-references"
443 \begin_layout Enumerate
444 If you did not implement full tex2lyx support of the new feature, add a
446 \begin_inset Flex Code
449 \begin_layout Plain Layout
455 describing the missing bits.
456 Note that it is perfectly fine if you do not add full tex2lyx support for
457 a new feature: The updating recommendation above is only issued for the
458 syntax of the produced .lyx file.
459 It is no problem if some features supported by LyX are still output as
460 ERT by tex2lyx, since the problems in the past that resulted in the update
461 recommendation were related to mixed version syntax, not ERT.
464 \begin_layout Section
465 Backporting new styles to the stable version
468 \begin_layout Standard
469 Starting with the stable LyX 2.1 branch, there is a mechanism in place to
470 backport new styles to the stable version without the need to update the
472 The basic idea is that the new style definition is automatically copied
473 to the document preamble, so that it can even be used by older minor revisions
474 that did not yet include the style.
475 To backport a new style to the stable version, the following steps are
479 \begin_layout Enumerate
481 \begin_inset Flex Code
484 \begin_layout Plain Layout
490 to the style definition in the development version.
493 \begin_layout Enumerate
494 Copy the style definition to the stable version, but use
495 \begin_inset Flex Code
498 \begin_layout Plain Layout
505 If needed adjust the format to the one used by the stable version (see
506 the customization manual for details of the layout file format).
509 \begin_layout Enumerate
510 For each update of the style in a later stable version, increase the argument
512 \begin_inset Flex Code
515 \begin_layout Plain Layout
521 by one (in the stable version, the development version should not be touched).
524 \begin_layout Standard
525 For details about the
526 \begin_inset Flex Code
529 \begin_layout Plain Layout
535 flag see the customization manual.
537 \begin_inset Flex Code
540 \begin_layout Plain Layout
546 support is needed for backported styles: Since the style of the development
547 version has an infinite version number, it will always be used.
548 Furthermore, since its version number is less than one, the style will
549 not be written anymore to the document header for files saved by the new
553 \begin_layout Chapter
557 \begin_layout Standard
558 Automated tests are an important tool to detect bugs and regressions in
559 software development.
560 Some projects like gcc even require each bug fix to be accompanied by a
561 test case for the automatic test suite, that would detect this bug.
562 Testing interactive features automatically is of course very hard, but
563 core functionality like document import and export can be tested quite
564 easily, and some tests of this kind exist.
567 \begin_layout Section
571 \begin_layout Standard
572 Some tests are located in the
573 \begin_inset Flex Code
576 \begin_layout Plain Layout
577 development/autotests
582 subfolder of the LyX source code distribution.
585 \begin_layout Subsection
589 \begin_layout Standard
590 The LyX tests can be run by the commands
591 \begin_inset Flex Code
594 \begin_layout Plain Layout
601 \begin_inset Flex Code
604 \begin_layout Plain Layout
610 subfolder of the build directory.
611 \begin_inset Note Note
614 \begin_layout Plain Layout
615 FIXME: Is this possible with autotools?
623 \begin_layout Section
627 \begin_layout Standard
628 The tex2lyx tests are located in the
629 \begin_inset Flex Code
632 \begin_layout Plain Layout
638 subfolder of the LyX source code distribution.
639 The actual testing is performed by the simple python script
640 \begin_inset Flex Code
643 \begin_layout Plain Layout
644 src/tex2lyx/test/runtests.py
650 Each test consists of two files:
651 \begin_inset Flex Code
654 \begin_layout Plain Layout
660 contains the LaTeX code that should be tested.
662 \begin_inset Flex Code
665 \begin_layout Plain Layout
671 contains the expected output of tex2lyx.
672 When a test is run, the actual produced output is compared with the stored
674 The test passes if both are identical.
675 The test machinery is also able to generate a file
676 \begin_inset Flex Code
679 \begin_layout Plain Layout
685 by exporting the produced .lyx file with LyX again.
686 This may be useful for roundtrip comparisons.
689 \begin_layout Subsection
693 \begin_layout Standard
694 The tex2lyx tests can be run by the commands
695 \begin_inset Flex Code
698 \begin_layout Plain Layout
705 \begin_inset Flex Code
708 \begin_layout Plain Layout
715 \begin_inset Flex Code
718 \begin_layout Plain Layout
724 subfolder of the build directory.
725 If a test fails, the differences between the expected and actual results
726 are output in unified diff format.
729 \begin_layout Subsection
730 Updating test references
731 \begin_inset CommandInset label
733 name "sec:Updating-test-references"
740 \begin_layout Standard
741 In some cases a changed tex2lyx output is not a test failure, but wanted,
743 \begin_inset space \thinspace{}
747 \begin_inset space \space{}
750 if a tex2lyx bug was fixed, or a new feature was added.
751 In these cases the stored references need to be updated.
753 \begin_inset Flex Code
756 \begin_layout Plain Layout
763 \begin_inset Note Note
766 \begin_layout Plain Layout
767 FIXME: Add cmake command
773 \begin_inset Flex Code
776 \begin_layout Plain Layout
782 subfolder of the build directory.
783 For convenience, this command does also produce re-exported roundtrip .lyx.tex
785 Please examine the changed output carefully before committing the changed
786 files to the repository: Since the test machinery does not do a roundtrip
788 \begin_inset Formula $\Rightarrow$
792 \begin_inset Formula $\Rightarrow$
795 .tex, and does not compare the produced dvi or pdf output, it assumes that
796 the stored .lyx reference produces correct output if processed by LyX.
797 There is only one chance to detect wrong output: before committing a new
799 Once it is committed, it is quite difficult to verify whether it is correct.
802 \begin_layout Subsection
806 \begin_layout Standard
807 In many cases tests for new features may be added to one of the existing
808 test files, but sometimes this is not possible or not wanted.
809 Then a new test file needs to be added:
812 \begin_layout Enumerate
814 \begin_inset Flex Code
817 \begin_layout Plain Layout
818 src/tex2lyx/test/<test name>.tex
823 and run tex2lyx in roundtrip mode to produce the file
824 \begin_inset Flex Code
827 \begin_layout Plain Layout
828 src/tex2lyx/test/<test name>.lyx.lyx
834 This file will be the new reference.
837 \begin_layout Enumerate
838 Once you confirmed that the tex2lyx output is correct, add the new files
839 to the corresponding lists in
840 \begin_inset Flex Code
843 \begin_layout Plain Layout
844 src/tex2lyx/test/runtests.py
850 \begin_inset Flex Code
853 \begin_layout Plain Layout
854 src/tex2lyx/Makefile.am
860 \begin_inset Flex Code
863 \begin_layout Plain Layout
864 src/tex2lyx/test/CMakeLists.txt
872 \begin_layout Enumerate
873 Commit the changes to the repository, or send a patch to the development
874 list and ask for committing if you do not have commit rights.
877 \begin_layout Chapter
881 \begin_layout Standard
882 This chapter lists some guidelines that should be followed.
883 This list is not complete, and many guidelines are in separate chapters,
885 \begin_inset Quotes eld
888 When is an update of the .lyx file format number needed?
889 \begin_inset Quotes erd
893 \begin_inset CommandInset ref
895 reference "sec:When-is-an"
902 \begin_layout Section
903 When to set a fixed milestone?
906 \begin_layout Standard
907 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
911 \begin_layout Enumerate
912 Somebody is actively working on a fix.
915 \begin_layout Enumerate
916 The bug is so severe that it would block the release if it is not fixed.
919 \begin_layout Standard
920 If a bug is important, but nobody is working on it, and it is no showstopper,
921 use a milestone like 2.1.x or 2.2.x.
922 For all other bugs, do not set a milestone at all.
925 \begin_layout Section
926 Can we add rc entries in stable branch?
929 \begin_layout Standard
931 We are supposed to increase the prefs2prefs version number with such things.
934 \begin_layout Chapter
935 Documentation policies
938 \begin_layout Standard
939 The main documentation consists of these files:
942 \begin_layout Description
943 splash.lyx it is the first file you see after an installation.
944 We assume that a new user sees this.
945 It is therefore designed to be as simple as possible.
946 Therefore please don't add any new formatting, only fix typos etc.
947 Splash.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
950 \begin_layout Description
951 Intro.lyx This is the manual new users will read to learn LyX.
952 It therefore uses a limited set of formatting.
953 For example a standard document class.
954 Since new users will first learn about the formatting possibilities of
955 LyX please keep this file that simple.
956 Intro.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
959 \begin_layout Description
960 Tutorial.lyx our tutorial.
961 It must be always up to date.
962 Normally there is nothing to add since we don't want to overwhelm new users
963 with too much details.
964 The will learn these details while using LyX and we have special manuals.
965 Tutorial.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
968 \begin_layout Description
969 UserGuide.lyx our main user guide.
970 It covers a mixture of basic and detailed information.
971 Some information is also in the Math and EmbeddedObjects manual so that
972 the UserGuide refers to these files.
973 UserGuide.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
976 \begin_layout Description
977 EmbeddedObjects.lyx a special manual to explain things like tables floats
980 EmbeddedObjects.lyx is up to date for LyX 2.1.x, currently maintained by Uwe
984 \begin_layout Description
985 Math.lyx a special manual to explain everything regarding math in all detail.
986 Math.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
989 \begin_layout Description
990 Additional.lyx this manual covers information that would be too much detail
991 for the UserGuide or would make the UserGuide uncompilable or only compilable
992 when installing a lot of special LaTeX-packages.
993 What should be in the UserGuide or better in Additional is a matter of
995 it is up to you to decide that.
996 Additional.lyx is not completely up to date for LyX 2.1.x.
1001 8 is up to date and currently maintained by Uwe Stöhr.
1002 It certainly needs a rewrite and update.
1003 For example many info in chapter
1004 \begin_inset space ~
1007 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
1011 \begin_layout Description
1012 Customization.lyx this manual covers information how to customize LyX for
1013 certain output formats, operating systems, languages etc.
1014 It is currently completely out of date and needs a major rewrite and update.
1015 If you do this please assure that your information are given for all OSes
1016 and LaTeX distributions (meaning be as objective as possible).
1019 \begin_layout Standard
1021 \begin_inset space ~
1024 rules in editing the docs:
1027 \begin_layout Enumerate
1028 If you are not the maintainer of a doc file or a chapter/section, you MUST
1029 use change tracking so that the maintainer could review your changes
1032 \begin_layout Enumerate
1033 Respect the formatting of the document.
1034 The different files use different formatting styles.
1035 That is OK and has historic reasons nobody fully know ;-).
1036 But it is important to be consistent within one file.
1039 \begin_layout Enumerate
1040 All changes you make to a file in one language MUST also go the file in
1041 the other actively maintained languages.
1042 Normally the maintainer does this for you, if you are the maintainer, you
1043 must do this by copying or changing the changed or added text to the other
1044 files so that the translators sees the blue underlined text and know what
1045 they have to translate and what was changed.
1048 \begin_layout Enumerate
1049 You MUST assure that the document is compilable as
1050 \begin_inset Quotes eld
1054 \begin_inset Quotes erd