From 1fde43b690157964774490bb46c606a5dd9ed38b Mon Sep 17 00:00:00 2001 From: Georg Baum Date: Sat, 16 Feb 2013 16:59:26 +0100 Subject: [PATCH] Add development manual. This is rather incomplete, and will hopefully be extended in the future. Currently, its main purpose is to document file format updates and tests. --- lib/doc/Development.lyx | 756 ++++++++++++++++++++++++++++++++++++++++ lib/doc/Makefile.am | 1 + 2 files changed, 757 insertions(+) create mode 100644 lib/doc/Development.lyx diff --git a/lib/doc/Development.lyx b/lib/doc/Development.lyx new file mode 100644 index 0000000000..f16e8bba3d --- /dev/null +++ b/lib/doc/Development.lyx @@ -0,0 +1,756 @@ +#LyX 2.1 created this file. For more info see http://www.lyx.org/ +\lyxformat 462 +\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 false +\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 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 numerical +\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.1.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 + +\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? +\end_layout + +\begin_layout Standard +When you ware 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.g. + 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 Flex Code +status collapsed + +\begin_layout Plain Layout +lib/lyx2lyx_lyx2lyx_2_1.py +\end_layout + +\end_inset + +. + Add a conversion routine if needed (e.g. + 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 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 +.tex +\end_layout + +\end_inset + + contains the LaTeX code that should be tested. + +\begin_inset Flex Code +status collapsed + +\begin_layout Plain Layout +.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 +.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 check +\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.g. + 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, call +\begin_inset Flex Code +status collapsed + +\begin_layout Plain Layout +make updatetests +\end_layout + +\end_inset + + (autotools) +\begin_inset Note Note +status open + +\begin_layout Plain Layout +FIXME: Add cmake command +\end_layout + +\end_inset + + in the +\begin_inset Flex Code +status collapsed + +\begin_layout Plain Layout +src/tex2lyx +\end_layout + +\end_inset + + subfolder of the build directory. + For convenience, this command does 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 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/.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/.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 + +\end_body +\end_document diff --git a/lib/doc/Makefile.am b/lib/doc/Makefile.am index 8ce2e77031..9c4fa1a6a1 100644 --- a/lib/doc/Makefile.am +++ b/lib/doc/Makefile.am @@ -6,6 +6,7 @@ docdir = $(pkgdatadir)/doc dist_doc_DATA = \ Additional.lyx \ Customization.lyx \ + Development.lyx \ DummyTextDocument.txt \ DummyDocument1.lyx \ DummyDocument2.lyx \ -- 2.39.5