lib/doc/Development.lyx

   1 #LyX 2.1 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 462
   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 esint 0
  72 \use_package mathdots 1
  73 \use_package mathtools 0
  74 \use_package mhchem 1
  75 \use_package stackrel 0
  76 \use_package stmaryrd 0
  77 \use_package undertilde 0
  78 \cite_engine basic
  79 \cite_engine_type numerical
  80 \biblio_style plain
  81 \use_bibtopic false
  82 \use_indices false
  83 \paperorientation portrait
  84 \suppress_date false
  85 \justification true
  86 \use_refstyle 0
  87 \notefontcolor #0000ff
  88 \index Index
  89 \shortcut idx
  90 \color #008000
  91 \end_index
  92 \secnumdepth 3
  93 \tocdepth 3
  94 \paragraph_separation indent
  95 \paragraph_indentation default
  96 \quotes_language english
  97 \papercolumns 1
  98 \papersides 2
  99 \paperpagestyle headings
 100 \tracking_changes false
 101 \output_changes false
 102 \html_math_output 0
 103 \html_css_as_file 0
 104 \html_be_strict true
 105 \end_header
 106
 107 \begin_body
 108
 109 \begin_layout Title
 110 Developing LyX
 111 \end_layout
 112
 113 \begin_layout Subtitle
 114 Version 2.1.x
 115 \end_layout
 116
 117 \begin_layout Author
 118 by the LyX Team
 119 \begin_inset Foot
 120 status collapsed
 121
 122 \begin_layout Plain Layout
 123 \noindent
 124 If you have comments or error corrections, please send them to the LyX Documenta
 125 tion mailing list,
 126 \begin_inset Flex Code
 127 status collapsed
 128
 129 \begin_layout Plain Layout
 130 \noindent
 131 <lyx-docs@lists.lyx.org>
 132 \end_layout
 133
 134 \end_inset
 135
 136 .
 137 \end_layout
 138
 139 \end_inset
 140
 141
 142 \end_layout
 143
 144 \begin_layout Standard
 145 \begin_inset CommandInset toc
 146 LatexCommand tableofcontents
 147
 148 \end_inset
 149
 150
 151 \end_layout
 152
 153 \begin_layout Chapter
 154 Introduction
 155 \end_layout
 156
 157 \begin_layout Standard
 158 This manual documents some aspects of LyX development.
 159  It is currently rather incomplete, but will hopefully be extended in the
 160  future.
 161  Meanwhile, additional information can be found in the
 162 \begin_inset Flex Code
 163 status collapsed
 164
 165 \begin_layout Plain Layout
 166 development
 167 \end_layout
 168
 169 \end_inset
 170
 171  subfolder of the LyX source code distribution.
 172  This document is not translated, since the development language of LyX
 173  is english.
 174  If you want to use LyX you don't need to read this manual.
 175  However, if you want to learn more about how LyX is developed, or even
 176  want to participate in LyX development, you may find some interesting informati
 177 on.
 178 \end_layout
 179
 180 \begin_layout Chapter
 181 File formats
 182 \end_layout
 183
 184 \begin_layout Standard
 185 LyX uses several custom file formats for configuration files and documents.
 186  This chapter contains some background concerning these file formats.
 187  Several file formats are also described in detail in the regular user documenta
 188 tion.
 189 \end_layout
 190
 191 \begin_layout Section
 192 File Format Numbers
 193 \end_layout
 194
 195 \begin_layout Section
 196 When is an update of the .lyx file format number needed?
 197 \end_layout
 198
 199 \begin_layout Standard
 200 When you ware working on a new feature you may ask yourself whether it needs
 201  an update of the .lyx file format number.
 202  Whether an update is needed or not is not always obvious.
 203  Below you can find a list of reasons for file format updates with explanations:
 204 \end_layout
 205
 206 \begin_layout Description
 207 New
 208 \begin_inset space ~
 209 \end_inset
 210
 211 document
 212 \begin_inset space ~
 213 \end_inset
 214
 215 setting Whenever you introduce a new setting that is stored in the document
 216  header, a file format update is needed.
 217  This is also true if you add a new valid value to an existing setting,
 218  e.g.
 219  a new language that is stored in
 220 \begin_inset Flex Code
 221 status collapsed
 222
 223 \begin_layout Plain Layout
 224
 225 \backslash
 226 language
 227 \end_layout
 228
 229 \end_inset
 230
 231 .
 232 \end_layout
 233
 234 \begin_layout Description
 235 Removed
 236 \begin_inset space ~
 237 \end_inset
 238
 239 document
 240 \begin_inset space ~
 241 \end_inset
 242
 243 setting If a certain setting becomes obsolete and gets removed, a file format
 244  update is needed.
 245 \end_layout
 246
 247 \begin_layout Description
 248 New
 249 \begin_inset space ~
 250 \end_inset
 251
 252 inset Of course a new inset requires a file format update.
 253 \end_layout
 254
 255 \begin_layout Description
 256 New
 257 \begin_inset space ~
 258 \end_inset
 259
 260 style in any layout file or module shipped with LyX, or new shipped layout
 261  file or module.
 262  These requirements are currently under discussion and might change in the
 263  future.
 264 \end_layout
 265
 266 \begin_layout Description
 267 Automatically
 268 \begin_inset space ~
 269 \end_inset
 270
 271 loaded
 272 \begin_inset space ~
 273 \end_inset
 274
 275 math
 276 \begin_inset space ~
 277 \end_inset
 278
 279 package Any new math package that is automatically loaded needs a file format
 280  update.
 281  The reason for this is that there is no true ERT inset for math formulas:
 282  Each command is parsed, and if a user happens to defne a local command
 283  with the same name as a command that triggers an automatic load of a package,
 284  he needs to be able to switch off the automatic loading of that package.
 285  This switch is stored by the
 286 \begin_inset Flex Code
 287 status collapsed
 288
 289 \begin_layout Plain Layout
 290 use_package
 291 \end_layout
 292
 293 \end_inset
 294
 295  header setting.
 296 \end_layout
 297
 298 \begin_layout Standard
 299 If you are still unsure, please ask on the development list.
 300 \end_layout
 301
 302 \begin_layout Section
 303 How to update the file format number of .lyx files
 304 \end_layout
 305
 306 \begin_layout Standard
 307 Once you came to the conclusion that a file format update is needed you
 308  should use the following procedure to perform the update:
 309 \end_layout
 310
 311 \begin_layout Enumerate
 312 Implement and test the new feature, including the reading and writing of
 313  .lyx files.
 314  Note that any file produced at this stage does not use a valid format,
 315  so do not use this version of LyX for working on any important documents.
 316 \end_layout
 317
 318 \begin_layout Enumerate
 319 Describe the new format in
 320 \begin_inset Flex Code
 321 status collapsed
 322
 323 \begin_layout Plain Layout
 324 development/FORMAT
 325 \end_layout
 326
 327 \end_inset
 328
 329 .
 330 \end_layout
 331
 332 \begin_layout Enumerate
 333 Update the LyX file format number in
 334 \begin_inset Flex Code
 335 status collapsed
 336
 337 \begin_layout Plain Layout
 338 src/version.h
 339 \end_layout
 340
 341 \end_inset
 342
 343 .
 344 \end_layout
 345
 346 \begin_layout Enumerate
 347 Add an entry to both format lists (for conversion and reversion) in
 348 \begin_inset Flex Code
 349 status collapsed
 350
 351 \begin_layout Plain Layout
 352 lib/lyx2lyx_lyx2lyx_2_1.py
 353 \end_layout
 354
 355 \end_inset
 356
 357 .
 358  Add a conversion routine if needed (e.g.
 359  a new header setting always needs a conversion that adds the new setting,
 360  a new document language does not need one).
 361  Add a reversion routine if needed.
 362  While the conversion routine is required to produce a document that is
 363  equivalent to the old version, the requirements of the reversion are not
 364  that strict.
 365  If possible, try to produce a proper reversion, using ERT if needed, but
 366  for some features this might be too complicated.
 367  In this case, the minimum requirement of the reversion routine is that
 368  it produces a valid document which can be read by an older LyX.
 369  If absolutely needed, even data loss is allowed for the reversion.
 370 \end_layout
 371
 372 \begin_layout Enumerate
 373 Since tex2lyx has several implicit file format dependencies caused by sharing
 374  code with LyX, updating the file format of .lyx files produced by tex2lyx
 375  at the same time as updating the main .lyx file format is strongly recommended.
 376  Therefore, a compiler warning will be issued if the LyX and tex2lyx .lyx
 377  file format numbers differ.
 378  In many cases the tex2lyx update requires only the first and last item
 379  of the list below:
 380 \end_layout
 381
 382 \begin_deeper
 383 \begin_layout Enumerate
 384 Update the tex2lyx file format number in
 385 \begin_inset Flex Code
 386 status collapsed
 387
 388 \begin_layout Plain Layout
 389 src/version.h
 390 \end_layout
 391
 392 \end_inset
 393
 394 .
 395 \end_layout
 396
 397 \begin_layout Enumerate
 398 If the lyx2lyx conversion from the old to the new format is empty, or if
 399  tex2lyx does not yet output the changed feature, you do not need any further
 400  tex2lyx changes.
 401  Otherwise, search for the changed feature in tex2lyx, and adjust the output
 402  according to the lyx2lyx changes.
 403 \end_layout
 404
 405 \begin_layout Enumerate
 406 Update the tex2lyx test references as described in
 407 \begin_inset CommandInset ref
 408 LatexCommand formatted
 409 reference "sec:Updating-test-references"
 410
 411 \end_inset
 412
 413 .
 414 \end_layout
 415
 416 \end_deeper
 417 \begin_layout Enumerate
 418 If you did not implement full tex2lyx support of the new feature, add a
 419  line to
 420 \begin_inset Flex Code
 421 status collapsed
 422
 423 \begin_layout Plain Layout
 424 src/tex2lyx/TODO.txt
 425 \end_layout
 426
 427 \end_inset
 428
 429  describing the missing bits.
 430  Note that it is perfectly fine if you do not add full tex2lyx support for
 431  a new feature: The updating recommendation above is only issued for the
 432  syntax of the produced .lyx file.
 433  It is no problem if some features supported by LyX are still output as
 434  ERT by tex2lyx, since the problems in the past that resulted in the update
 435  recommendation were related to mixed version syntax, not ERT.
 436 \end_layout
 437
 438 \begin_layout Chapter
 439 Tests
 440 \end_layout
 441
 442 \begin_layout Standard
 443 Automated tests are an important tool to detect bugs and regressions in
 444  software development.
 445  Some projects like gcc even require each bug fix to be accompanied by a
 446  test case for the automatic test suite, that would detect this bug.
 447  Testing interactive features automatically is of course very hard, but
 448  core functionality like document import and export can be tested quite
 449  easily, and some tests of this kind exist.
 450 \end_layout
 451
 452 \begin_layout Section
 453 LyX tests
 454 \end_layout
 455
 456 \begin_layout Standard
 457 Some tests are located in the
 458 \begin_inset Flex Code
 459 status collapsed
 460
 461 \begin_layout Plain Layout
 462 development/autotests
 463 \end_layout
 464
 465 \end_inset
 466
 467  subfolder of the LyX source code distribution.
 468 \end_layout
 469
 470 \begin_layout Subsection
 471 Running the tests
 472 \end_layout
 473
 474 \begin_layout Standard
 475 The LyX tests can be run by the commands
 476 \begin_inset Flex Code
 477 status collapsed
 478
 479 \begin_layout Plain Layout
 480 make test
 481 \end_layout
 482
 483 \end_inset
 484
 485  (cmake) in the
 486 \begin_inset Flex Code
 487 status collapsed
 488
 489 \begin_layout Plain Layout
 490 autotests
 491 \end_layout
 492
 493 \end_inset
 494
 495  subfolder of the build directory.
 496 \begin_inset Note Note
 497 status open
 498
 499 \begin_layout Plain Layout
 500 FIXME: Is this possible with autotools?
 501 \end_layout
 502
 503 \end_inset
 504
 505
 506 \end_layout
 507
 508 \begin_layout Section
 509 tex2lyx tests
 510 \end_layout
 511
 512 \begin_layout Standard
 513 The tex2lyx tests are located in the
 514 \begin_inset Flex Code
 515 status collapsed
 516
 517 \begin_layout Plain Layout
 518 src/tex2lyx/test
 519 \end_layout
 520
 521 \end_inset
 522
 523  subfolder of the LyX source code distribution.
 524  The actual testing is performed by the simple python script
 525 \begin_inset Flex Code
 526 status collapsed
 527
 528 \begin_layout Plain Layout
 529 src/tex2lyx/test/runtests.py
 530 \end_layout
 531
 532 \end_inset
 533
 534 .
 535  Each test consists of two files:
 536 \begin_inset Flex Code
 537 status collapsed
 538
 539 \begin_layout Plain Layout
 540 <test name>.tex
 541 \end_layout
 542
 543 \end_inset
 544
 545  contains the LaTeX code that should be tested.
 546
 547 \begin_inset Flex Code
 548 status collapsed
 549
 550 \begin_layout Plain Layout
 551 <test name>.lyx.lyx
 552 \end_layout
 553
 554 \end_inset
 555
 556  contains the expected output of tex2lyx.
 557  When a test is run, the actual produced output is compared with the stored
 558  reference output.
 559  The test passes if both are identical.
 560  The test machinery is also able to generate a file
 561 \begin_inset Flex Code
 562 status collapsed
 563
 564 \begin_layout Plain Layout
 565 <test name>.lyx.tex
 566 \end_layout
 567
 568 \end_inset
 569
 570  by exporting the produced .lyx file with LyX again.
 571  This may be useful for roundtrip comparisons.
 572 \end_layout
 573
 574 \begin_layout Subsection
 575 Running the tests
 576 \end_layout
 577
 578 \begin_layout Standard
 579 The tex2lyx tests can be run by the commands
 580 \begin_inset Flex Code
 581 status collapsed
 582
 583 \begin_layout Plain Layout
 584 make test
 585 \end_layout
 586
 587 \end_inset
 588
 589  (cmake) or
 590 \begin_inset Flex Code
 591 status collapsed
 592
 593 \begin_layout Plain Layout
 594 make check
 595 \end_layout
 596
 597 \end_inset
 598
 599  (autotools) in the
 600 \begin_inset Flex Code
 601 status collapsed
 602
 603 \begin_layout Plain Layout
 604 src/tex2lyx
 605 \end_layout
 606
 607 \end_inset
 608
 609  subfolder of the build directory.
 610  If a test fails, the differences between the expected and actual results
 611  are output in unified diff format.
 612 \end_layout
 613
 614 \begin_layout Subsection
 615 Updating test references
 616 \begin_inset CommandInset label
 617 LatexCommand label
 618 name "sec:Updating-test-references"
 619
 620 \end_inset
 621
 622
 623 \end_layout
 624
 625 \begin_layout Standard
 626 In some cases a changed tex2lyx output is not a test failure, but wanted,
 627  e.g.
 628  if a tex2lyx bug was fixed, or a new feature was added.
 629  In these cases the stored references need to be updated.
 630  To do so, call
 631 \begin_inset Flex Code
 632 status collapsed
 633
 634 \begin_layout Plain Layout
 635 make updatetests
 636 \end_layout
 637
 638 \end_inset
 639
 640  (autotools)
 641 \begin_inset Note Note
 642 status open
 643
 644 \begin_layout Plain Layout
 645 FIXME: Add cmake command
 646 \end_layout
 647
 648 \end_inset
 649
 650  in the
 651 \begin_inset Flex Code
 652 status collapsed
 653
 654 \begin_layout Plain Layout
 655 src/tex2lyx
 656 \end_layout
 657
 658 \end_inset
 659
 660  subfolder of the build directory.
 661  For convenience, this command does also produce re-exported roundtrip .lyx.tex
 662  files.
 663  Please examine the changed output carefully before committing the changed
 664  files to the repository: Since the test machinery does not do a roundtrip
 665  test .tex
 666 \begin_inset Formula $\Rightarrow$
 667 \end_inset
 668
 669  .lyx
 670 \begin_inset Formula $\Rightarrow$
 671 \end_inset
 672
 673  .tex, and does not compare the produced dvi or pdf output, it assumes that
 674  the stored .lyx reference produces correct output if processed by LyX.
 675  There is only one chance to detect wrong output: before committing a new
 676  reference.
 677  Once it is committed, it is quite difficult to verify whether it is correct.
 678 \end_layout
 679
 680 \begin_layout Subsection
 681 Adding a new test
 682 \end_layout
 683
 684 \begin_layout Standard
 685 In many cases tests for new features may be added to one of the existing
 686  test files, but sometimes this is not possible or not wanted.
 687  Then a new test file needs to be added:
 688 \end_layout
 689
 690 \begin_layout Enumerate
 691 Create the new file
 692 \begin_inset Flex Code
 693 status collapsed
 694
 695 \begin_layout Plain Layout
 696 src/tex2lyx/test/<test name>.tex
 697 \end_layout
 698
 699 \end_inset
 700
 701  and run tex2lyx in roundtrip mode to produce the file
 702 \begin_inset Flex Code
 703 status collapsed
 704
 705 \begin_layout Plain Layout
 706 src/tex2lyx/test/<test name>.lyx.lyx
 707 \end_layout
 708
 709 \end_inset
 710
 711 .
 712  This file will be the new reference.
 713 \end_layout
 714
 715 \begin_layout Enumerate
 716 Once you confirmed that the tex2lyx output is correct, add the new files
 717  to the corresponding lists in
 718 \begin_inset Flex Code
 719 status collapsed
 720
 721 \begin_layout Plain Layout
 722 src/tex2lyx/test/runtests.py
 723 \end_layout
 724
 725 \end_inset
 726
 727 ,
 728 \begin_inset Flex Code
 729 status collapsed
 730
 731 \begin_layout Plain Layout
 732 src/tex2lyx/Makefile.am
 733 \end_layout
 734
 735 \end_inset
 736
 737  and
 738 \begin_inset Flex Code
 739 status collapsed
 740
 741 \begin_layout Plain Layout
 742 src/tex2lyx/test/CMakeLists.txt
 743 \end_layout
 744
 745 \end_inset
 746
 747 .
 748 \end_layout
 749
 750 \begin_layout Enumerate
 751 Commit the changes to the repository, or send a patch to the development
 752  list and ask for committing if you do not have commit rights.
 753 \end_layout
 754
 755 \end_body
 756 \end_document