lib/doc/Development.lyx

   1 #LyX 2.1 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 474
   3 \begin_document
   4 \begin_header
   5 \textclass scrbook
   6 \options fleqn,bibliography=totoc,index=totoc,BCOR7.5mm,titlepage,captions=tableheading
   7 \use_default_options false
   8 \begin_modules
   9 logicalmkup
  10 theorems-ams
  11 theorems-ams-extended
  12 multicol
  13 shapepar
  14 \end_modules
  15 \maintain_unincluded_children false
  16 \begin_local_layout
  17 Format 7
  18 InsetLayout CharStyle:MenuItem
  19 LyxType               charstyle
  20 LabelString           menu
  21 LatexType             command
  22 LatexName             menuitem
  23 Font
  24 Family              Sans
  25 EndFont
  26 Preamble
  27 \newcommand*{\menuitem}[1]{{\sffamily #1}}
  28 EndPreamble
  29 End
  30 \end_local_layout
  31 \language english
  32 \language_package default
  33 \inputencoding auto
  34 \fontencoding global
  35 \font_roman default
  36 \font_sans default
  37 \font_typewriter default
  38 \font_math auto
  39 \font_default_family default
  40 \use_non_tex_fonts false
  41 \font_sc false
  42 \font_osf false
  43 \font_sf_scale 100
  44 \font_tt_scale 100
  45 \graphics default
  46 \default_output_format default
  47 \output_sync 0
  48 \bibtex_command default
  49 \index_command default
  50 \paperfontsize 12
  51 \spacing single
  52 \use_hyperref true
  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"
  57 \pdf_bookmarks true
  58 \pdf_bookmarksnumbered true
  59 \pdf_bookmarksopen true
  60 \pdf_bookmarksopenlevel 1
  61 \pdf_breaklinks false
  62 \pdf_pdfborder false
  63 \pdf_colorlinks true
  64 \pdf_backref false
  65 \pdf_pdfusetitle false
  66 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
  67 \papersize a4paper
  68 \use_geometry false
  69 \use_package amsmath 1
  70 \use_package amssymb 1
  71 \use_package cancel 0
  72 \use_package esint 0
  73 \use_package mathdots 1
  74 \use_package mathtools 0
  75 \use_package mhchem 1
  76 \use_package stackrel 0
  77 \use_package stmaryrd 0
  78 \use_package undertilde 0
  79 \cite_engine basic
  80 \cite_engine_type default
  81 \biblio_style plain
  82 \use_bibtopic false
  83 \use_indices false
  84 \paperorientation portrait
  85 \suppress_date false
  86 \justification true
  87 \use_refstyle 0
  88 \notefontcolor #0000ff
  89 \index Index
  90 \shortcut idx
  91 \color #008000
  92 \end_index
  93 \secnumdepth 3
  94 \tocdepth 3
  95 \paragraph_separation indent
  96 \paragraph_indentation default
  97 \quotes_language english
  98 \papercolumns 1
  99 \papersides 2
 100 \paperpagestyle headings
 101 \tracking_changes false
 102 \output_changes false
 103 \html_math_output 0
 104 \html_css_as_file 0
 105 \html_be_strict true
 106 \end_header
 107
 108 \begin_body
 109
 110 \begin_layout Title
 111 Developing LyX
 112 \end_layout
 113
 114 \begin_layout Subtitle
 115 Version 2.2.x
 116 \end_layout
 117
 118 \begin_layout Author
 119 by the LyX Team
 120 \begin_inset Foot
 121 status collapsed
 122
 123 \begin_layout Plain Layout
 124 \noindent
 125 If you have comments or error corrections, please send them to the LyX Documenta
 126 tion mailing list,
 127 \begin_inset Flex Code
 128 status collapsed
 129
 130 \begin_layout Plain Layout
 131 \noindent
 132 <lyx-docs@lists.lyx.org>
 133 \end_layout
 134
 135 \end_inset
 136
 137 .
 138 \end_layout
 139
 140 \end_inset
 141
 142
 143 \end_layout
 144
 145 \begin_layout Standard
 146 \begin_inset CommandInset toc
 147 LatexCommand tableofcontents
 148
 149 \end_inset
 150
 151
 152 \end_layout
 153
 154 \begin_layout Chapter
 155 Introduction
 156 \end_layout
 157
 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
 161  future.
 162  Meanwhile, additional information can be found in the
 163 \begin_inset Flex Code
 164 status collapsed
 165
 166 \begin_layout Plain Layout
 167 development
 168 \end_layout
 169
 170 \end_inset
 171
 172  subfolder of the LyX source code distribution.
 173  This document is not translated, since the development language of LyX
 174  is english.
 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
 178 on.
 179 \end_layout
 180
 181 \begin_layout Chapter
 182 File formats
 183 \end_layout
 184
 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
 189 tion.
 190 \end_layout
 191
 192 \begin_layout Section
 193 File Format Numbers
 194 \end_layout
 195
 196 \begin_layout Section
 197 When is an update of the .lyx file format number needed?
 198 \begin_inset CommandInset label
 199 LatexCommand label
 200 name "sec:When-is-an"
 201
 202 \end_inset
 203
 204
 205 \end_layout
 206
 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:
 212 \end_layout
 213
 214 \begin_layout Description
 215 New
 216 \begin_inset space ~
 217 \end_inset
 218
 219 document
 220 \begin_inset space ~
 221 \end_inset
 222
 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,
 226  e.
 227 \begin_inset space \thinspace{}
 228 \end_inset
 229
 230 g.
 231 \begin_inset space \space{}
 232 \end_inset
 233
 234 a new language that is stored in
 235 \begin_inset Flex Code
 236 status collapsed
 237
 238 \begin_layout Plain Layout
 239
 240 \backslash
 241 language
 242 \end_layout
 243
 244 \end_inset
 245
 246 .
 247 \end_layout
 248
 249 \begin_layout Description
 250 Removed
 251 \begin_inset space ~
 252 \end_inset
 253
 254 document
 255 \begin_inset space ~
 256 \end_inset
 257
 258 setting If a certain setting becomes obsolete and gets removed, a file format
 259  update is needed.
 260 \end_layout
 261
 262 \begin_layout Description
 263 New
 264 \begin_inset space ~
 265 \end_inset
 266
 267 inset Of course a new inset requires a file format update.
 268 \end_layout
 269
 270 \begin_layout Description
 271 New
 272 \begin_inset space ~
 273 \end_inset
 274
 275 style in any layout file or module shipped with LyX, or new shipped layout
 276  file or module.
 277  These requirements are currently under discussion and might change in the
 278  future.
 279 \end_layout
 280
 281 \begin_layout Description
 282 Automatically
 283 \begin_inset space ~
 284 \end_inset
 285
 286 loaded
 287 \begin_inset space ~
 288 \end_inset
 289
 290 math
 291 \begin_inset space ~
 292 \end_inset
 293
 294 package Any new math package that is automatically loaded needs a file format
 295  update.
 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
 302 status collapsed
 303
 304 \begin_layout Plain Layout
 305 use_package
 306 \end_layout
 307
 308 \end_inset
 309
 310  header setting.
 311 \end_layout
 312
 313 \begin_layout Standard
 314 If you are still unsure, please ask on the development list.
 315 \end_layout
 316
 317 \begin_layout Section
 318 How to update the file format number of .lyx files
 319 \end_layout
 320
 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:
 324 \end_layout
 325
 326 \begin_layout Enumerate
 327 Implement and test the new feature, including the reading and writing of
 328  .lyx files.
 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.
 331 \end_layout
 332
 333 \begin_layout Enumerate
 334 Describe the new format in
 335 \begin_inset Flex Code
 336 status collapsed
 337
 338 \begin_layout Plain Layout
 339 development/FORMAT
 340 \end_layout
 341
 342 \end_inset
 343
 344 .
 345 \end_layout
 346
 347 \begin_layout Enumerate
 348 Update the LyX file format number in
 349 \begin_inset Flex Code
 350 status collapsed
 351
 352 \begin_layout Plain Layout
 353 src/version.h
 354 \end_layout
 355
 356 \end_inset
 357
 358 .
 359 \end_layout
 360
 361 \begin_layout Enumerate
 362 Add an entry to both format lists (for conversion and reversion) in
 363 \begin_inset Newline newline
 364 \end_inset
 365
 366
 367 \begin_inset Flex Code
 368 status collapsed
 369
 370 \begin_layout Plain Layout
 371 lib/lyx2lyx/lyx_2_2.py
 372 \end_layout
 373
 374 \end_inset
 375
 376 .
 377  Add a conversion routine if needed (e.
 378 \begin_inset space \thinspace{}
 379 \end_inset
 380
 381 g.
 382 \begin_inset space \space{}
 383 \end_inset
 384
 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
 390  that strict.
 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.
 396 \end_layout
 397
 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
 405  of the list below:
 406 \end_layout
 407
 408 \begin_deeper
 409 \begin_layout Enumerate
 410 Update the tex2lyx file format number in
 411 \begin_inset Flex Code
 412 status collapsed
 413
 414 \begin_layout Plain Layout
 415 src/version.h
 416 \end_layout
 417
 418 \end_inset
 419
 420 .
 421 \end_layout
 422
 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
 426  tex2lyx changes.
 427  Otherwise, search for the changed feature in tex2lyx, and adjust the output
 428  according to the lyx2lyx changes.
 429 \end_layout
 430
 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"
 436
 437 \end_inset
 438
 439 .
 440 \end_layout
 441
 442 \end_deeper
 443 \begin_layout Enumerate
 444 If you did not implement full tex2lyx support of the new feature, add a
 445  line to
 446 \begin_inset Flex Code
 447 status collapsed
 448
 449 \begin_layout Plain Layout
 450 src/tex2lyx/TODO.txt
 451 \end_layout
 452
 453 \end_inset
 454
 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.
 462 \end_layout
 463
 464 \begin_layout Enumerate
 465 It would be nice if you could create a .lyx test file which contains instances
 466  of all changed or added features.
 467  This could then be used to test lyxl2yx and tex2lyx.
 468  Unfortunately it has not yet been decided how to collect such examples,
 469  so please ask on the development list if you want to create one.
 470 \end_layout
 471
 472 \begin_layout Section
 473 Backporting new styles to the stable version
 474 \end_layout
 475
 476 \begin_layout Standard
 477 Starting with the stable LyX 2.1 branch, there is a mechanism in place to
 478  backport new styles to the stable version without the need to update the
 479  file format.
 480  The basic idea is that the new style definition is automatically copied
 481  to the document preamble, so that it can even be used by older minor revisions
 482  that did not yet include the style.
 483  To backport a new style to the stable version, the following steps are
 484  needed:
 485 \end_layout
 486
 487 \begin_layout Enumerate
 488 Add the line
 489 \begin_inset Flex Code
 490 status collapsed
 491
 492 \begin_layout Plain Layout
 493 ForceLocal -1
 494 \end_layout
 495
 496 \end_inset
 497
 498  to the style definition in the development version.
 499 \end_layout
 500
 501 \begin_layout Enumerate
 502 Copy the style definition to the stable version, but use
 503 \begin_inset Flex Code
 504 status collapsed
 505
 506 \begin_layout Plain Layout
 507 ForceLocal 1
 508 \end_layout
 509
 510 \end_inset
 511
 512  instead.
 513  If needed adjust the format to the one used by the stable version (see
 514  the customization manual for details of the layout file format).
 515 \end_layout
 516
 517 \begin_layout Enumerate
 518 For each update of the style in a later stable version, increase the argument
 519  of
 520 \begin_inset Flex Code
 521 status collapsed
 522
 523 \begin_layout Plain Layout
 524 ForceLocal
 525 \end_layout
 526
 527 \end_inset
 528
 529  by one (in the stable version, the development version should not be touched).
 530 \end_layout
 531
 532 \begin_layout Standard
 533 For details about the
 534 \begin_inset Flex Code
 535 status collapsed
 536
 537 \begin_layout Plain Layout
 538 ForceLocal
 539 \end_layout
 540
 541 \end_inset
 542
 543  flag see the customization manual.
 544  No
 545 \begin_inset Flex Code
 546 status collapsed
 547
 548 \begin_layout Plain Layout
 549 lyx2lyx
 550 \end_layout
 551
 552 \end_inset
 553
 554  support is needed for backported styles: Since the style of the development
 555  version has an infinite version number, it will always be used.
 556  Furthermore, since its version number is less than one, the style will
 557  not be written anymore to the document header for files saved by the new
 558  version.
 559 \end_layout
 560
 561 \begin_layout Chapter
 562 Tests
 563 \end_layout
 564
 565 \begin_layout Standard
 566 Automated tests are an important tool to detect bugs and regressions in
 567  software development.
 568  Some projects like gcc even require each bug fix to be accompanied by a
 569  test case for the automatic test suite, that would detect this bug.
 570  Testing interactive features automatically is of course very hard, but
 571  core functionality like document import and export can be tested quite
 572  easily, and some tests of this kind exist.
 573 \end_layout
 574
 575 \begin_layout Section
 576 LyX tests
 577 \end_layout
 578
 579 \begin_layout Standard
 580 Some tests are located in the
 581 \begin_inset Flex Code
 582 status collapsed
 583
 584 \begin_layout Plain Layout
 585 development/autotests
 586 \end_layout
 587
 588 \end_inset
 589
 590  subfolder of the LyX source code distribution.
 591 \end_layout
 592
 593 \begin_layout Subsection
 594 Running the tests
 595 \end_layout
 596
 597 \begin_layout Standard
 598 The LyX tests can be run by the commands
 599 \begin_inset Flex Code
 600 status collapsed
 601
 602 \begin_layout Plain Layout
 603 make test
 604 \end_layout
 605
 606 \end_inset
 607
 608  (cmake) in the
 609 \begin_inset Flex Code
 610 status collapsed
 611
 612 \begin_layout Plain Layout
 613 autotests
 614 \end_layout
 615
 616 \end_inset
 617
 618  subfolder of the build directory.
 619 \begin_inset Note Note
 620 status open
 621
 622 \begin_layout Plain Layout
 623 FIXME: Is this possible with autotools?
 624 \end_layout
 625
 626 \end_inset
 627
 628
 629 \end_layout
 630
 631 \begin_layout Section
 632 tex2lyx tests
 633 \end_layout
 634
 635 \begin_layout Standard
 636 The tex2lyx tests are located in the
 637 \begin_inset Flex Code
 638 status collapsed
 639
 640 \begin_layout Plain Layout
 641 src/tex2lyx/test
 642 \end_layout
 643
 644 \end_inset
 645
 646  subfolder of the LyX source code distribution.
 647  The actual testing is performed by the simple python script
 648 \begin_inset Flex Code
 649 status collapsed
 650
 651 \begin_layout Plain Layout
 652 src/tex2lyx/test/runtests.py
 653 \end_layout
 654
 655 \end_inset
 656
 657 .
 658  Each test consists of two files:
 659 \begin_inset Flex Code
 660 status collapsed
 661
 662 \begin_layout Plain Layout
 663 <test name>.tex
 664 \end_layout
 665
 666 \end_inset
 667
 668  contains the LaTeX code that should be tested.
 669
 670 \begin_inset Flex Code
 671 status collapsed
 672
 673 \begin_layout Plain Layout
 674 <test name>.lyx.lyx
 675 \end_layout
 676
 677 \end_inset
 678
 679  contains the expected output of tex2lyx.
 680  When a test is run, the actual produced output is compared with the stored
 681  reference output.
 682  The test passes if both are identical.
 683  The test machinery is also able to generate a file
 684 \begin_inset Flex Code
 685 status collapsed
 686
 687 \begin_layout Plain Layout
 688 <test name>.lyx.tex
 689 \end_layout
 690
 691 \end_inset
 692
 693  by exporting the produced .lyx file with LyX again.
 694  This may be useful for roundtrip comparisons.
 695 \end_layout
 696
 697 \begin_layout Subsection
 698 Running the tests
 699 \end_layout
 700
 701 \begin_layout Standard
 702 The tex2lyx tests can be run by the commands
 703 \begin_inset Flex Code
 704 status collapsed
 705
 706 \begin_layout Plain Layout
 707 make test
 708 \end_layout
 709
 710 \end_inset
 711
 712  (cmake) or
 713 \begin_inset Flex Code
 714 status collapsed
 715
 716 \begin_layout Plain Layout
 717 make alltests
 718 \end_layout
 719
 720 \end_inset
 721
 722  (autotools) in the
 723 \begin_inset Flex Code
 724 status collapsed
 725
 726 \begin_layout Plain Layout
 727 src/tex2lyx
 728 \end_layout
 729
 730 \end_inset
 731
 732  subfolder of the build directory.
 733  If a test fails, the differences between the expected and actual results
 734  are output in unified diff format.
 735 \end_layout
 736
 737 \begin_layout Subsection
 738 Updating test references
 739 \begin_inset CommandInset label
 740 LatexCommand label
 741 name "sec:Updating-test-references"
 742
 743 \end_inset
 744
 745
 746 \end_layout
 747
 748 \begin_layout Standard
 749 In some cases a changed tex2lyx output is not a test failure, but wanted,
 750  e.
 751 \begin_inset space \thinspace{}
 752 \end_inset
 753
 754 g.
 755 \begin_inset space \space{}
 756 \end_inset
 757
 758 if a tex2lyx bug was fixed, or a new feature was added.
 759  In these cases the stored references need to be updated.
 760  To do so if using autotools, call
 761 \begin_inset Flex Code
 762 status collapsed
 763
 764 \begin_layout Plain Layout
 765 make updatetests
 766 \end_layout
 767
 768 \end_inset
 769
 770  in the
 771 \begin_inset Flex Code
 772 status collapsed
 773
 774 \begin_layout Plain Layout
 775 src/tex2lyx
 776 \end_layout
 777
 778 \end_inset
 779
 780  subdirectory of the build directory.
 781  If instead using CMake, call
 782 \begin_inset Flex Code
 783 status collapsed
 784
 785 \begin_layout Plain Layout
 786 make updatetex2lyxtests
 787 \end_layout
 788
 789 \end_inset
 790
 791  in the build directory or in the
 792 \begin_inset Flex Code
 793 status collapsed
 794
 795 \begin_layout Plain Layout
 796 src/tex2lyx/test
 797 \end_layout
 798
 799 \end_inset
 800
 801  subdirectory of the build directory
 802 \begin_inset Foot
 803 status collapsed
 804
 805 \begin_layout Plain Layout
 806 Note that this is a case where a make target in the build directory can
 807  affect the source directory, which might not be advisable.
 808 \end_layout
 809
 810 \end_inset
 811
 812 .
 813  For convenience, these commands also produce re-exported roundtrip .lyx.tex
 814  files.
 815  Please examine the changed output carefully before committing the changed
 816  files to the repository: Since the test machinery does not do a roundtrip
 817  test .tex
 818 \begin_inset Formula $\Rightarrow$
 819 \end_inset
 820
 821  .lyx
 822 \begin_inset Formula $\Rightarrow$
 823 \end_inset
 824
 825  .tex, and does not compare the produced dvi or pdf output, it assumes that
 826  the stored .lyx reference produces correct output if processed by LyX.
 827  There is only one chance to detect wrong output: before committing a new
 828  reference.
 829  Once it is committed, it is quite difficult to verify whether it is correct.
 830 \end_layout
 831
 832 \begin_layout Standard
 833 Please
 834 \emph on
 835 do not
 836 \emph default
 837  update the test references by opening them with LyX or directly running
 838  lyx2lyx on them.
 839  This would not work, since lyx2lyx and LyX produce slightly different files
 840  regarding insignificant whitespace and line breaks.
 841 \end_layout
 842
 843 \begin_layout Subsection
 844 Adding a new test
 845 \end_layout
 846
 847 \begin_layout Standard
 848 In many cases tests for new features may be added to one of the existing
 849  test files, but sometimes this is not possible or not wanted.
 850  Then a new test file needs to be added:
 851 \end_layout
 852
 853 \begin_layout Enumerate
 854 Create the new file
 855 \begin_inset Flex Code
 856 status collapsed
 857
 858 \begin_layout Plain Layout
 859 src/tex2lyx/test/<test name>.tex
 860 \end_layout
 861
 862 \end_inset
 863
 864  and run tex2lyx in roundtrip mode to produce the file
 865 \begin_inset Flex Code
 866 status collapsed
 867
 868 \begin_layout Plain Layout
 869 src/tex2lyx/test/<test name>.lyx.lyx
 870 \end_layout
 871
 872 \end_inset
 873
 874 .
 875  This file will be the new reference.
 876 \end_layout
 877
 878 \begin_layout Enumerate
 879 Once you confirmed that the tex2lyx output is correct, add the new files
 880  to the corresponding lists in
 881 \begin_inset Flex Code
 882 status collapsed
 883
 884 \begin_layout Plain Layout
 885 src/tex2lyx/test/runtests.py
 886 \end_layout
 887
 888 \end_inset
 889
 890 ,
 891 \begin_inset Flex Code
 892 status collapsed
 893
 894 \begin_layout Plain Layout
 895 src/tex2lyx/Makefile.am
 896 \end_layout
 897
 898 \end_inset
 899
 900  and
 901 \begin_inset Flex Code
 902 status collapsed
 903
 904 \begin_layout Plain Layout
 905 src/tex2lyx/test/CMakeLists.txt
 906 \end_layout
 907
 908 \end_inset
 909
 910 .
 911 \end_layout
 912
 913 \begin_layout Enumerate
 914 Commit the changes to the repository, or send a patch to the development
 915  list and ask for committing if you do not have commit rights.
 916 \end_layout
 917
 918 \begin_layout Chapter
 919 Development policies
 920 \end_layout
 921
 922 \begin_layout Standard
 923 This chapter lists some guidelines that should be followed.
 924  This list is not complete, and many guidelines are in separate chapters,
 925  such as
 926 \begin_inset Quotes eld
 927 \end_inset
 928
 929 When is an update of the .lyx file format number needed?
 930 \begin_inset Quotes erd
 931 \end_inset
 932
 933  in Section
 934 \begin_inset CommandInset ref
 935 LatexCommand ref
 936 reference "sec:When-is-an"
 937
 938 \end_inset
 939
 940 .
 941 \end_layout
 942
 943 \begin_layout Section
 944 When to set a fixed milestone?
 945 \end_layout
 946
 947 \begin_layout Standard
 948 Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
 949  holds:
 950 \end_layout
 951
 952 \begin_layout Enumerate
 953 Somebody is actively working on a fix.
 954 \end_layout
 955
 956 \begin_layout Enumerate
 957 The bug is so severe that it would block the release if it is not fixed.
 958 \end_layout
 959
 960 \begin_layout Standard
 961 If a bug is important, but nobody is working on it, and it is no showstopper,
 962  use a milestone like 2.1.x or 2.2.x.
 963  For all other bugs, do not set a milestone at all.
 964 \end_layout
 965
 966 \begin_layout Section
 967 Can we add rc entries in stable branch?
 968 \end_layout
 969
 970 \begin_layout Standard
 971 No.
 972  We are supposed to increase the prefs2prefs version number with such things.
 973 \end_layout
 974
 975 \begin_layout Chapter
 976 Documentation policies
 977 \end_layout
 978
 979 \begin_layout Standard
 980 The main documentation consists of these files:
 981 \end_layout
 982
 983 \begin_layout Description
 984 splash.lyx it is the first file you see after an installation.
 985  We assume that a new user sees this.
 986  It is therefore designed to be as simple as possible.
 987  Therefore please don't add any new formatting, only fix typos etc.
 988  Splash.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
 989 \end_layout
 990
 991 \begin_layout Description
 992 Intro.lyx This is the manual new users will read to learn LyX.
 993  It therefore uses a limited set of formatting.
 994  For example a standard document class.
 995  Since new users will first learn about the formatting possibilities of
 996  LyX please keep this file that simple.
 997  Intro.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
 998 \end_layout
 999
1000 \begin_layout Description
1001 Tutorial.lyx our tutorial.
1002  It must be always up to date.
1003  Normally there is nothing to add since we don't want to overwhelm new users
1004  with too much details.
1005  The will learn these details while using LyX and we have special manuals.
1006  Tutorial.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
1007 \end_layout
1008
1009 \begin_layout Description
1010 UserGuide.lyx our main user guide.
1011  It covers a mixture of basic and detailed information.
1012  Some information is also in the Math and EmbeddedObjects manual so that
1013  the UserGuide refers to these files.
1014  UserGuide.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
1015 \end_layout
1016
1017 \begin_layout Description
1018 EmbeddedObjects.lyx a special manual to explain things like tables floats
1019  boxes etc.
1020  in all detail.
1021  EmbeddedObjects.lyx is up to date for LyX 2.1.x, currently maintained by Uwe
1022  Stöhr.
1023 \end_layout
1024
1025 \begin_layout Description
1026 Math.lyx a special manual to explain everything regarding math in all detail.
1027  Math.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
1028 \end_layout
1029
1030 \begin_layout Description
1031 Additional.lyx this manual covers information that would be too much detail
1032  for the UserGuide or would make the UserGuide uncompilable or only compilable
1033  when installing a lot of special LaTeX-packages.
1034  What should be in the UserGuide or better in Additional is a matter of
1035  taste.
1036  it is up to you to decide that.
1037  Additional.lyx is not completely up to date for LyX 2.1.x.
1038  Only chapter
1039 \begin_inset space ~
1040 \end_inset
1041
1042 8 is up to date and currently maintained by Uwe Stöhr.
1043  It certainly needs a rewrite and update.
1044  For example many info in chapter
1045 \begin_inset space ~
1046 \end_inset
1047
1048 2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
1049  manual.
1050 \end_layout
1051
1052 \begin_layout Description
1053 Customization.lyx this manual covers information how to customize LyX for
1054  certain output formats, operating systems, languages etc.
1055  It is currently completely out of date and needs a major rewrite and update.
1056  If you do this please assure that your information are given for all OSes
1057  and LaTeX distributions (meaning be as objective as possible).
1058 \end_layout
1059
1060 \begin_layout Standard
1061 There are only 4
1062 \begin_inset space ~
1063 \end_inset
1064
1065 rules in editing the docs:
1066 \end_layout
1067
1068 \begin_layout Enumerate
1069 If you are not the maintainer of a doc file or a chapter/section, you MUST
1070  use change tracking so that the maintainer could review your changes
1071 \end_layout
1072
1073 \begin_layout Enumerate
1074 Respect the formatting of the document.
1075  The different files use different formatting styles.
1076  That is OK and has historic reasons nobody fully know ;-).
1077  But it is important to be consistent within one file.
1078 \end_layout
1079
1080 \begin_layout Enumerate
1081 All changes you make to a file in one language MUST also go the file in
1082  the other actively maintained languages.
1083  Normally the maintainer does this for you, if you are the maintainer, you
1084  must do this by copying or changing the changed or added text to the other
1085  files so that the translators sees the blue underlined text and know what
1086  they have to translate and what was changed.
1087 \end_layout
1088
1089 \begin_layout Enumerate
1090 You MUST assure that the document is compilable as
1091 \begin_inset Quotes eld
1092 \end_inset
1093
1094 PDF (pdflatex)
1095 \begin_inset Quotes erd
1096 \end_inset
1097
1098  after your changes.
1099 \end_layout
1100
1101 \end_body
1102 \end_document