lib/doc/Development.lyx

   1 #LyX 2.1 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 470
   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 false
  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 numerical
  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.1.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 \end_layout
 199
 200 \begin_layout Standard
 201 When you ware working on a new feature you may ask yourself whether it needs
 202  an update of the .lyx file format number.
 203  Whether an update is needed or not is not always obvious.
 204  Below you can find a list of reasons for file format updates with explanations:
 205 \end_layout
 206
 207 \begin_layout Description
 208 New
 209 \begin_inset space ~
 210 \end_inset
 211
 212 document
 213 \begin_inset space ~
 214 \end_inset
 215
 216 setting Whenever you introduce a new setting that is stored in the document
 217  header, a file format update is needed.
 218  This is also true if you add a new valid value to an existing setting,
 219  e.g.
 220  a new language that is stored in
 221 \begin_inset Flex Code
 222 status collapsed
 223
 224 \begin_layout Plain Layout
 225
 226 \backslash
 227 language
 228 \end_layout
 229
 230 \end_inset
 231
 232 .
 233 \end_layout
 234
 235 \begin_layout Description
 236 Removed
 237 \begin_inset space ~
 238 \end_inset
 239
 240 document
 241 \begin_inset space ~
 242 \end_inset
 243
 244 setting If a certain setting becomes obsolete and gets removed, a file format
 245  update is needed.
 246 \end_layout
 247
 248 \begin_layout Description
 249 New
 250 \begin_inset space ~
 251 \end_inset
 252
 253 inset Of course a new inset requires a file format update.
 254 \end_layout
 255
 256 \begin_layout Description
 257 New
 258 \begin_inset space ~
 259 \end_inset
 260
 261 style in any layout file or module shipped with LyX, or new shipped layout
 262  file or module.
 263  These requirements are currently under discussion and might change in the
 264  future.
 265 \end_layout
 266
 267 \begin_layout Description
 268 Automatically
 269 \begin_inset space ~
 270 \end_inset
 271
 272 loaded
 273 \begin_inset space ~
 274 \end_inset
 275
 276 math
 277 \begin_inset space ~
 278 \end_inset
 279
 280 package Any new math package that is automatically loaded needs a file format
 281  update.
 282  The reason for this is that there is no true ERT inset for math formulas:
 283  Each command is parsed, and if a user happens to defne a local command
 284  with the same name as a command that triggers an automatic load of a package,
 285  he needs to be able to switch off the automatic loading of that package.
 286  This switch is stored by the
 287 \begin_inset Flex Code
 288 status collapsed
 289
 290 \begin_layout Plain Layout
 291 use_package
 292 \end_layout
 293
 294 \end_inset
 295
 296  header setting.
 297 \end_layout
 298
 299 \begin_layout Standard
 300 If you are still unsure, please ask on the development list.
 301 \end_layout
 302
 303 \begin_layout Section
 304 How to update the file format number of .lyx files
 305 \end_layout
 306
 307 \begin_layout Standard
 308 Once you came to the conclusion that a file format update is needed you
 309  should use the following procedure to perform the update:
 310 \end_layout
 311
 312 \begin_layout Enumerate
 313 Implement and test the new feature, including the reading and writing of
 314  .lyx files.
 315  Note that any file produced at this stage does not use a valid format,
 316  so do not use this version of LyX for working on any important documents.
 317 \end_layout
 318
 319 \begin_layout Enumerate
 320 Describe the new format in
 321 \begin_inset Flex Code
 322 status collapsed
 323
 324 \begin_layout Plain Layout
 325 development/FORMAT
 326 \end_layout
 327
 328 \end_inset
 329
 330 .
 331 \end_layout
 332
 333 \begin_layout Enumerate
 334 Update the LyX file format number in
 335 \begin_inset Flex Code
 336 status collapsed
 337
 338 \begin_layout Plain Layout
 339 src/version.h
 340 \end_layout
 341
 342 \end_inset
 343
 344 .
 345 \end_layout
 346
 347 \begin_layout Enumerate
 348 Add an entry to both format lists (for conversion and reversion) in
 349 \begin_inset Flex Code
 350 status collapsed
 351
 352 \begin_layout Plain Layout
 353 lib/lyx2lyx_lyx2lyx_2_1.py
 354 \end_layout
 355
 356 \end_inset
 357
 358 .
 359  Add a conversion routine if needed (e.g.
 360  a new header setting always needs a conversion that adds the new setting,
 361  a new document language does not need one).
 362  Add a reversion routine if needed.
 363  While the conversion routine is required to produce a document that is
 364  equivalent to the old version, the requirements of the reversion are not
 365  that strict.
 366  If possible, try to produce a proper reversion, using ERT if needed, but
 367  for some features this might be too complicated.
 368  In this case, the minimum requirement of the reversion routine is that
 369  it produces a valid document which can be read by an older LyX.
 370  If absolutely needed, even data loss is allowed for the reversion.
 371 \end_layout
 372
 373 \begin_layout Enumerate
 374 Since tex2lyx has several implicit file format dependencies caused by sharing
 375  code with LyX, updating the file format of .lyx files produced by tex2lyx
 376  at the same time as updating the main .lyx file format is strongly recommended.
 377  Therefore, a compiler warning will be issued if the LyX and tex2lyx .lyx
 378  file format numbers differ.
 379  In many cases the tex2lyx update requires only the first and last item
 380  of the list below:
 381 \end_layout
 382
 383 \begin_deeper
 384 \begin_layout Enumerate
 385 Update the tex2lyx file format number in
 386 \begin_inset Flex Code
 387 status collapsed
 388
 389 \begin_layout Plain Layout
 390 src/version.h
 391 \end_layout
 392
 393 \end_inset
 394
 395 .
 396 \end_layout
 397
 398 \begin_layout Enumerate
 399 If the lyx2lyx conversion from the old to the new format is empty, or if
 400  tex2lyx does not yet output the changed feature, you do not need any further
 401  tex2lyx changes.
 402  Otherwise, search for the changed feature in tex2lyx, and adjust the output
 403  according to the lyx2lyx changes.
 404 \end_layout
 405
 406 \begin_layout Enumerate
 407 Update the tex2lyx test references as described in
 408 \begin_inset CommandInset ref
 409 LatexCommand formatted
 410 reference "sec:Updating-test-references"
 411
 412 \end_inset
 413
 414 .
 415 \end_layout
 416
 417 \end_deeper
 418 \begin_layout Enumerate
 419 If you did not implement full tex2lyx support of the new feature, add a
 420  line to
 421 \begin_inset Flex Code
 422 status collapsed
 423
 424 \begin_layout Plain Layout
 425 src/tex2lyx/TODO.txt
 426 \end_layout
 427
 428 \end_inset
 429
 430  describing the missing bits.
 431  Note that it is perfectly fine if you do not add full tex2lyx support for
 432  a new feature: The updating recommendation above is only issued for the
 433  syntax of the produced .lyx file.
 434  It is no problem if some features supported by LyX are still output as
 435  ERT by tex2lyx, since the problems in the past that resulted in the update
 436  recommendation were related to mixed version syntax, not ERT.
 437 \end_layout
 438
 439 \begin_layout Section
 440 Backporting new styles to the stable version
 441 \end_layout
 442
 443 \begin_layout Standard
 444 Starting with the stable LyX 2.1 branch, there is a mechanism in place to
 445  backport new styles to the stable version without the need to update the
 446  file format.
 447  The basic idea is that the new style definition is automatically copied
 448  to the document preamble, so that it can even be used by older minor revisions
 449  that did not yet include the style.
 450  To backport a new style to the stable version, the following steps are
 451  needed:
 452 \end_layout
 453
 454 \begin_layout Enumerate
 455 Add the line
 456 \begin_inset Flex Code
 457 status collapsed
 458
 459 \begin_layout Plain Layout
 460 ForceLocal -1
 461 \end_layout
 462
 463 \end_inset
 464
 465  to the style definition in the development version.
 466 \end_layout
 467
 468 \begin_layout Enumerate
 469 Copy the style definition to the stable version, but use
 470 \begin_inset Flex Code
 471 status collapsed
 472
 473 \begin_layout Plain Layout
 474 ForceLocal 1
 475 \end_layout
 476
 477 \end_inset
 478
 479  instead.
 480  If needed adjust the format to the one used by the stable version (see
 481  the customization manual for details of the layout file format).
 482 \end_layout
 483
 484 \begin_layout Enumerate
 485 For each update of the style in a later stable version, increase the argument
 486  of
 487 \begin_inset Flex Code
 488 status collapsed
 489
 490 \begin_layout Plain Layout
 491 ForceLocal
 492 \end_layout
 493
 494 \end_inset
 495
 496  by one (in the stable version, the development version should not be touched).
 497 \end_layout
 498
 499 \begin_layout Standard
 500 For details about the
 501 \begin_inset Flex Code
 502 status collapsed
 503
 504 \begin_layout Plain Layout
 505 ForceLocal
 506 \end_layout
 507
 508 \end_inset
 509
 510  flag see the customization manual.
 511  No
 512 \begin_inset Flex Code
 513 status collapsed
 514
 515 \begin_layout Plain Layout
 516 lyx2lyx
 517 \end_layout
 518
 519 \end_inset
 520
 521  support is needed for backported styles: Since the style of the development
 522  version has an infinite version number, it will always be used.
 523  Furthermore, since its version number is less than one, the style will
 524  not be written anymore to the document header for files saved by the new
 525  version.
 526 \end_layout
 527
 528 \begin_layout Chapter
 529 Tests
 530 \end_layout
 531
 532 \begin_layout Standard
 533 Automated tests are an important tool to detect bugs and regressions in
 534  software development.
 535  Some projects like gcc even require each bug fix to be accompanied by a
 536  test case for the automatic test suite, that would detect this bug.
 537  Testing interactive features automatically is of course very hard, but
 538  core functionality like document import and export can be tested quite
 539  easily, and some tests of this kind exist.
 540 \end_layout
 541
 542 \begin_layout Section
 543 LyX tests
 544 \end_layout
 545
 546 \begin_layout Standard
 547 Some tests are located in the
 548 \begin_inset Flex Code
 549 status collapsed
 550
 551 \begin_layout Plain Layout
 552 development/autotests
 553 \end_layout
 554
 555 \end_inset
 556
 557  subfolder of the LyX source code distribution.
 558 \end_layout
 559
 560 \begin_layout Subsection
 561 Running the tests
 562 \end_layout
 563
 564 \begin_layout Standard
 565 The LyX tests can be run by the commands
 566 \begin_inset Flex Code
 567 status collapsed
 568
 569 \begin_layout Plain Layout
 570 make test
 571 \end_layout
 572
 573 \end_inset
 574
 575  (cmake) in the
 576 \begin_inset Flex Code
 577 status collapsed
 578
 579 \begin_layout Plain Layout
 580 autotests
 581 \end_layout
 582
 583 \end_inset
 584
 585  subfolder of the build directory.
 586 \begin_inset Note Note
 587 status open
 588
 589 \begin_layout Plain Layout
 590 FIXME: Is this possible with autotools?
 591 \end_layout
 592
 593 \end_inset
 594
 595
 596 \end_layout
 597
 598 \begin_layout Section
 599 tex2lyx tests
 600 \end_layout
 601
 602 \begin_layout Standard
 603 The tex2lyx tests are located in the
 604 \begin_inset Flex Code
 605 status collapsed
 606
 607 \begin_layout Plain Layout
 608 src/tex2lyx/test
 609 \end_layout
 610
 611 \end_inset
 612
 613  subfolder of the LyX source code distribution.
 614  The actual testing is performed by the simple python script
 615 \begin_inset Flex Code
 616 status collapsed
 617
 618 \begin_layout Plain Layout
 619 src/tex2lyx/test/runtests.py
 620 \end_layout
 621
 622 \end_inset
 623
 624 .
 625  Each test consists of two files:
 626 \begin_inset Flex Code
 627 status collapsed
 628
 629 \begin_layout Plain Layout
 630 <test name>.tex
 631 \end_layout
 632
 633 \end_inset
 634
 635  contains the LaTeX code that should be tested.
 636
 637 \begin_inset Flex Code
 638 status collapsed
 639
 640 \begin_layout Plain Layout
 641 <test name>.lyx.lyx
 642 \end_layout
 643
 644 \end_inset
 645
 646  contains the expected output of tex2lyx.
 647  When a test is run, the actual produced output is compared with the stored
 648  reference output.
 649  The test passes if both are identical.
 650  The test machinery is also able to generate a file
 651 \begin_inset Flex Code
 652 status collapsed
 653
 654 \begin_layout Plain Layout
 655 <test name>.lyx.tex
 656 \end_layout
 657
 658 \end_inset
 659
 660  by exporting the produced .lyx file with LyX again.
 661  This may be useful for roundtrip comparisons.
 662 \end_layout
 663
 664 \begin_layout Subsection
 665 Running the tests
 666 \end_layout
 667
 668 \begin_layout Standard
 669 The tex2lyx tests can be run by the commands
 670 \begin_inset Flex Code
 671 status collapsed
 672
 673 \begin_layout Plain Layout
 674 make test
 675 \end_layout
 676
 677 \end_inset
 678
 679  (cmake) or
 680 \begin_inset Flex Code
 681 status collapsed
 682
 683 \begin_layout Plain Layout
 684 make check
 685 \end_layout
 686
 687 \end_inset
 688
 689  (autotools) in the
 690 \begin_inset Flex Code
 691 status collapsed
 692
 693 \begin_layout Plain Layout
 694 src/tex2lyx
 695 \end_layout
 696
 697 \end_inset
 698
 699  subfolder of the build directory.
 700  If a test fails, the differences between the expected and actual results
 701  are output in unified diff format.
 702 \end_layout
 703
 704 \begin_layout Subsection
 705 Updating test references
 706 \begin_inset CommandInset label
 707 LatexCommand label
 708 name "sec:Updating-test-references"
 709
 710 \end_inset
 711
 712
 713 \end_layout
 714
 715 \begin_layout Standard
 716 In some cases a changed tex2lyx output is not a test failure, but wanted,
 717  e.g.
 718  if a tex2lyx bug was fixed, or a new feature was added.
 719  In these cases the stored references need to be updated.
 720  To do so, call
 721 \begin_inset Flex Code
 722 status collapsed
 723
 724 \begin_layout Plain Layout
 725 make updatetests
 726 \end_layout
 727
 728 \end_inset
 729
 730  (autotools)
 731 \begin_inset Note Note
 732 status open
 733
 734 \begin_layout Plain Layout
 735 FIXME: Add cmake command
 736 \end_layout
 737
 738 \end_inset
 739
 740  in the
 741 \begin_inset Flex Code
 742 status collapsed
 743
 744 \begin_layout Plain Layout
 745 src/tex2lyx
 746 \end_layout
 747
 748 \end_inset
 749
 750  subfolder of the build directory.
 751  For convenience, this command does also produce re-exported roundtrip .lyx.tex
 752  files.
 753  Please examine the changed output carefully before committing the changed
 754  files to the repository: Since the test machinery does not do a roundtrip
 755  test .tex
 756 \begin_inset Formula $\Rightarrow$
 757 \end_inset
 758
 759  .lyx
 760 \begin_inset Formula $\Rightarrow$
 761 \end_inset
 762
 763  .tex, and does not compare the produced dvi or pdf output, it assumes that
 764  the stored .lyx reference produces correct output if processed by LyX.
 765  There is only one chance to detect wrong output: before committing a new
 766  reference.
 767  Once it is committed, it is quite difficult to verify whether it is correct.
 768 \end_layout
 769
 770 \begin_layout Subsection
 771 Adding a new test
 772 \end_layout
 773
 774 \begin_layout Standard
 775 In many cases tests for new features may be added to one of the existing
 776  test files, but sometimes this is not possible or not wanted.
 777  Then a new test file needs to be added:
 778 \end_layout
 779
 780 \begin_layout Enumerate
 781 Create the new file
 782 \begin_inset Flex Code
 783 status collapsed
 784
 785 \begin_layout Plain Layout
 786 src/tex2lyx/test/<test name>.tex
 787 \end_layout
 788
 789 \end_inset
 790
 791  and run tex2lyx in roundtrip mode to produce the file
 792 \begin_inset Flex Code
 793 status collapsed
 794
 795 \begin_layout Plain Layout
 796 src/tex2lyx/test/<test name>.lyx.lyx
 797 \end_layout
 798
 799 \end_inset
 800
 801 .
 802  This file will be the new reference.
 803 \end_layout
 804
 805 \begin_layout Enumerate
 806 Once you confirmed that the tex2lyx output is correct, add the new files
 807  to the corresponding lists in
 808 \begin_inset Flex Code
 809 status collapsed
 810
 811 \begin_layout Plain Layout
 812 src/tex2lyx/test/runtests.py
 813 \end_layout
 814
 815 \end_inset
 816
 817 ,
 818 \begin_inset Flex Code
 819 status collapsed
 820
 821 \begin_layout Plain Layout
 822 src/tex2lyx/Makefile.am
 823 \end_layout
 824
 825 \end_inset
 826
 827  and
 828 \begin_inset Flex Code
 829 status collapsed
 830
 831 \begin_layout Plain Layout
 832 src/tex2lyx/test/CMakeLists.txt
 833 \end_layout
 834
 835 \end_inset
 836
 837 .
 838 \end_layout
 839
 840 \begin_layout Enumerate
 841 Commit the changes to the repository, or send a patch to the development
 842  list and ask for committing if you do not have commit rights.
 843 \end_layout
 844
 845 \end_body
 846 \end_document