Re: Suggestion for documentation: Easy path to datatype reference

[Jonathan Wilkes]

> Message: 1

> Date: Thu, 12 Apr 2012 21:32:28 +0800
> From: James Harkins <address@hidden>
> To: lily-users <address@hidden>
> Subject: Suggestion for documentation: Easy path to datatype reference
> Message-ID: <address@hidden>
> Content-Type: text/plain; charset=UTF-8
> 
> Along with the existing documentation about overrides and tweaks, it would be 
> helpful to have a page -- which is easy to find -- listing all the data types 
> and the syntax to write them.
> 
> Example: Today, I was trying to write my own \override for the first time. 
> To make matters more challenging, I was in a caf? and their WiFi connection 
> was 
> not working. So, the only documentation I had available to me was the *info* 
> docs in Emacs. Eventually I found my way to grob-interface and extra-offset: 
> "It takes a pair of numbers"... /pair/ of numbers? No obvious entries 
> in the index, or looking through the table of contents of the learning 
> manual, 
> notation reference for internals reference.
> 
> I only needed to move something down, so I gave up and used Y-offset.
> 
> I got home, and an Internet search turned up the Scheme tutorial, which does 
> explain cons cells, so I finally found the syntax is (a . b). I didn't see 
> it in the table of contents because it goes down to second-level sections 
> (1.1, 
> 1.2 etc.) and the headings about datatypes are 1.1.3 and 1.1.4.
> 
> Small issue, I guess -- it's possible to find the information with the help 
> of tools outside the documentation, but it is a bit of a usability issue: the 
> learning manual discusses tweaks, but appears not to be specific about the 
> syntax you will need to specify certain datatypes -- requiring external tools 
> and an internet connection to make the documentation useful.
> 
> Or maybe it just irritated me and I want to complain :)

Well it's definitely a pain.  My favorites are booleans, which require one hash 
to 
denote scheme code, and one hash for the boolean.  (Why not one more hash, 
for good measure?)

Do you know about the internals reference?  Here's the entry for "textscript", 
for example:
http://lilypond.org/doc/v2.14/Documentation/internals/textscript

It shows you the defaults for each setting which show you the syntax to be 
usedin an 
override.

-Jonathan


> 
> FWIW, I'm throwing some quite complex multi-voice notation at Lilypond and 
> most of it is coming out beautifully, without manual intervention. So let me 
> balance the complaint with kudos for the excellent work of the developer team!
> 
> James
> 
> 
> --
> James Harkins /// dewdrop world
> address@hidden
> http://www.dewdrop-world.net
> 
> "Come said the Muse,
> Sing me a song no poet has yet chanted,
> Sing me the universal."  -- Whitman
> 
> blog: http://www.dewdrop-world.net/words
> audio clips: http://www.dewdrop-world.net/audio
> more audio: http://soundcloud.com/dewdrop_world/tracks