Provide define-session and define-session-public commands

Provide define-session and define-session-public commands

Also moves the session logic into lily.scm instead of init.ly

[Ian Hulin (gmail), 2012-10-01 18:02:16]

Just a question about the doc-string.

http://codereview.appspot.com/6588056/diff/1/scm/lily.scm
File scm/lily.scm (right):

http://codereview.appspot.com/6588056/diff/1/scm/lily.scm#newcode51
scm/lily.scm:51: A@tie{}session basically corresponds to one LilyPond file on
the
Is a space needed somewhere in "A@tie{}session"? I.e. will it look the way you
intended when the docs are compiled?

[dak, 2012-10-01 18:24:20]

On 2012/10/01 18:02:16, Ian Hulin (gmail) wrote:
> Just a question about the doc-string.
> 
> http://codereview.appspot.com/6588056/diff/1/scm/lily.scm
> File scm/lily.scm (right):
> 
> http://codereview.appspot.com/6588056/diff/1/scm/lily.scm#newcode51
> scm/lily.scm:51: A@tie{}session basically corresponds to one LilyPond file on
> the
> Is a space needed somewhere in "A@tie{}session"? I.e. will it look the way you
> intended when the docs are compiled?

15.6 `@tie{}': Inserting an Unbreakable Space
=============================================

The `@tie{}' command produces a normal interword space at which a line
break may not occur.  Always write it with following (empty) braces, as
usual for commands used within a paragraph.  Here's an example:

     @TeX{} was written by Donald E.@tie{}Knuth.

produces:

     TeX was written by Donald E. Knuth.

So in a nutshell: if this runs through Texinfo, we will get a non-breakable
space in there.  At the current point of time, only the doc strings of music
functions and of functions written in C++ are listed in the NR and Extending
manual, respectively.  Does this mean that we should not use Texinfo markup in
*.scm files?  No idea.

[Ian Hulin (gmail), 2012-10-01 22:54:07]

On 2012/10/01 18:24:20, dak wrote:
><snip>
> 
> 15.6 `@tie{}': Inserting an Unbreakable Space
> =============================================
> 
> The `@tie{}' command produces a normal interword space at which a line
> break may not occur.  Always write it with following (empty) braces, as
> usual for commands used within a paragraph.  Here's an example:
> 
>      @TeX{} was written by Donald E.@tie{}Knuth.
> 
> produces:
> 
>      TeX was written by Donald E. Knuth.
> 
Thanks for the clarification.

[janek, 2012-10-03 05:10:27]

Could you modify the commit message so that it says why we need this change? 
After reading the comments in your code i don't understant what's its purpose.

[dak, 2012-10-03 06:01:27]

On 2012/10/03 05:10:27, janek wrote:
> Could you modify the commit message so that it says why we need this change?

It's not really a change but an API to something you had to do by hand
previously if you were working on .scm files providing user customization in
some manner (and there are a number of cases in LilyPond where programmers
failed to do so, leading to settings bleeding over into the next session/file).

> After reading the comments in your code i don't understant what's its purpose.

Sounds like I should rather delete the comments...  I thought that the
documentation of define-session was rather clear: can you point out where it
falls down?

[janek, 2012-10-03 06:20:10]

On Wed, Oct 3, 2012 at 8:01 AM,  <dak@gnu.org> wrote:
> On 2012/10/03 05:10:27, janek wrote:
>> After reading the comments in your code i don't understant what's its
>> purpose.
>
> Sounds like I should rather delete the comments...

oh, no!  They are well-written and provide insight into your code.
It's just that i didn't know what we might need sessions for.

> I thought that the
> documentation of define-session was rather clear: can you point out
> where it falls down?

i think all i need is a short example, like "with sessions, you can do
X and you won't get side-effects of Y kind".

cheers,
Janek

[dak, 2012-10-03 08:04:28]

On 2012/10/03 06:20:10, janek wrote:
> On Wed, Oct 3, 2012 at 8:01 AM,  <mailto:dak@gnu.org> wrote:
> > On 2012/10/03 05:10:27, janek wrote:
> >> After reading the comments in your code i don't understant what's its
> >> purpose.
> >
> > Sounds like I should rather delete the comments...
> 
> oh, no!  They are well-written and provide insight into your code.
> It's just that i didn't know what we might need sessions for.
> 
> > I thought that the
> > documentation of define-session was rather clear: can you point out
> > where it falls down?
> 
> i think all i need is a short example, like "with sessions, you can do
> X and you won't get side-effects of Y kind".

Uh, I guess we have a fundamental misunderstanding here.  We already _have_
sessions (you can call lilypond on several different .ly input files and have
them processed tentatively independently).  We just don't have any help for the
programmer who tries dealing with them.  What currently exists is that each
session gets its fresh parser copy, and the parser variables are initialized
from the state right before the first session started.  For everything else, you
are out on your own and responsible that all the variables in .scm files start
with the same values each session, if necessary by reinitializing them in
ly/init.ly.

Except that nobody does.

scm/midi.scm starts with
;;;;;;;;;;;;;;;;;;
;;; TODO:

;; this is broken: we should not ever export variables from Scheme.

and indeed, it is broken.  If you write to any of those variables, the changes
persists across all sessions of a LilyPond run.

define-session will declare a variable that has its value recorded at the start
of the first session and reinstated at the start of each following session.

It is supposed to provide a simple API for something that is so hard to do right
that we have quite a bit of code in LilyPond that gets it wrong.

It is not really providing anything new, just gives a face to something that
programmers were expected to do right on their own, but which is really too hard
to understand or explain.

[thomasmorley65, 2012-10-03 15:49:04]

After testing the patch's functionality, only:
LGTM

[janek, 2012-10-03 16:29:38]

On Wed, Oct 3, 2012 at 10:04 AM,  <dak@gnu.org> wrote:
> Uh, I guess we have a fundamental misunderstanding here.  We already
> _have_ sessions (you can call lilypond on several different .ly input
> files and have them processed tentatively independently).  We just don't
> have any help for the programmer who tries dealing with them.  What
> currently exists is that each session gets its fresh parser copy, and
> the parser variables are initialized from the state right before the
> first session started.  For everything else, you are out on your own and
> responsible that all the variables in .scm files start with the same
> values each session, if necessary by reinitializing them in ly/init.ly.

Yeah, i read the barline thread when i was offline and i understand now.

> define-session will declare a variable that has its value recorded at
> the start of the first session and reinstated at the start of each
> following session.

I think this paragraph could be included in commit message.

> It is not really providing anything new, just gives a face to something
> that programmers were expected to do right on their own, but which is
> really too hard to understand or explain.

Indeed ;)
Thanks for explanations!
Janek

[janek, 2012-10-03 16:29:54]

PS: LGTM :)