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

From:

Graham Percival

Subject:

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

Date:

Mon, 6 Oct 2008 06:01:06 -0700

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