[I am taking the discussion to gnu-music-discuss--hope you don't mind]
[EMAIL PROTECTED] writes:
> I have made further modifications to refman.yo. They are extensive
Wow! I am impressed! This is Cool!
> enough that I am simply sending the entire text of refman.yo below.
> (The unified diffs are larger.)
I'd rather have patches anyway: I won't overwrite any changes that I
made, and it's easier for me to see what has changed.
> It claims in the tutorial that d''4. is really shorthand for:
> \musicalpitch { 1 2 0 } \duration { 2 1 }
> If this is true, then why do I get an error message when I substitute
> the above for d''4? Obviously something more is going on.
Yes. I have to twiddle some more to get that working.
> Here are my thoughts about a tutorial and reference manual. The
> purpose of the tutorial should be to get people using the program as
> fast as possible. I think that explaining details of the internals
> (such as \musicalpitch and \duration) should not be done at all in the
> tutorial.
I put it in to demonstrate what you people are really working with.
But maybe it ought to be in the reference manual.
> That just isn't something people need to know to produce
> the music. The \relative command should be introduced earlier and
> used more because that is something people are really going to want to
> use.
Do you think so? Jan and I had some discussion over this (it used to
be after the pitch & duration section) ... I was reluctant to use
\relative, because it adds another level of complexity to the examples.
That's why I moved it to the end.
>The reference manual, on the other hand, should completely,
> precisely, and concisely explain what everything does.
of course. Don't let the present state of the reference manual fool
you: it has little to do with how we feel that a manual should look like.
> I tried to add a list of all commands to the reference manual. I
> don't know if I found them all, though. I wrote explanations of what
> the commands do if I know. The ones I don't understand, I left blank.
> There's still definitely some basic organization that needs to be
> done, but I've spent too much time on this already for this week. My
> ability to decipher flex and bison code is limited, so I may note be
> the best person to try to write a section describing the syntax. I'm
> fuzzy on just what {} mean. I'm fuzzy on when a ; is needed.
> Sometimes a ; causes an error message. I think I observed this after
> \melodic{} and after note name definitions. It might be desireable to
> permit extra ; characters so people don't have to be so careful. The
> \input command doesn't require a ; but doesn't seem to care if one is
> present, which seems odd. But then this command doesn't seem to be in
> the parser, so maybe I shouldn't be surprised.
There is one distinction that I like to make, and which might make the
difference in \blah {} vs \blah; more clear. To me a mudela input
file is a *declaration* of the music/typesetting task at hand.
OTOH, the word `command' implies an ordering, and changing *state*:
commands are something from an imperative language.
To make things more confusing, the \commands from mudela are commands,
but they operate on a *notation context* (for example the \meter
command changes the state of the timing information during the
typesetting).
The \blah { } commmands (as you would call them), or constructs are
different. To me the \blah is like a function, and what's in braces
is like an argument.
\type { c4 }
\type c4
\type < c4 >
are all valid.
What is behind \blah in \blah{} typically is also examined by the
parser, and what is in \blah ... ; is usually just put dumped into
some strings, and examined during the interpretation phase.
And then there are keywords, which are connected because every
\commmand and every \prefix{} construction uses a \keyword
I do not like the syntax with `;', but we used to have a
\meter {2/4}
syntax, which also had problems (you get a lot of braces, and if you
forget one, hell still breaks loose). Ideally, I would want to have a
\property Staff.meter = "2/4"
probably, but I fear that this is too much work right now. (Plus Mats
would get all angry, because that would move much musicality out of
the language ;-)
Basically -- everywhere where you see a ; in the syntax, that's just
me being too lazy: if you can find a cleaner way to notate things: go
ahead. If you can find a ad-interim fix for the confusing ;'s, go
ahead (but I don't feel like inventing one; the ; is broken anyway)
> Why is the command for entering a new context called "\type" instead
> of being called "\context"?
Left overs from an era when there was no documentation and
consequently: no term `context'. I had to invent the word context to
explain what was happening. I am still not 100% satisfied with it,
but I can't make up a better word.
> After doing 'make dvi' and getting part way through refman.yo before a
> fatal error, I did make dvi again. The result is and endless loop of
> error messages, which is surely not the right behavior:
This is a problem with YODL. What version of YODL do you use ?
Platform? Does installing GNU diff utils help? I know that YODL
doesn't really work well on my IRIX box.
> When I write
>
> lyric=\melodic{ blah blah blah}
>
> I don't get an error until typing \lyric later, and the error message
fixed.
> Why can't the grouping command accept: \grouping 4 8*3; ?
fixed
> It's a little disconcerting to do \type Lyrics \lyric. Why is one
> plural and the other one singular? Also I generally think of "lyric"
> as a noun (with adjective form lyrical), so there is a contrast
> between "\melodic" and "\lyric". So, for example, it might be better
> to have named them \melody and \lyrics. (But I imagine it's too late
> to change a basic name like this.)
That's no problem, we do it all the time. The \version command really
is useful :).
The problem is that not only should the input look cute, it should
also reflect what is happening
\lyric, \melodic: change the mode of the lexer
Lyrics, Staff, StaffGroup: names of contexts.
Perhaps \melody and \lyrics is better than what we have, but I would
like to have some more comments. (And I would like to hear Jan's
comments; he'll be back in a week or so.)
> Here are two minor doc patches:
installed.
> COMMENT(As far as I can tell, the last bit is simply a repetition of
> the information on how to use an identifier, so it should be deleted.
>
> But I'm uncertain about the meaning of \TYPE in the above section.
> Different from \type? Does it refer to \melodic, \lyric? In general,
> the use of the word "type" seems to be a source of confusion.
> )
no, sorry \TYPE is like \blah
> verb(a&@&@&TSI|{[ % a word
> 1THtrhortho % not a "word"
> Leise DOEXPAND(Fl\)DOEXPAND("u\)ss{}teren meine Sapfe % 4 words
> _ _ _ _ % 4 words: 4 spaces
> ))
>
> COMMENT(Well, " seems to present some problems. Also `` seems to be
> problematic. So the above statement isn't quite right. Unless these
> characters are considered to be "white")
I think the statements are correct, only YODL needs some fooling
(DOEXPAND) to get the ouptut right.
> What's this about reals? When can you enter them or not enter them?)
>
the reals are in the \paper section; they modify parameters, eg
linewidth = 4.0\cm;
in note mode, the dot and the 4 in 4.0 get interpreted sepately (to
allow you to write
c4.
> understand what's going on at all here. The meaning of the lone ] is
> unclear. And the : syntax is also unclear. --Adrian)
Not olny has the section to be rewritten, the code has to be too.
> COMMENT(The above is wrong. Many commands have the form
> \keyword { text }
> with no semicolon, at least much of the time, and some commands
> have obligatory braces as far as I can tell, which don't contain music.)
>
See my explanation above.
> dit(code(\grouping) var(durationlist)) Sets the metric structure of
> the measure.
> COMMENT(elaboration is needed here.)
again, the corresponding implementation needs rewriting, not the
manual.
For the rest, your changes look like an improvement to me. But are
some subtle errors on the precise meaning of commands/syntax in some
places. Do you want to know them know (or can I put your patch in
?). You can also send in a patch to Documentation/topdocs/AUTHORS.yo
if you wish.
Again, thanks for your contributions.
--
Han-Wen Nienhuys, [EMAIL PROTECTED] ** GNU LilyPond - The Music Typesetter
http://www.cs.uu.nl/people/hanwen/lilypond/index.html
