confusion: clef middle-pitch
[middle=<pitch>] - is an alternate way to define the line number of the clef. The pitch indicates what note is displayed on the 3rd line of the staff. Defaults are: treble: B; alto: C; tenor: A,; bass: D,; none: B.
My interpretation of this is that the effect of clef=treble middle=G would be the same as clef=treble line=3: to raise the treble clef up one line in the printed staff. It would still circle the note G but G would now live on the 3rd staffline instead of the 2nd. (Is this the right way to understand clef=treble line=3?)
But just a few lines later we have this statement:
The middle specifier can be handy when working in the bass clef. Setting K:bass middle=d will save you from adding comma specifiers to the notes.
This seems to imply that clef=bass middle=d is the same as clef=bass octave=-2, in other words middle= doesn't change what line the clef gets printed on, it changes the name of the note on the middle staff line! By this logic we should expect clef=treble middle=G to move G to the middle line of the staff, but the clef would stay on the 2nd line (E!). But that doesn't make any sense.
Is the second statement just wrong, or does the middle specifier change its behaviour when the note is an octave or more away?