TODO

   1 -*-outline-layout:(2 (-1 -1 0 :) 0);outline-stylish-prefixes:nil -*-
   2
   3 * GNU LilyPond TODO
   4 Features you cannot find in the doco as working, should be
   5 mentioned here.  This is an assorted collection of stuff that will be
   6 done, might be done, or is an idea that I want to think about
   7
   8 Most of the items are marked in the code as well
   9 Grep for TODO and ugh/ugr/urg.
  10
  11 .* BUGS
  12 . * junk separate mudela versioning.
  13 . * PostScript
  14 .  * header for PS enteredby = "bla <bla@bar.com>"
  15 .  * ps/lily.ps see comments.
  16 . * down tuplet spanner.
  17 . * didot / big point.
  18 . * devise standard for functioning of Vertical_align_element.
  19 . * midi key.
  20 . * Repeats
  21 .  * input/bugs/rep.ly (moved from test)
  22 .  * unfold broken:
  23 .   * without alternatives: repeat unfold 4 { a b c d }
  24 .   * count > alternatives: repeat unfold 79 { a b c d }
  25 \alternative { { c c c c } { d d d d } }
  26 .  * kind of 'initial property' iso fold/volta(semi)/unfold strings
  27 . * fix singleStaffBracket
  28 . * declare performers in \midi
  29 . * fix MIDI
  30 . * \shape 1st dim skipped?
  31 . * turn slope-damping on/off
  32 . * tremolo stuff
  33 . * We need feta-din*.mf files for more sizes than 10.
  34 . * fix dynamics decently, ie. use kerning & ligatures.
  35 . * dots & rest collisions?
  36 . * mudela-book.py
  37 .  * fix \mudelafile{} to have decent functionality
  38 .  * P.P.S. It can be cool in mudela-book to distinguish in
  39 pre,postMudelaExample, whether MudelaExample is epsed or not: ( if
  40 this fragment is floating eps, than 1, otherwise 2). say
  41 preMudelaExample[eps]{}, and change it in document body sometimes.
  42 .  * use less RE's
  43 . * slurs colllide with lyrics.
  44 . * Is there any reasonable way to do this: I would like to have one file
  45 that can generate the same tune in two different modes without having
  46 to go through and rewrite all the music in the other mode.
  47
  48 Long lyrics don't get a space at the end.  They just run right up
  49 against the next lyric.  (I don't think this used to be the case.)
  50
  51 Lyrics and scripts collide.
  52
  53 \key b; \time 4/4; looks bad.  The clef and time signature are too close.
  54
  55 restStyle=mensural doesn't seem to work (lots of characters not found
  56 for rests.fly)
  57 . * Phrasing:  Indicating the textual underlay of a piece, or
  58 otherwise dividing a piece into phrases.
  59
  60 There are distinct ways of specifying the first two (although at
  61 present, they're not properly distinguished) but no distinct way to
  62 specify the third.  Should there be?
  63 . * rest collision minimum dist.
  64 . * a note with a circle after it, meaning:
  65
  66    note + circle = note + 1/4 of its length
  67
  68    the circle is like a dot that's not filled in.  for example, on
  69    page three, the c-sharp on the second line should be a quarter with
  70    a circle, not a quarter tied to a sixteenth.  is this at all
  71    possible with lily?
  72 . * tuplets that are written as "number : note", for example
  73    "3 : [image of a half note here]".  possible?
  74 . * repeat engraver, gallina.ly
  75
  76 . * Matanya's tips:
  77 .  * spacing for prefatory matter
  78 .  * accidentals closer to note head
  79 .  * to space the staffs/staffgroups contained in the score.
  80
  81 In the orchestscore.ly file, I tried:
  82 \paper{
  83     \translator {
  84         \OrchestralScoreContext
  85         minVerticalAlign = 3.0*\staffheight;
  86     }
  87     \translator {
  88         \StaffGroupContext
  89         minVerticalAlign = 3.0*\staffheight;
  90     }
  91     \translator {
  92         \StaffContext
  93         minVerticalAlign = 3.0*\staffheight;
  94     }
  95 }
  96 .  * heavier beams?
  97
  98 .* Cleanups needed
  99 . * Beam
 100 . * Stem
 101 . * Slur
 102 . * Rhythmic_grouping
 103 . * Duration
 104 . * Collision
 105 . * Rest_collision
 106 . * clef grav prop's
 107 . * parser
 108
 109 .* TODO before 1.2
 110 . * Morally pure LilyPond.
 111 .  * Remove mutopia ramblings.
 112 .  * Remove non-free software links.
 113 .  * Remove meta article LilyPond.
 114 . * break priority setting from SCM.
 115 . * Gade score
 116 .  * remove [] in favour of auto-beamer
 117 . * hangOnClef with non-breakable clefs.
 118 . * Aha, the problem is the new TeX code generation for changing fonts.
 119 > (The explanation below is mostly intended for Han-Wen and Jan)
 120 > Before, the font was changed with macros declared separately for
 121 > pure TeX and LaTeX, but now all the fonts are declared directly in
 122 > the generated code using the low-level TeX commands. This circumvents
 123 > the fontencoding mechanism of LaTeX and is a potential source of
 124 > problems also for us users of the Latin-1 character set.
 125 > I think it still works since the inputencoding latin1 is
 126 > declared by ly2dvi, but it still means that e.g. an o with
 127 > umlaut is typeset as a combination of the two symbols 'o' and
 128 > 'umlaut' instead of as a single character, as would be the case
 129 > if fontencoding OT1 had been used. This shouldn't give any
 130 > difference in layout, though. One of the main argument for using
 131 > fontencoding OT1 is for the hyphenation mechanism to work, an
 132 > argument that's clearly irrelevant in our application. Yet we
 133 > see the problem for August.
 134 . * Abstraction for engravers:
 135 .  * make "in-between" engraver (Tie, Extender)
 136 .  * make wide_spanner_engraver (line_group_spanne,r staff_symbol)
 137 . * remove Interval dim_ from Dimension_cache and rename the struct.
 138 . * do scaled fonts generally
 139 . * Spacing.
 140 . * The Lilypond accidental symbols are available through the TeX macros,
 141 \textflat, \textsharp and \textnatural defined in the init file
 142 lilyponddefs.tex. All the symbols are defined in the files fetaXX.tex
 143 where XX corresponds to the size. I don't know where (or even if) they
 144 are installed but they are generated in the mf/out/ directory during the
 145 compilation.
 146 . * make dependencies () a virtual function.
 147 . * one big ly2dvi input that includes *all* tests.
 148 . * store req -> element, element -> element causes for warnings
 149 . * include examples in RPM.
 150 . * fix partial measures in meaningful way.
 151 . * add scripts to bars eg.  |^"bla"
 152 . * relative mode for mi2mu
 153 . * uniformise recent feta contributions.
 154 .  * use SCM and Molecules for {accordeon stuff, }
 155 .  * bigger and fatter 4/4 C
 156 . * sort out directory stuff.
 157 .  * --prefix option?
 158 .  * -I option per filetype?
 159 .  * kpathsea?
 160 . * ly2dvi/lilypond logfile.
 161 . * fractional chord durs.
 162 . * hang Item on Spanner
 163 . * do --safe for PS output?
 164 . * convert-mudela --output
 165 . * Staff_margin (with a partial measure.)
 166 . * fix pletvisibility properties:
 167 .  * bracket on/off/no-bracket-when-beam
 168 .  * num on/off/no-num-when-beam
 169 . * fix: standchen.
 170 . * junk text{sharp,flat,etc}
 171 . * fix convert-mudela manpage
 172 . * decimal point in \paper {}
 173 . * {  \voiceone <a'4.*2/3  d''4.*2/3 fis''4.*2/3>  [g''8 fis'' e''] d''4 |}
 174          and
 175          { \voicetwo  d'4 d'2.*2/3 } spacing
 176 . * tied notes for MIDI
 177 . * sharp / flat on trills (in MIDI ??)
 178 . * scm-ify \property values.
 179 . * move class Lookup {} into scm
 180 . * msgfmt -o check?
 181 . * \breathmark TeX macro
 182 . * add new glyphs to font.ly
 183 . * formatting of input stuff.
 184 . * \notes{ a \< b \cr } vs \notes{ a \< b \! }
 185 . * space after bars?
 186 . * 'hinterfleisch' before bar (e.g. wtk1-fugue2)?
 187 . * Summary of minor spelling irregularities:
 188 .  *  capitalization/use of underscores in property names
 189 .  * fix SkipBars  -> skipBars
 190 . * broken scripts:
 191         lbheel = \script { "bheel" 0 0 -1  0 0 }
 192         rbheel = \script { "bheel" 0 0 1 0 0 }
 193         lbtoe = \script { "btoe" 0 0 -1 0 0 }
 194         rbtoe = \script { "btoe" 0 0 1 0 0 }
 195         lfheel = \script { "fheel" 0 0 -1  0 0 }
 196         rfheel = \script { "fheel" 0 0 1 0 0 }
 197         lftoe = \script { "ftoe" 0 0 -1 0 0 }
 198         rftoe = \script { "ftoe" 0 0 1 0 0 }
 199         and also
 200         portato= \script { "portato" 0 -1 0 1 0 }
 201 . * ly2dvi
 202 .  * bottomnote for ly2dvi
 203 .  * deps for ly2dvi
 204
 205 .* STUFF
 206 . * compulsory hshift
 207 . * Give # lines in linebreaking.
 208 . * arrows on slurs.
 209 . * rewrite context defs using Scheme
 210 . * \selectmusic to cut pieces from music.
 211 . * TODO: merge atom & molecule; make  tree from molecule.
 212 . * Align_element::padding  ?
 213 . * typo checks on property names?
 214 . * use streambufs and iostream
 215         to provide IO handling for TeX stream, mudela stream, data-file.
 216 . * seriously buffer TeX output (do profile of writing .5 mb TeX file.)
 217 . * strip EXEs before installing
 218 . * zip target for binary windows dist (JBR)
 219 . * junking \skip req in lyrics
 220 . * mi2mu empty staffs.
 221 . * use Fourier transformation for rhythmic quantisation.
 222 . * horizontal centering of dynamics
 223 . * $DEPENDENCIES_OUTPUT support
 224 . * Xdvi zooming ?! Try to understand GS garbage collection.
 225 gs: Error: /undefined in draw_beam
 226 gs: Operand stack:
 227 . * fix vertical alignment and stafflines
 228 . * declaring Performers
 229 . * *.yo: fix pod manpage layout legacy
 230 . * text-items clash with stems/beams
 231 . * --include, -I option for ly2dvi (pass on to lily)
 232 . * fix placement of beam-less abbrev
 233 . * \meter 3/4;
 234         <{\voiceone cis4. cis8 cis4 | cis4 cis cis | r1 }
 235          {\voicetwo cis,4 r r | r2. | r1 }> |
 236         }
 237 . * Musical_pitch (analogous to Duration and Rhythmic_req)
 238           think about, analogous to pitch:
 239            * { a4 a16 } c <-- duration of c?
 240            * < a4 b8 > c <-- duration of c?
 241 . * \tempo 4. = 90;
 242 . * fix audio-items (don't use (input) requests, but copy data)
 243 . * make sure all ex's have a mudela-version
 244 . * do rest-collisions for Multi_measure_rests as well.
 245 . * split error/warning in error/warning/non_fatal_error
 246 . * add a Duration_convert member to Duration_iter to set parameters.
 247         Junk global duration settings.
 248 . * en-,discouraged linebreaking:
 249 .  * handle DISALLOW < penalty > FORCE
 250 .  * discourage breaking of slurs
 251 . * fix variable define/lookup parser global<->paper
 252 . * fix title/instrument placements; see input/test/title.ly
 253 . * <\voiceone c4. \voicetwo c4>
 254 . * add full cello suites to web site (kom op, Maarten!)
 255 . * add mudela-book-doc source to webstie.
 256 . * Rethink Time_description
 257 \cadenza , \meter, \grouping should all be \properties
 258 . * rename
 259 .  * measure -> bar
 260 .  * abbrev -> tremolo
 261 .  * abbreviation-beam -> (measured/unmeasured) tremolo
 262 .  * partial -> anacrouse
 263 . * robustify Beam (in case of no stems, 32nd notes)
 264 . * move paper vars into engraver properties
 265 . * check for groff / troff/ nroff et
 266 . * more intelligent file searching
 267 . * disable spaces in TeX stuff
 268 . * handle ^C for tmp/file creation.
 269 . * make LilyPond RPM fully relocatable
 270 . * dots & rest collisions.
 271 . * the warning about the negative slur/tie length appears twice
 272 which is irritating.
 273 . * better hshift (dots, distance, head dependent)
 274 . * clefs (AG): The "8" should appear closer to the actual clef,
 275 touching it.
 276 . * put errorlevel in Input class
 277 . * junk nesting slurs
 278 . * integrate midi-elts from mi2mu and lily?
 279 . * distinguish between unset and empty properties.
 280
 281 .* FONT
 282 . * the bracket is ugly (wings are too parabolic, should be more circular)
 283 . * versioning for Feta
 284 . * rewrite dynamic signs.  They're kind of spaghetti now.
 285 . * The `3' in the meter key is a one or two pixels too thin (at 600dpi)
 286         in the middle:
 287 . * design macro for penstroke with rounded endings
 288 . * timesig C: fat yet less curved.  Check out relations.
 289 . * design decent macro for bulbed endings
 290 . * printer dependencies.
 291 . * versioning
 292 . * lo-res fixes.
 293 . * work out sizes of character fonts.
 294 . * more symbols
 295 .  * piano pedals: Ped/*
 296 .  * maxima notehead
 297 .  * coda signs: Segno, O+
 298 .  * glissando, arpeggio
 299 .  * lengthened trill
 300 . * include important spacing dims in fetalog
 301 . * scalability: use blot_diameter everywhere, make font chubbier for
 302     small sizes.
 303
 304 .* 3RD PARTY BUGS
 305 . * GNU diff 2.7: diff -rN does not see a new directory with empty file
 306 . * check out GCC signatures?
 307 . * glibc 2.0:
 308           f = fopen ("/dev/null", "r")
 309           assert (feof (f))
 310
 311 . * tetex: mfplain.mem
 312 .* 3RD PARTY PROJECTS:
 313 . * make GCC warn about ctor that leaves member vars  uninitialised.
 314 . * GNU patch
 315 .  * 'double-fix' mode: ignore identical fix, rather than suggest
 316             to revert patch direction when (more or less? exactly) the same
 317             thing is fixed
 318 .* PROJECTS
 319 . * Scripts:
 320 .  * stack scripts in chords:
 321           % fingering:        footing:
 322             < a-4 c-2 g-1 >   < c-\ltoe e-\lheel >
 323 .  * script-spacing
 324 .  * slur parts as a script
 325 .  * stack parameterised scripts for fingering and footing:
 326
 327 . * convert-mudela:
 328 .  * automatically add  a \version if not present.
 329 .  * better parsing
 330 .  * make smarter
 331 .  * convert-mudela -e empty.ly
 332
 333 . * emacs mudela-mode
 334 .  *  should handle block comments too.
 335 .  *  handle lexer modes (\header, \melodic, \lyric) etc.
 336 .  *  indentation
 337 .  *  notenames?
 338 .  *  fontlock: \melodic \melodic
 339
 340 . * use properties for:
 341 .  * default tempo.
 342 .  * cadenza mode?
 343
 344 . * page handling:
 345 .  * PS output
 346 .  * optimal pagebreaking.
 347
 348 . * Unicode support? -> man 7 unicode
 349 .  * 16 bit Strings
 350 .  * -u switch
 351 .  * detect of 16/8 bit files
 352 .  * examples to go with it.
 353
 354 . * \header
 355 .  * output header info to MIDI too.
 356
 357 . * a musical dictionary. See Documentation/vocabulary-*, other
 358 languages:
 359 .  * explanations
 360 .  * italian
 361 .  * german
 362 .  * dutch
 363 .  * swedish
 364          .. ?
 365
 366 . * chords
 367 .  * guitar chords (fret diagrams)
 368 .  * other chord name styles (american(?) style)
 369 .  * basso continuo
 370 .  * MIDI output?
 371
 372 . * Debug logs:
 373 .  * derive lily_stream, Dstream, texstream from ostream?
 374 .  * indentable stream as baseclass for TeX stream, lily stream, Dstream.
 375 .  * use dstream feature in mi2mu
 376 .  * integrate IO checking into stream class
 377
 378 . * input converters
 379 .  * NIFF?
 380 .  * ABC?
 381 .  * SMDL?
 382
 383 . * add to MIDI output:
 384 .  * tempo change
 385 .  * ornaments (and trills?)
 386 .  * slurs
 387 .  * accents
 388 .  * dynamics
 389 > Would it be hard to add support for proper dynamics in MIDI output?  I
 390 > would really like to have this feature...
 391
 392 To answer this, I have to give a little background.  Please say so if
 393 I am being obtuse.
 394
 395 Both audio and notation elements are created decentrally, when
 396 LilyPond says "Interpreting music ... [8][16] etc."  After all
 397 elements are created, they are processed again to calculate all
 398 parameters.  After that is done, they are dumped onto the output (the
 399 MIDI stream or the TeX file).
 400
 401 The audio and notation elements are created by objects called
 402 performer and engraver respectively.  They work by taking a chunk of
 403 input (a so-called request), and using the request to create an audio
 404 or notation element.
 405
 406 After some processing, the engraver sends the created elements to
 407 its enclosing notation/performance context.
 408
 409 In the case of notation, engravers can also modify existing elements
 410 created by sibling engravers.  Eg. the beam-engraver will modify stems
 411 when it creates a beam over a couple of stems.  This is done in
 412 Engraver::do_acknowledge_element () and
 413 Engraver::do_process_acknowledged ().
 414
 415 In the case of audio, there are no mechanisms to modify existing audio
 416 elements. After the audio elements are created, they are sent directly
 417 to the enclosing context (an instance of Performer_group_performer),
 418 through the method Performer::play ()
 419
 420 Concretely spoken, for dynamics you have to write a performer
 421 (Dynamics_performer), that will take the input requests. If I
 422 understand correctly, every MIDI note played must have its dynamic
 423 strength set separately.  That means the the Dynamics_performer must
 424 set the strength of every Audio_note it finds.  This means that one
 425 has to modify existing Audio items.  The best way of doing this is
 426 with a broadcast/acknowledge process.
 427
 428 So the best way of handling this, is
 429
 430   1 supporting dynamic settings in Audio_note
 431
 432   2 mimicking the broadcast/acknowledge mechanism of the Engravers in
 433   the Performers
 434
 435   3 using that mechanism to write a Dynamics_performer that will modify
 436   any notes it finds to set appropriate strengths.
 437
 438 You could also kludge this by deriving from Performer_group_performer
 439 a performer that also sets dynamics within notes, but that is not the
 440 elegant way to do it.
 441
 442 I'd say that the work involved is not hard, but you have to be fluent
 443 with C++ and need some insight into the working of Notation Contexts
 444 and friends.  I guess I could do it in a day or so, but if you are not
 445 so fluent with the inner workings of LilyPond, it could take you some
 446 more time (A few more days?).
 447
 448 Please note, that I am *not* going to code this myself: my days are
 449 valuable, and I think I have more interesting things to do than fixing
 450 the MIDI output (I don't even have a soundcard).  But I *do* want to help
 451 you or other people with implementing this, so if you need help, don't
 452 hesitate to ask.
 453
 454 .  * account for rhythmic position in measure
 455 .  * etc.
 456
 457 . * grace notes
 458 .  * make separate class for Grace_*_engravers
 459         (which is at Voice_gravs level)
 460 .  * make encapsulated spacing problems.
 461
 462 . * accidentals per Voice_group
 463
 464 . * Output class, handles : (smallish)
 465 .  * help text /(c) notice?
 466 .  * version line
 467 .  * warning /errors/progress
 468 .  * abort on error/warning; exit status
 469 .  * quiet/ignore-version options
 470 .  * logfile output
 471
 472 . * PS
 473 .  * speed up PS code.
 474 .  * PS lines to .eps files
 475 .  * write custom prolog
 476
 477 . * SGML input
 478
 479 . * Documentation
 480 .  * remove links to non-free SW.
 481 .  * internal documentation
 482 .  * a general paper.
 483 .  * \properties
 484 .   * left/rightbeamcount
 485 .   * various other new properties.
 486 .  * introduction?
 487 .  * info?
 488 .  * LaTeX?
 489 .  * more manpages?
 490 .  * Doc (C) stuff of sheet music
 491 .  * a better format?  SGML?  TeX?  Info?
 492 .  * a better tutorial
 493
 494 . * more spanners (smallish)
 495 .  * Glissando
 496 .  * trill
 497
 498 . * Rewrite Stem, Beam and Rhythmic_grouping (hairy)
 499 .  * [c8. c32 c32]
 500 .  * doc on Rhythmic_grouping
 501 .  * general shaving on Beam and Stem
 502 .  * use plet grouping
 503 .  * separate visual from rhythmic info even more
 504 .  * beams over bars
 505
 506 . * lines:
 507 .  * Ledger lines, should be separate item: Ledger_lines
 508 .  * set different line sizes / thicknesses
 509 .  * beam stem showthrough, inter beam sizes (french vs german style)
 510
 511 . * Collisions
 512 .  * left/right note balls should be handled by Collision:
 513         < \multi 2; { \stem 1; <b c> } { <f as b> } >
 514
 515 . * Keys:
 516 .  * merge key{item} & localkey{item}?
 517 .  * spacing, national styles?
 518
 519 . * Support for TAB
 520 .  * redo Notehead to allow digits as heads
 521 .  * add a \tablature {} lexer mode for easy entering
 522
 523 . * should adjust stemlength for flag number.
 524
 525 . * breaking:
 526 .  * caching breakpoints
 527 .  * saving them
 528 .  * specify number of lines
 529
 530 .* INPUTLANGUAGE
 531 . * \rhythms 4 16 16 16 16; c c c c c -> c4 c16 etc.
 532 . * Language:
 533 .  * \translator -> ?
 534 .  * fix \partial
 535 .  * \bla {} vs \bla ;
 536 .  * mix engraver hacking with music ?
 537 .  * \once\property  KEY = VAL
 538 .  * \addtranslator, \removetranslator
 539 .  * junk ^ and _ for scripts
 540 .  * junk _ for lyrics.
 541 .  * abstract grammar.
 542 . * Figure out semicolons.
 543 . * c4 4 4 4 for c4 c4 c4 c4?
 544 . * <c f a>4 ?
 545 . * Viola mode?
 546
 547                 @c c g e g
 548         for
 549                 c g es g,
 550
 551                 @A c g e g
 552         for
 553                 cis gis e gis
 554 . * configure pitch_byte
 555 . * rest name configurable
 556
 557
 558 .* SMALLISH PROJECTS
 559
 560 . * Faulenzer sign (% repeat).  Perhaps also use \repeat syntax?
 561
 562 . * fix confusing naming in Engraver vs Engraver_group_engraver (context)
 563
 564 . * progress when creating MIDI elts.
 565
 566 . * A range for context errors (eg. mark both { and }. )
 567
 568 . * lyric in staff  (sharpsharp in staff, text below)
 569
 570 . * half sharps/flats
 571
 572 . * write Dynamic_line (to group dynamics horizontally)
 573
 574 . * use Real for all y positions.
 575
 576 . * half-sharps, half-flats
 577
 578 . * adaptive accidental spacing.
 579
 580 . * handle EOF graciously in error messages.
 581
 582 . * midi esp.: use I32 iso int where 32 bits are needed (or assumed...)
 583
 584 . * stafftypes: voice names/ instrument names.
 585
 586 . * lily \tempo
 587
 588 . *   % toe to bheel   four to five
 589             %   ^_u            4_5
 590             %     -
 591             %  --|x--         --|x--
 592             %  --|---         --|---
 593             %  --|---         --|---
 594           (where "to" is a tiny bow)
 595
 596 . * auxilliary file for caching info.
 597
 598 . * Text_crescendo
 599
 600 . * revise calcideal
 601
 602 .* IDEAS
 603 . * Output data structures of Mudela in XML/SGML.
 604 . * create libmudela, or liblily_frontend
 605 . * move MIDI stuff (including Quantization) to a ANSI C libmidi library.
 606 . * Spacing_request for manually adjusting spacing
 607 . * caching breakpoints
 608 . * used fixedpoint arithmetic for min. energy.
 609 . * move towards incremental algorithms.
 610 . * versioning stuff (cvt mudela, mudela, etc.)
 611 . * dynamic loading of engravers?
 612 .* SMOBS
 613 Han-Wen Nienhuys <hanwen@cs.uu.nl> writes:
 614
 615 >       class Foo_class {
 616 >               Foo_smob *smob_ptr_;
 617 >       }
 618 >
 619 >       struct Foo_smob {
 620 >               Foo_class *class_ptr_
 621 >       }
 622
 623 Usually you can get away without having this interlinked structure.
 624 One piece of information you need when exporting objects to scheme is
 625 the smob tag for your class.  You might store this value (a long) into
 626 a class static variable, or a file static variable.  I'll use a class
 627 static variable in this example.
 628
 629 I typically use code that works like this (untested code ahead):
 630
 631 class Foo_class {
 632     static long *Foo_smob_tag;
 633     SCM obj; // representation as a scheme object, description comes later
 634 }
 635
 636 // call this once on startup
 637 void init_Foo_class {
 638     static scm_smobfuns type_rec;
 639
 640     type_rec.mark = foo_mark;
 641     type_rec.free = foo_free;
 642     type_rec.print = foo_display;
 643     type_rec.equalp = 0;
 644     Foo_class::Foo_smob_tag = new int(scm_new_smob(type_rec));
 645 }
 646
 647 When you want to export an object to scheme, you put a pointer to the
 648 object itself in the cdr of the cell, and the tag in the car of the
 649 cell.  The code looks like this:
 650
 651 // Is this a Foo?
 652 static int
 653 foo_p(SCM obj)
 654 {
 655     return(SCM_NIMP(obj) && SCM_CAR(obj) == Foo_class::Foo_smob_tag);
 656 }
 657
 658 // given a Scheme representation, return, a C++ representation
 659 static Foo_class *
 660 foo_unbox(SCM obj)
 661 {
 662     return((Foo_class*)SCM_CDR(obj));
 663 }
 664
 665 // the SCM representation of the object is stored inside itself
 666 // this will become useful when destructor gets called
 667 static SCM
 668 foo_box(Foo_class *foo)
 669 {
 670     SCM_DEFER_INTS;
 671     SCM_NEWCELL(foo->obj);
 672     SCM_SETCAR(foo->obj, Foo_class::Foo_smob_tag);
 673     SCM_SETCDR(foo->obj, (SCM)foo);
 674     SCM_ALLOW_INTS;
 675     return foo->obj;
 676 }
 677
 678 > C++ determines life time, so what is the strategy?
 679
 680 What happens now when the destructor gets called?  Lets set the cdr to
 681 NULL, and then check for that in all of the primitive functions that
 682 use your smob.  We'll call this notion 'live'; a scheme object is
 683 'live' if the C++ representation still exists, it's dead if the C++
 684 object is gone.  You can still have references to dead objects in
 685 scheme code; it's just an error to use them.  This idea is stolen from
 686 Emacs's handling of buffers ('buffer-live-p' and friends).
 687
 688 Add another function, foo_live_p:
 689
 690 static int
 691 foo_live_p(SCM obj)
 692 {
 693     return(foo_p(obj) && SCM_CDR(obj) != NULL);
 694 }
 695
 696 In you destructor, you need to do:
 697
 698 ~Foo_class()
 699 {
 700     SCM_CDR(this->obj, NULL);
 701 }
 702
 703 When writing new primitives, now just check foo_live_p().
 704
 705 I hope the above helps,
 706
 707
 708 * OUTLINE SETUP
 709 .* .EMACS
 710 ;;; from outline.el
 711 (defvar outline-font-lock-keywords
 712   '(;; Highlight headings according to the level.
 713     ;; must change this to allout node layout
 714     ;;("^\\(\\*+\\)[ \t]*\\(.+\\)?[ \t]*$"
 715     ("^\\([.]*[ ]*[*]\\)[ \t]*\\(.*\\)$"
 716      (1 font-lock-string-face)
 717      (2 (let ((len (- (match-end 1) (match-beginning 1))))
 718           (or (cdr (assq len '((1 . font-lock-function-name-face)
 719                                (2 . font-lock-keyword-face)
 720                                (3 . font-lock-comment-face))))
 721               font-lock-variable-name-face))
 722         nil t))
 723     ;; Highlight citations of the form [1] and [Mar94].
 724     ("\\[\\([A-Z][A-Za-z]+\\)*[0-9]+\\]" . font-lock-type-face))
 725   "Additional expressions to highlight in Outline mode.")
 726
 727 (add-hook 'outline-mode-hook
 728           '(lambda ()
 729             (setq font-lock-maximum-decoration t)
 730             (setq font-lock-maximum-decoration t)
 731             (make-local-variable 'font-lock-defaults)
 732             (setq font-lock-defaults '(outline-font-lock-keywords t))
 733             (font-lock-mode global-font-lock-mode)
 734         ))
 735
 736 (require 'allout)
 737 (outline-init 't)