lib/doc/Development.lyx

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