2002-08-08 Rune Zedeler <rune@zedeler.dk>

[lilypond.git] / lily / molecule.cc

diff --git a/lily/molecule.cc b/lily/molecule.cc
index 6a9af3d3550189703d1d9a20d3622042c2eba780..1a5efa8c76abbf0347f7c794051e376a484d88c3 100644 (file)
--- a/lily/molecule.cc
+++ b/lily/molecule.cc
@@ -14,7 +14,7 @@
 #include "interval.hh"
 #include "string.hh"
 #include "molecule.hh"
-#include "debug.hh"
+#include "warn.hh"
 
 
 #include "ly-smobs.icc"
@@ -146,7 +146,7 @@ smaller than @code{B}, and is often negative.
 {
   Molecule* m = unsmob_molecule (mol);
   SCM_ASSERT_TYPE (m, mol, SCM_ARG1, __FUNCTION__, "molecule");
-  SCM_ASSERT_TYPE (ly_axis_p(axis), axis, SCM_ARG2, __FUNCTION__, "axis");
+  SCM_ASSERT_TYPE (ly_axis_p (axis), axis, SCM_ARG2, __FUNCTION__, "axis");
   SCM_ASSERT_TYPE (ly_number_pair_p (np), np, SCM_ARG3, __FUNCTION__, "number pair");
 
   Interval iv = ly_scm2interval (np);
@@ -163,7 +163,7 @@ LY_DEFINE(ly_get_molecule_extent,
 {
   Molecule *m = unsmob_molecule (mol);
   SCM_ASSERT_TYPE (m, mol, SCM_ARG1, __FUNCTION__, "molecule");
-  SCM_ASSERT_TYPE (ly_axis_p(axis), axis, SCM_ARG2, __FUNCTION__, "axis");
+  SCM_ASSERT_TYPE (ly_axis_p (axis), axis, SCM_ARG2, __FUNCTION__, "axis");
  
   return ly_interval2scm (m->extent (Axis (gh_scm2int (axis))));
 }
@@ -184,9 +184,9 @@ space to add in between measured in global staff space.")
   Molecule result;
 
 
-  SCM_ASSERT_TYPE(ly_axis_p(axis), axis, SCM_ARG2, __FUNCTION__, "axis");
+  SCM_ASSERT_TYPE(ly_axis_p (axis), axis, SCM_ARG2, __FUNCTION__, "axis");
   SCM_ASSERT_TYPE(ly_dir_p (direction), direction, SCM_ARG3, __FUNCTION__, "dir");
-  SCM_ASSERT_TYPE(gh_number_p(padding), padding, SCM_ARG4, __FUNCTION__, "number");
+  SCM_ASSERT_TYPE(gh_number_p (padding), padding, SCM_ARG4, __FUNCTION__, "number");
 
   if (m1)
     result = *m1;
@@ -220,7 +220,38 @@ LY_DEFINE(ly_add_molecule ,
 
 LY_DEFINE(ly_make_molecule,
          "ly-make-molecule", 3, 0, 0,  (SCM expr, SCM xext, SCM yext),
-         "")
+         "
+The objective of any typesetting system is to put ink on paper in the
+right places. For LilyPond, this final stage is left to the @TeX{} and
+the printer subsystem. For lily, the last stage in processing a score is
+outputting a description of what to put where.  This description roughly
+looks like
+@example
+        PUT glyph AT (x,y)
+        PUT glyph AT (x,y)
+        PUT glyph AT (x,y) 
+@end example
+you merely have to look at the tex output of lily to see this.
+Internally these instructions are encoded in Molecules.@footnote{At some
+point LilyPond also contained Atom-objects, but they have been replaced
+by Scheme expressions, making the name outdated.}  A molecule is
+what-to-print-where information that also contains dimension information
+(how large is this glyph?).
+
+Conceptually, Molecules can be constructed from Scheme code, by
+translating a Molecule and by combining two molecules. In BNF
+notation:
+
+@example
+Molecule  :: COMBINE Molecule Molecule
+           | TRANSLATE Offset Molecule
+           | GLYPH-DESCRIPTION
+           ;
+@end example
+
+If you are interested in seeing how this information is stored, you
+can run with the @code{-f scm} option. The scheme expressions are then
+dumped in the output file.")
 {
   SCM_ASSERT_TYPE (ly_number_pair_p (xext), xext, SCM_ARG2, __FUNCTION__, "number pair");
   SCM_ASSERT_TYPE (ly_number_pair_p (yext), yext, SCM_ARG3, __FUNCTION__, "number pair");  
@@ -252,7 +283,7 @@ LY_DEFINE(ly_align_to_x,"ly-align-to!", 3, 0, 0,  (SCM mol, SCM axis, SCM dir),
          "Align @var{mol} using its own extents.")
 {
   SCM_ASSERT_TYPE(unsmob_molecule (mol), mol, SCM_ARG1, __FUNCTION__, "molecule");
-  SCM_ASSERT_TYPE(ly_axis_p(axis), axis, SCM_ARG2, __FUNCTION__, "axis");
+  SCM_ASSERT_TYPE(ly_axis_p (axis), axis, SCM_ARG2, __FUNCTION__, "axis");
   SCM_ASSERT_TYPE(ly_dir_p (dir), dir, SCM_ARG3, __FUNCTION__, "dir");
 
   unsmob_molecule (mol)->align_to ((Axis)gh_scm2int (axis), Direction (gh_scm2int (dir)));
@@ -294,8 +325,8 @@ Molecule::print_smob (SCM , SCM port, scm_print_state *)
   scm_puts ("#<Molecule ", port);
 #if 0
   Molecule  *r = (Molecule *) ly_cdr (s);
-  String str (r->str ());
-  scm_puts ((char *)str.ch_C (), port);
+  String string (r->string ());
+  scm_puts ((char *)str.to_str0 (), port);
 #endif
   scm_puts (" >", port);