Re: Notation Reference 1.8 "Text" : ready for review

[Graham Percival]

On Sun, 5 Oct 2008 17:46:45 +0200
"Valentin Villenave" <address@hidden> wrote:

> 2008/10/5 Graham Percival <address@hidden>:
> > Do you honestly consider LaTeX to be a "word processor"?
> 
> Well, at least my personal source of knowledge and wisdom says so:
> http://en.wikipedia.org/wiki/LaTeX

Well, your personal source of knowledge and wisdom sucks.

> > (ok, now I actually want to write a piece like that.  This is the
> > first time I've ever been tempted to write a Cage-like piece.  :)
> 
> Really? I thought you had already been working on Strasheela :-)

I use Strasheela to create Churney (sp) or Sevcek-style technical
exercises for violinists.

> > That said, I don't think you need a multi-page example here.  Just
> > dump the example currently in "Multi-page markup" in here.
> 
> 1- ... As a duplicate of the existing example?

I admit that's not perfect.

> 2- ... While people can access the already existing example and the
> already existing explanations though the already existing obvious
> link?

The docs aren't only in HTML format, you know.  Give the pdf
readers a clue of what happens on page 184.

Basically, it comes down to this:
1. every non-obvious @predef needs an example in the main text.
2. there is no \markuplines example in the main text.

Either remove the \markuplines from the @predef, or add an
example.

I recommend removing \markuplines from the @predef, and change the
final paragraph to this:
Separate text blocks can be spread over multiple pages, making it
possible to print text documents or books entirely within
LilyPond.  For more information, see @ref{Multi-page markup}.

Really, this "the specific syntax it requires" is an abomination
and disgrace to Mao.  Every bloody specific documentation page
specifically discusses the specific syntax used to specifically
create specific notation.


Remember: Il semble que la perfection soit atteinte non quand il
n'y a plus rien _ ajouter, mais quand il n'y a plus rien _
retrancher.
If you can remove a word (or words) without changing the meaning
of a sentence, kill it with glee.


> > characters, as mentioned in @ref{New dynamic marks} and
> > @ref{Manual repeat marks}.
> >
> > Where's this magical comma after the first @ref{} ?!
> 
> I thought you meant the @seealso list. AFAIC(H)R, the "commas after
> each @ref{}" discussion was always about @seealso lists, not plain
> sentences.

Texinfo insists on having punctuation after each @ref{}.

> > - markup as variables: why the complicated example?  And why the
> >  lack of [relative]?
> 
> Ever tried to define a variable inside a \relative block?

Ok, good point.

> > * Selecting font and font size
> > - second example: why the first note so much higher than the rest?
> 
> Because someone (can't remember who) told us to use relative=2 :-)
> I've removed it now.

Umm, I was hinting that you should change the first f to b or c or
d.  Not that you should use [relative=1].

> >  It look a bit weird, as does the a,^\markup.  Also, what do
> >  the final two bars add to the example?
> 
> They make the line long enough to make sure the markup won't go
> outside.

Ok.  (unlike me, you *do* need the ego boost :)


> OK, let me see. Oh, indeed, I must like this word: I used it about 20
> times in text.itely alone. I find it reassuring for the user; it means
> "we know this syntax seems exotic to you, we know you won't understand
> nor remember it at first, but it's normal: it's *specific*".

That's the silliest thing I've read in the past few months.  The
key signature vs. accidental thing is *much* harder to understand
for newbies.

Look, this is the NR, not LM 2.  The reader knows the basics.
They don't need ridiculous reassurance that ^\markup{ foo } is a
"specific" syntax.


> > ok, I'm bored again.
> 
> Did I ever mention you're easily bored? :-)

Editing documentation *is* boring.  But I'll have you note that I
processed 99% of doc updates within a 12 hours for the *whole
year* that I was running GDP.  And the remaining 1% was delayed
for academic work, not because I was bored did fun stuff instead.

Cheers,
- Graham