Add an explanatory comment regarding session-handling to scm/lily.scm

diff --git a/scm/lily.scm b/scm/lily.scm
index 3d179dd2cb2e6d6e66a3840706582586f463cda4..496598bbbcab42af60f8b98621a28de7686a683d 100644 (file)
--- a/scm/lily.scm
+++ b/scm/lily.scm
@@ -43,6 +43,30 @@
    (string-downcase
     (car (string-tokenize (utsname:sysname (uname)))))))
 
+;;
+;; Session-handling variables and procedures.
+;;
+;;  A "session" corresponds to one .ly file processed on a LilyPond
+;;  command line.  Every session gets to see a reasonably fresh state
+;;  of LilyPond and should work independently from previous files.
+;;
+;;  Session management relies on cooperation, namely the user not
+;;  trying to change variables and data structures internal to
+;;  LilyPond.  It is not proof against in-place modification of data
+;;  structures (as they are just reinitialized with the original
+;;  identities), and it is not proof against tampering with internals.
+;;
+;;  As a consequence, session management is not sufficient for
+;;  separating multiple independent .ly files in "-dsafe" mode: you
+;;  should give each its own LilyPond process when reliable separation
+;;  is mandatory.
+;;
+;;  For standard tasks and programming practices, multiple sessions in
+;;  the same LilyPond job should work reasonably independently and
+;;  without "bleed-over" while still loading and compiling the
+;;  relevant .scm and .ly files only once.
+;;
+
 (define lilypond-declarations '())
 (define after-session-hook (make-hook))