Re: Doc, EG: LilyPond's getting too smart for the "Inline Scheme code" section (issue 13661045)

[dak]

Reviewers: Trevor Daniels,

Message:
On 2013/09/19 16:23:54, Trevor Daniels wrote:
> Hhm.  I think I'd prefer this whole section to
> be commented out (with an explanation) until
> someone can think of a convincing example.
> Why continue to explain to users how to do
> something they will now quite likely never need
> to do?

> Trevor

Because this section is an introduction for the cases where one _does_
need Scheme?  Those cases will always be around, and just because
LilyPond now is easier to use, we are not doing people favors by
removing working documentation.

It's not that the stuff in this section does not work.  It's just that
this particular case _can_ be done without Scheme.  And it's better to
explain this with a simple example that does not actually require using
Scheme than not explaining it at all.

The EG is covering too little ground already.

Description:
Doc, EG: LilyPond's getting too smart for the "Inline Scheme code"
section

The "Inline Scheme code" section already was embarrassing enough
during its last revision, when a trivial syntactic change was all that
was required in order to have the stated problem go away without
requiring to revert to Scheme.

Since then, the situation has further deteriorated: the originally
"what we would like to do but it fails" example works entirely
unchanged without a hitch.

Please review this at https://codereview.appspot.com/13661045/

Affected files (+7, -8 lines):
  M Documentation/extending/programming-interface.itely


Index: Documentation/extending/programming-interface.itely
diff --git a/Documentation/extending/programming-interface.itely  
b/Documentation/extending/programming-interface.itely
index  
aafb4fc5d31759989784dc26733b4d29042803ec..162d3fdcb8328fc573fb40b29b6cf2a13fc1e137  
100644
--- a/Documentation/extending/programming-interface.itely
+++ b/Documentation/extending/programming-interface.itely
@@ -1277,16 +1277,15 @@ my-callback = #(lambda (grob)
 @node Inline Scheme code
 @section Inline Scheme code

-TODO: the example for this section is ill-chosen since
address@hidden
-F = -\tweak font-size #-3 -\flageolet
address@hidden example
-(note the @samp{-} marking it as a post event) will actually work fine
-for the stated purpose.  Until this section gets a rewrite, let's
-pretend we don't know.
+TODO: after this section had been written, LilyPond has improved
+to the point that finding a @emph{simple} example where one would
address@hidden to revert to Scheme has become rather hard.
+
+Until this section gets a rewrite, let's pretend we don't know.

 The main disadvantage of @code{\tweak} is its syntactical
-inflexibility.  For example, the following produces a syntax error.
+inflexibility.  For example, the following produces a syntax error
+(or rather, it did so at some point in the past).

 @example
 F = \tweak font-size #-3 -\flageolet