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