X-Git-Url: https://git.lyx.org/gitweb/?a=blobdiff_plain;f=lib%2Fdoc%2FDevelopment.lyx;h=18f0861f1579fb849dd7e73c508372ed799da1ba;hb=239b9919ffe28338d789e6dc9122228f77ab77a7;hp=326c90a38e40a8e6140a839ad9aa2f7293367658;hpb=95169b10009494b069acedae2b6cce7c55f8df2a;p=lyx.git diff --git a/lib/doc/Development.lyx b/lib/doc/Development.lyx index 326c90a38e..18f0861f15 100644 --- a/lib/doc/Development.lyx +++ b/lib/doc/Development.lyx @@ -1,5 +1,5 @@ -#LyX 2.2 created this file. For more info see http://www.lyx.org/ -\lyxformat 507 +#LyX 2.3 created this file. For more info see http://www.lyx.org/ +\lyxformat 527 \begin_document \begin_header \save_transient_properties true @@ -25,6 +25,7 @@ logicalmkup \font_osf false \font_sf_scale 100 100 \font_tt_scale 100 100 +\use_microtype false \graphics default \default_output_format pdf2 \output_sync 1 @@ -77,7 +78,8 @@ logicalmkup \tocdepth 4 \paragraph_separation indent \paragraph_indentation default -\quotes_language english +\quotes_style english +\dynamic_quotes 0 \papercolumns 1 \papersides 2 \paperpagestyle headings @@ -201,6 +203,16 @@ name "sec:When-is-an" 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. + Rule of thumb: +\end_layout + +\begin_layout Quote +Whenever there is the danger that a previous version of LyX cannot open + a file using the new feature, a file format update is needed. +\end_layout + +\begin_layout Standard +The file format change allows lyx2lyx rules to implement backwards compatibility. Below you can find a list of reasons for file format updates with explanations: \end_layout @@ -215,16 +227,92 @@ document 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. +\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 + +valid +\begin_inset space ~ +\end_inset + +value +\begin_inset space ~ +\end_inset + +for +\begin_inset space ~ +\end_inset + +an +\begin_inset space ~ +\end_inset + +existing +\begin_inset space ~ +\end_inset + +setting, e. \begin_inset space \thinspace{} \end_inset g. -\begin_inset space \space{} +\end_layout + +\begin_deeper +\begin_layout Description +\paragraph_spacing single +Automatically +\begin_inset space ~ +\end_inset + +loaded +\begin_inset space ~ +\end_inset + +math +\begin_inset space ~ +\end_inset + +package 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 define a local + command with the same name as a command that triggers an automatic load + of a package, they need 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 Description +New +\begin_inset space ~ \end_inset -a new language that is stored in +language that is stored in \begin_inset Flex Code status collapsed @@ -237,21 +325,20 @@ language \end_inset . + +\begin_inset Note Note +status collapsed + +\begin_layout Plain Layout +This requirement is under discussion. \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 +\end_deeper \begin_layout Description New \begin_inset space ~ @@ -288,39 +375,27 @@ Removed style If a style or inset layout is removed in any layout file or module shipped with \SpecialChar LyX -, then a new file format is required. +, a new file format is required. \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 define a local command - with the same name as a command that triggers an automatic load of a package, - they need 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 +\begin_layout Standard +However, +\series bold +new +\series default + layouts and modules do +\series bold +not +\series default + require a file format update (changed 03/16, see +\begin_inset CommandInset ref +LatexCommand ref +reference "subsec:New-layouts" \end_inset - header setting. +). + \end_layout \begin_layout Standard @@ -385,30 +460,6 @@ src/version.h . \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 \begin_inset CommandInset label LatexCommand label @@ -539,7 +590,8 @@ name "enu:updatefiles" \end_inset -Update LyX's .lyx documentation files to the new format. +Test your lyx2lyx code by updating 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 @@ -613,7 +665,52 @@ gen_lfuns.py \end_inset before being converted to the latest format. - Finally, commit using +\begin_inset Newline newline +\end_inset + + +\begin_inset Note Greyedout +status open + +\begin_layout Plain Layout + +\series bold +Note: +\series default + Only commit file format changes in the doc files if these files are using + the new feature of the new file format. + The reason is rule +\begin_inset space ~ +\end_inset + + +\begin_inset CommandInset ref +LatexCommand ref +reference "enu:The-fileformat-of" + +\end_inset + + of the documentation policies described in sec. +\begin_inset space ~ +\end_inset + + +\begin_inset CommandInset ref +LatexCommand ref +reference "sec:Documentation-policies" + +\end_inset + +. +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Enumerate +Finally, commit using \begin_inset Flex Code status collapsed @@ -670,7 +767,7 @@ updatedocs.py \end_layout \begin_layout Standard -Note that we do not automatically any local layout used in the +Note that we do not automatically update any local layout used in the \begin_inset Flex Code status collapsed @@ -1029,41 +1126,6 @@ lyx2lyx New layouts and modules \end_layout -\begin_layout Standard -\begin_inset Note Greyedout -status open - -\begin_layout Description -Note: This section is currently only a proposal under discussion. - Please correct/amend as suited. - Remove this note once a consensus is found. -\end_layout - -\begin_layout Plain Layout -Summary of a recent discussion in lyx-devel by GM. -\end_layout - -\begin_layout Plain Layout -See the thread -\begin_inset Quotes eld -\end_inset - -Proposal for a guide on updating layouts -\begin_inset Quotes erd -\end_inset - - for details and background -\end_layout - -\begin_layout Plain Layout -http://permalink.gmane.org/gmane.editors.lyx.devel/161126 -\end_layout - -\end_inset - - -\end_layout - \begin_layout Subsection \begin_inset CommandInset label LatexCommand label @@ -1105,8 +1167,7 @@ target "https://wiki.lyx.org/Layouts/Layouts" \begin_layout Standard In older versions of this document, it was stated that new layout files require a file format change. - After some discussion it was decided that this is not needed. - For reference, here are the arguments on each side: + After some discussion, it was decided that this is not needed. \begin_inset Foot status open @@ -1114,7 +1175,7 @@ status open See \begin_inset CommandInset href LatexCommand href -name "this thread" +name "the thread “Proposal for a guide on updating layouts”" target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202" \end_inset @@ -1124,9 +1185,14 @@ target "http://permalink.gmane.org/gmane.editors.lyx.devel/161202" \end_inset + +\end_layout +\begin_layout Quote +For reference, here are the arguments on each side \end_layout +\begin_deeper \begin_layout Description Pro \begin_inset Quotes eld @@ -1140,8 +1206,15 @@ New layout files are a file format change \end_layout \begin_layout Itemize -All documents produced by 2.2.x can always be edited and exported even if - x is different. +All documents produced by 2.2. +\begin_inset Formula $x$ +\end_inset + + can always be edited and exported even if +\begin_inset Formula $x$ +\end_inset + + is different. This is important for people using different machines, or exchanging work with colleagues. \end_layout @@ -1173,15 +1246,10 @@ We have the same situation already with custom layout files: If a document \end_layout \begin_layout Itemize -The lyx2lyx script cannot do anything useful on backward conversion in such - a case, and the forward conversion would be a no-op. -\end_layout - -\begin_layout Standard -As said, consensus has been reached that the reasons in favor of not requiring - a file format change are more compelling. +The lyx2lyx script cannot do anything useful in such a case. \end_layout +\end_deeper \begin_layout Standard If you have decided that you are going to add a new layout file to \SpecialChar LyX itself, @@ -1201,7 +1269,7 @@ lib/layouts/ and add it to Git ( \begin_inset Flex Code -status open +status collapsed \begin_layout Plain Layout git add lib/layouts/newlayout.layout @@ -1246,13 +1314,11 @@ Found: [InsetInfo] \end_layout \begin_layout Standard -\paragraph_spacing single where [InsetInfo] is obtained by entering in the minibuffer (Alt+X) \begin_inset Flex Code status collapsed \begin_layout Plain Layout -\paragraph_spacing single info-insert textclass \end_layout @@ -1280,7 +1346,9 @@ no \end_deeper \begin_layout Enumerate -Add a template or example file to +A template or example is strongly encouraged (but not necessarily required). + It is also possible to provide both. + Add them to \begin_inset Flex Code status collapsed @@ -1364,6 +1432,37 @@ Modules do not need a template, only an example, which is strongly encouraged Layouts for document classes with incompatible versions \end_layout +\begin_layout Standard +\begin_inset Note Greyedout +status open + +\begin_layout Description +Note: This section is currently only a proposal under discussion. + Please correct/amend as suited. + Remove this note once a consensus is found. +\end_layout + +\begin_layout Plain Layout +See the thread +\begin_inset Quotes eld +\end_inset + +Proposal for a guide on updating layouts +\begin_inset Quotes erd +\end_inset + + for details and background +\end_layout + +\begin_layout Plain Layout +http://permalink.gmane.org/gmane.editors.lyx.devel/161126 +\end_layout + +\end_inset + + +\end_layout + \begin_layout Standard Every now and then, there are changes to LaTeX document classes that break backwards compatibility. @@ -1452,10 +1551,9 @@ This point was also made here: http://permalink.gmane.org/gmane.editors.lyx.deve \end_layout -\begin_layout Standard -Moreover, because the layout file is completely new, it can be added both - to the master and the stable branches, in accord with the policy discussed - in +\begin_layout Itemize +The new layout can be added both to the master and the stable branches, + in accord with the policy discussed in \begin_inset CommandInset ref LatexCommand formatted reference "subsec:New-layouts" @@ -1467,8 +1565,8 @@ reference "subsec:New-layouts" \end_layout \begin_layout Standard -The user can then move an existing document to the new version simply by - selecting a new document class. +The user can move an existing document to the new version simply by selecting + a new document class. This step is well supported by \SpecialChar LyX , with established methods for handling unsupported styles and other changes. @@ -1508,7 +1606,7 @@ status collapsed file as an optional argument in the \begin_inset Flex Code -status open +status collapsed \begin_layout Plain Layout @@ -1542,8 +1640,8 @@ DeclareLaTeXClass[acmsiggraph]{ACM SIGGGRAPH (v. \end_layout \begin_layout Itemize -Update the GUI name in the old layout file (whose name should not have been - changed), e.g.: +Update the GUI name in the old layout file (whose name should not be changed), + e.g.: \begin_inset Newline newline \end_inset @@ -1581,9 +1679,9 @@ Input remove\SpecialChar breakableslash obsolete\SpecialChar breakableslash modify settings and styles (similar - to inclusion of + to the inclusion of \begin_inset Flex Code -status open +status collapsed \begin_layout Plain Layout *.inc @@ -1931,13 +2029,26 @@ src/tex2lyx/test \end_layout \begin_layout Itemize -In the appearing MSVC program right-click on the project +In the appearing MSVC program assure that you build the +\emph on +Release +\emph default + version, then right-click on the project \family sans updatetex2lyxtests \family default - in the project explorer and chose + in the project explorer and choose then \family sans -Create +Project +\begin_inset space ~ +\end_inset + +Only\SpecialChar menuseparator +Rebuild +\begin_inset space ~ +\end_inset + +only \family default . \end_layout @@ -3119,7 +3230,7 @@ status collapsed status collapsed \begin_layout Plain Layout -development/autotests/suspiciousTests +development/autotests/invertedTests \end_layout \end_inset @@ -3259,15 +3370,15 @@ inverted \emph on uninvert \emph default - the test by removing the labeling pattern from + the test by removing the pattern from the \begin_inset Quotes eld \end_inset -suspiciousTests +invertedTests \begin_inset Quotes erd \end_inset -) (see + file) (see \begin_inset CommandInset ref LatexCommand ref reference "par:Inverted-tests" @@ -3279,11 +3390,15 @@ reference "par:Inverted-tests" \begin_layout Itemize If the export did not fail previously but led to wrong output (PDF, say), - it is in fact an improvement when the test now fails, label it as +\begin_inset Foot +status collapsed + +\begin_layout Plain Layout +Non-failing test with wrong output should be labeled as \begin_inset Quotes eld \end_inset -unreliable:wrong:output +unreliable:wrong_output \begin_inset Quotes erd \end_inset @@ -3297,9 +3412,25 @@ reference "par:Unreliable-tests" ). \end_layout +\end_inset + + it is in fact an improvement when the test now fails. + +\emph on +Invert +\emph default + the failing test case (see +\begin_inset CommandInset ref +LatexCommand ref +reference "par:Inverted-tests" + +\end_inset + +). +\end_layout + \begin_layout Itemize -In case of tests failing due to missing requirements (when only a subset - of TeXLive is installed or a test labeled +In case of tests failing due to missing requirements (tests labeled \begin_inset Quotes eld \end_inset @@ -3307,8 +3438,17 @@ unreliable:nonstandard \begin_inset Quotes erd \end_inset - fails), ignore the failure, ask for someone else to run the test, or install - the missing ressources and try again. + or testing on a system with only a subset of TeXLive installed), ignore + the failure, ask for someone else to run the test, or install the missing + resources and try again. +\end_layout + +\begin_layout Itemize +Check the log file Testing/Temporary/LastTest.log. + In case of latex-errors rerun the failing test with environment variable + 'LYX_DEBUG_LATEX' set to '1'. + This will include latex messages in LastTest.log, so it should be easier + to interpret the fail-reason. \end_layout \begin_layout Paragraph @@ -3327,7 +3467,7 @@ Test cases whose name matches a pattern in the file status collapsed \begin_layout Plain Layout -development/autotests/suspiciousTests +development/autotests/invertedTests \end_layout \end_inset @@ -3382,7 +3522,7 @@ The following sublabels are currently present in status collapsed \begin_layout Plain Layout -suspiciousTests +invertedTests \end_layout \end_inset @@ -3448,12 +3588,20 @@ otherwise, add a pattern here. \end_deeper \begin_layout Description -attic Documents in the attic. - (Kept for reference and format conversion test.) +attic Documents in the attic (kept for reference and format conversion test). + Usually +\begin_inset Quotes eld +\end_inset + +Wontfix +\begin_inset Quotes erd +\end_inset + +. \end_layout \begin_layout Subparagraph -suspended +suspended tests \end_layout \begin_layout Standard @@ -3628,43 +3776,45 @@ status collapsed \end_layout -\begin_layout Description -nonstandard Documents with additional requirements, e.g. - a class or package file not in TeXLive. - -\begin_inset Note Note -status open +\begin_layout Standard +The following sublabels are currently present in +\begin_inset Flex Code +status collapsed \begin_layout Plain Layout -TODO: rename to "extra"? +unreliableTests \end_layout \end_inset - -\end_layout - -\begin_deeper -\begin_layout Standard -These tests are labeled as -\family typewriter -'nonstandard'. +: \end_layout -\end_deeper \begin_layout Description -erratic Tests depending on local configuration, OS, TeX distribution, package - versions, or the phase of the moon. +nonstandard Documents with additional requirements, e.g. + a class or package file not in TeXLive. \begin_inset Note Note status open \begin_layout Plain Layout -TODO: use -\emph on -erratic -\emph default - only for the phase-of-moon dependency? +TODO: rename to +\begin_inset Quotes eld +\end_inset + +extra +\begin_inset Quotes erd +\end_inset + + or +\begin_inset Quotes eld +\end_inset + +exotic +\begin_inset Quotes erd +\end_inset + +? \end_layout \end_inset @@ -3672,20 +3822,25 @@ erratic \end_layout -\begin_deeper -\begin_layout Standard -These tests are labeled as -\family typewriter -'erratic'. +\begin_layout Description +erratic Tests depending on local configuration or the phase of the moon. + +\end_layout + +\begin_layout Description +varying_versions Tests depending on e.g. + OS or version of a non-TeX-Live dependency. + Note that a full, up-to-date TeX Live installation is required so this + sublabel is about versions of other dependencies. \end_layout -\end_deeper \begin_layout Description wrong \begin_inset space ~ \end_inset -output Export does not fail but the resulting document has errors. +output Export does not fail but the resulting document has (undetected) + errors. \end_layout \begin_deeper @@ -3696,11 +3851,7 @@ status open \begin_layout Plain Layout \paragraph_spacing single -These tests are actually not -\emph on -unreliable -\emph default - but +These tests are in a strict sense not unreliable but \emph on invalid \emph default @@ -3757,8 +3908,8 @@ Output Stop if tests not selected here \end_deeper \begin_layout Description -unreliableTests: Tests selected either pass or fail, but that is dependent - on the system where the test is run. +unreliableTests: Tests selected pass or fail dependent on the system where + the test is run. Selected tests gain the label 'unreliable'. \end_layout @@ -3770,12 +3921,12 @@ Input Each test which passed 'ignoredTests' \begin_layout Labeling \labelwidthstring 00.00.0000 -Output Stop if test selected, gain label 'unreliable'. +Output Gain label 'unreliable', proceed with checking for 'inverted'. \end_layout \end_deeper \begin_layout Description -suspiciousTests +invertedTests \begin_inset space \space{} \end_inset @@ -3785,17 +3936,18 @@ suspiciousTests \begin_deeper \begin_layout Labeling \labelwidthstring 00.00.0000 -Input Each test which passed 'unreliableTests' +Input Each test which passed 'ignoredTests' \end_layout \begin_layout Labeling \labelwidthstring 00.00.0000 -Output Stop if not selected. +Output Stop if not selected, gain test-property 'WILL_FAIL' (i.e. + tests are reported as failing if the export works without error.) If no + subselection applies, gain labels 'export' and 'inverted'. \end_layout \begin_layout Standard -The following file is meant as subselections of 'suspiciousTests'. - If neither subselection applies, test gains labels 'export' and 'inverted' +The following filter perfoms a subselection of 'invertedTests': \end_layout \begin_layout Description @@ -3807,7 +3959,7 @@ suspendedTests Tests selected here gain the label 'suspended' but _not_ \begin_deeper \begin_layout Labeling \labelwidthstring 00.00.0000 -Input Each test selected by 'suspiciousTests' +Input Each test selected by 'invertedTests' \end_layout \begin_layout Labeling @@ -3823,17 +3975,18 @@ The following table may clarify label assignement \end_layout \begin_layout Standard +\begin_inset space \hspace{} +\length -3cm +\end_inset + + \begin_inset Tabular - + - - - - - - - - + + + + @@ -3843,7 +3996,7 @@ The following table may clarify label assignement \begin_inset Text \begin_layout Plain Layout -Test found in file: +Test matching pattern in file: \end_layout \end_inset @@ -3875,16 +4028,16 @@ Test found in file: \end_inset - + \begin_inset Text \begin_layout Plain Layout -Marked in ctest, Assigned label +Assigned label \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -3893,7 +4046,7 @@ Marked in ctest, Assigned label \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -3902,153 +4055,159 @@ Marked in ctest, Assigned label \end_inset - + \begin_inset Text \begin_layout Plain Layout - +test property \end_layout \end_inset - + + + \begin_inset Text \begin_layout Plain Layout - +ignored\SpecialChar softhyphen +Tests \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout - +unreliable\SpecialChar softhyphen +Tests \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout - +inverted\SpecialChar softhyphen +Tests \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout - +suspended\SpecialChar softhyphen +Tests \end_layout \end_inset - - - + \begin_inset Text \begin_layout Plain Layout -Ignored +export \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -Unreliable +inverted \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -Suspicious +suspended \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -Suspended + \end_layout \end_inset - + + + \begin_inset Text \begin_layout Plain Layout -export +Yes \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout - +- \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -unreliable +- \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout - +- \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -inverted +- \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout - +- \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -suspended +- \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -4059,38 +4218,46 @@ suspended - + \begin_inset Text \begin_layout Plain Layout -Yes +No \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- +If Yes, +\begin_inset Newline newline +\end_inset + +add label +\begin_inset Newline newline +\end_inset + +'unreliable' \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- +Yes \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- +Yes \end_layout \end_inset @@ -4113,81 +4280,81 @@ Yes \end_inset - + \begin_inset Text \begin_layout Plain Layout -- ++ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout - +WILL_FAIL \end_layout \end_inset - + + + \begin_inset Text \begin_layout Plain Layout -- + \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- + \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- + \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- +No \end_layout \end_inset - - - + \begin_inset Text \begin_layout Plain Layout -No ++ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -Yes ++ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -4196,61 +4363,63 @@ Yes \end_inset - + \begin_inset Text \begin_layout Plain Layout -- +WILL_FAIL \end_layout \end_inset - + + + \begin_inset Text \begin_layout Plain Layout -- + \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- + \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- +No \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -+ +- \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- ++ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -4259,7 +4428,7 @@ Yes \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -4268,103 +4437,139 @@ Yes \end_inset - + \begin_inset Text \begin_layout Plain Layout -- + \end_layout \end_inset + + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset Note Note +status open + +\begin_layout Plain Layout +Without the +\begin_inset Quotes eld +\end_inset + +suspendedTests +\begin_inset Quotes erd +\end_inset + + filter, this would be far less complicated: +\end_layout + +\begin_layout Plain Layout +\begin_inset Tabular + + + + + + + + + - + \begin_inset Text \begin_layout Plain Layout - +Test matching pattern in file: \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -No + \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -Yes + \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -Yes +Label \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- + \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- + \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- +test property \end_layout \end_inset - + + + \begin_inset Text \begin_layout Plain Layout -- +ignoredTests \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -+ +unreliableTests \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- +invertedTests \end_layout \end_inset @@ -4373,32 +4578,30 @@ Yes \begin_inset Text \begin_layout Plain Layout -- +export \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -+ +unreliable \end_layout \end_inset - - - + \begin_inset Text \begin_layout Plain Layout - +inverted \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -4407,11 +4610,22 @@ Yes \end_inset - + + + \begin_inset Text \begin_layout Plain Layout +Yes +\end_layout + +\end_inset + + +\begin_inset Text +\begin_layout Plain Layout +- \end_layout \end_inset @@ -4420,7 +4634,7 @@ Yes \begin_inset Text \begin_layout Plain Layout -No +- \end_layout \end_inset @@ -4438,12 +4652,12 @@ No \begin_inset Text \begin_layout Plain Layout -+ + \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -4452,7 +4666,36 @@ No \end_inset - + +\begin_inset Text + +\begin_layout Plain Layout + +\end_layout + +\end_inset + + + + +\begin_inset Text + +\begin_layout Plain Layout +No +\end_layout + +\end_inset + + +\begin_inset Text + +\begin_layout Plain Layout +Yes +\end_layout + +\end_inset + + \begin_inset Text \begin_layout Plain Layout @@ -4465,7 +4708,7 @@ No \begin_inset Text \begin_layout Plain Layout -+ +- \end_layout \end_inset @@ -4479,7 +4722,7 @@ No \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -4492,14 +4735,14 @@ No \begin_inset Text \begin_layout Plain Layout -- + \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -4508,34 +4751,34 @@ No \end_inset - + \begin_inset Text \begin_layout Plain Layout - +No \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -No +Yes \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout -- ++ \end_layout \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -4544,7 +4787,7 @@ No \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -4553,20 +4796,40 @@ No \end_inset - + \begin_inset Text \begin_layout Plain Layout -- +WILL_FAIL \end_layout \end_inset - + + + \begin_inset Text \begin_layout Plain Layout -- + +\end_layout + +\end_inset + + +\begin_inset Text + +\begin_layout Plain Layout + +\end_layout + +\end_inset + + +\begin_inset Text + +\begin_layout Plain Layout +No \end_layout \end_inset @@ -4575,7 +4838,7 @@ No \begin_inset Text \begin_layout Plain Layout -- ++ \end_layout \end_inset @@ -4589,7 +4852,7 @@ No \end_inset - + \begin_inset Text \begin_layout Plain Layout @@ -4602,7 +4865,7 @@ No \begin_inset Text \begin_layout Plain Layout -- + \end_layout \end_inset @@ -4613,6 +4876,11 @@ No \end_inset +\end_layout + +\end_inset + + \end_layout \begin_layout Subsubsection @@ -4658,7 +4926,18 @@ Keytests \end_layout \begin_layout Standard -Automated tests based on the "MonKey Testing" keytest program. +Automated tests based on the "MonKey Testing" keytest program are enabled + if the necessary dependencies are found and if the CMake flag +\begin_inset Flex Code +status collapsed + +\begin_layout Plain Layout +-DLYX_ENABLE_KEYTESTS=ON +\end_layout + +\end_inset + + is used. They are documented in the README document in \begin_inset Flex Code status collapsed @@ -4671,7 +4950,6 @@ development/autotests subfolder of the \SpecialChar LyX source code distribution. - T \end_layout \begin_layout Subsubsection @@ -4823,9 +5101,98 @@ No. \end_layout \begin_layout Section +\begin_inset CommandInset label +LatexCommand label +name "sec:Documentation-policies" + +\end_inset + Documentation policies \end_layout +\begin_layout Subsection +Rules +\end_layout + +\begin_layout Standard +There are 6 +\begin_inset space ~ +\end_inset + +rules in editing the docs: +\end_layout + +\begin_layout Enumerate +\begin_inset CommandInset label +LatexCommand label +name "enu:If-you-are" + +\end_inset + +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 knows ;-). + 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 + + or the document's default output format after your changes. +\end_layout + +\begin_layout Enumerate +All fixes (typos, compilation fixes, updates info etc.) go at first into + the current GIT branch because the user should benefit from all fixes with + every minor release. + Feel free to commit directly to branch as long as you follow rule +\begin_inset space ~ +\end_inset + + +\begin_inset CommandInset ref +LatexCommand ref +reference "enu:If-you-are" + +\end_inset + +. + You can immediately commit to master as well. +\end_layout + +\begin_layout Enumerate +\begin_inset CommandInset label +LatexCommand label +name "enu:The-fileformat-of" + +\end_inset + +The fileformat of a file must not be changed unless you document a new feature + in LyX that requires a new fileformat. + The reason for this rule is to keep it easy for the doc maintainers to + port/backport changes to from master/branch. +\end_layout + \begin_layout Standard The main documentation consists of these files: \end_layout @@ -4920,46 +5287,5 @@ Customization.lyx this manual covers information how to customize \SpecialChar L 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