Doc: Clarify automatic beam setting (2701)

Doc: Clarify automatic beam setting (2701)

Explain at the beginning the precedence of the
rules, and include an example to show how to
disable beamExceptions.

[Trevor Daniels, 2012-07-31 22:30:12]

For Graham, really:

http://codereview.appspot.com/6452072/diff/1/Documentation/notation/rhythms.i...
File Documentation/notation/rhythms.itely (right):

http://codereview.appspot.com/6452072/diff/1/Documentation/notation/rhythms.i...
Documentation/notation/rhythms.itely:2007: @i{@strong{Beaming based on
@code{baseMoment} and @code{beatStructure}}}
I don't like this either, but it was already used elsewhere in this section.  We
already have unnumberedsubsubsec, so can't use that.

[Trevor Daniels, 2012-08-02 21:03:15]

In vocal.itely both @subheading and @subsubheading are used.
The CG advice is to use @subheading.
Both have disadvantages:
  @subheading looks like @unnumberedsubsubsec
  @subsubheading looks like Known issues and warnings et al.

So maybe @i{@strong .. }} is not so bad after all, at least 
in its appearance if not in its syntax.  It does at least
look like a level below @subheading/@unnumberedsubsubsec.

Trevor

[Graham Percival, 2012-08-03 09:30:55]

LGTM although I'm not wild about the @i{} bits, I can't immediately think of a
better alternative.

[dak, 2012-08-03 09:35:47]

On 2012/08/03 09:30:55, Graham Percival wrote:
> LGTM although I'm not wild about the @i{} bits, I can't immediately think of a
> better alternative.

The obvious way would be to reorganize into fewer layers.  Nobody is going to
keep track of that many anyway.

That @i{} stuff is not really good: it has the wrong spacing and penalties for a
heading.  For example, it might get separated by a page break from its following
text.  It will also usually be followed by indented text as opposed to normal
headings.  And will probably be indented itself.

[Trevor Daniels, 2012-08-04 08:06:38]

On 2012/08/03 09:35:47, dak wrote:

> The obvious way would be to reorganize into fewer layers.

No.  This is a long and complicated subsubsec and the point
of this issue is to improve clarity.  The best way of doing
that is to introduce structure into the very long text.  In
particular we need to clearly distinguish the two methods of
controlling automatic beaming so they can be contrasted and
referenced.

> That @i{} stuff is not really good: it has the wrong 
> spacing and penalties for a heading.  For example, it 
> might get separated by a page break from its following
> text.  

This is a drawback, but not a disaster -- it might not
happen.  It's a pity @group does not work reliably
in this situation, though.

> It will also usually be followed by indented text 
> as opposed to normal headings.  And will probably 
> be indented itself.

Neither it nor the following text are indented in html.
In pdf the heading is indented, but in my view this is
not detrimental to its purpose.  Far worse would be
to use @unnumberedsubsubsec or @subsubheading as these
all look identical in pdf and the intended structuring
is lost.

So on balance we should go with @i{@strong ..}} as the
best of the poor choices available.

Trevor

[dak, 2012-08-04 08:27:10]

On 2012/08/04 08:06:38, Trevor Daniels wrote:
> On 2012/08/03 09:35:47, dak wrote:
> 
> > The obvious way would be to reorganize into fewer layers.
> 
> No.  This is a long and complicated subsubsec

Reorganizing into fewer layers would mean reorganizing the containing structure
so that we don't already end up in a subsubsec.

> and the point
> of this issue is to improve clarity.  The best way of doing
> that is to introduce structure into the very long text.

A very long text is not suitable as a subsubsec.

> In particular we need to clearly distinguish the two methods of
> controlling automatic beaming so they can be contrasted and
> referenced.
> 
> > That @i{} stuff is not really good: it has the wrong 
> > spacing and penalties for a heading.  For example, it 
> > might get separated by a page break from its following
> > text.  
> 
> This is a drawback, but not a disaster -- it might not
> happen.

A disaster waiting to happen is not a great thing.  In particular since it will
tend to happen undercover.  People are not likely to recheck all page breaks
just because they change an unrelated section some place above.

> > It will also usually be followed by indented text 
> > as opposed to normal headings.  And will probably 
> > be indented itself.
> 
> Neither it nor the following text are indented in html.
> In pdf the heading is indented, but in my view this is
> not detrimental to its purpose.

A heading indented as opposed to the following main paragraph shape?  Ugh, ugh,
ugh.

> Far worse would be
> to use @unnumberedsubsubsec or @subsubheading as these
> all look identical in pdf and the intended structuring
> is lost.
> 
> So on balance we should go with @i{@strong ..}} as the
> best of the poor choices available.

I don't see any balance at all.  It is not like anything precludes you from
using @unnumberedsubsubsec @i{@strong ...} so it is not like using the heading
commands for getting proper header distances, page breaks and indentation
precludes you from additional markups.

But again: the real issue to me seems that we are hiding a long chapter inside
of a subsubsec already.

[Trevor Daniels, 2012-08-04 09:20:57]

On 2012/08/04 08:27:10, dak wrote:

> But again: the real issue to me seems that we are 
> hiding a long chapter inside of a subsubsec already.

I agree.  But to fix that would require rewriting pretty
well the whole of chapter 1 of the NR.  I'm not going to
do that.  Let's just fix this simple issue and move on,
please.  It's not ideal, but it's the best course available
to us.

And please stop sneering.  

Trevor

[dak, 2012-08-04 09:33:33]

On 2012/08/04 09:20:57, Trevor Daniels wrote:
> On 2012/08/04 08:27:10, dak wrote:
> 
> > But again: the real issue to me seems that we are 
> > hiding a long chapter inside of a subsubsec already.
> 
> I agree.  But to fix that would require rewriting pretty
> well the whole of chapter 1 of the NR.  I'm not going to
> do that.  Let's just fix this simple issue and move on,
> please.  It's not ideal, but it's the best course available
> to us.

I don't see that ignoring even the proposal to use a combination of structuring
commands with explicit markup is "the best course available".

> And please stop sneering.  

I would have called it "reviewing".  Since I don't assume that you ask me to
stop reviewing altogether, it would help if you pointed out what parts of the
review you consider "sneering".  I don't have the communication skills required
for telling the difference.

[Trevor Daniels, 2012-08-04 15:11:55]

On 2012/08/04 09:33:33, dak wrote:

> I don't see that ignoring even the proposal to use 
> a combination of structuring commands with explicit 
> markup is "the best course available".

I'm sorry - I completely missed this.  Probably because
I was hung up by the earlier sneer and didn't take in
much else.  Since you ask, the bit that affected me was

> A heading indented as opposed to the following main 
> paragraph shape?  Ugh, ugh, ugh.

That was belittling my opinion (which I still hold) 
in a rather nasty way.

I'll look again at your suggestion.  Thanks.

Trevor

[dak, 2012-08-04 15:35:44]

On 2012/08/04 15:11:55, Trevor Daniels wrote:
> On 2012/08/04 09:33:33, dak wrote:
>
> I'm sorry - I completely missed this.  Probably because
> I was hung up by the earlier sneer and didn't take in
> much else.  Since you ask, the bit that affected me was
> 
> > A heading indented as opposed to the following main 
> > paragraph shape?  Ugh, ugh, ugh.
> 
> That was belittling my opinion (which I still hold) 
> in a rather nasty way.

It was not at all intended personally.  It expressed my rather strong
disapproval with the typesettings aethetics of a construct that looks like the
following.

    *This is supposed to be a heading*

    And this is supposed to be the text following the heading.  Note that there
is no spacing other than the normal paragraph spacing both before and after that
paragraph.

*Now this is a heading*

And as opposed to the above, it does not look like a normally occuring
paragraph, but has some markup that fits its function of separating a new
sequence of paragraphs.  And it does not break completely out the otherwise
consistent formatting of header material.

I don't expect everybody to be a typographer (my last freelance job before
LilyPond was in the area of book design and automated typesetting, and actually
so was my last regular job as well).  That "Ugh, ugh, ugh" was not expressing my
opinion of you, but rather of how the proposed layout appealed to my sense of
aethetics.

It is possible to make an indented book design, though quite challenging to
bring of consistently.  But it does not belong in the middle of material
formatted with different conventions.

[Trevor Daniels, 2012-08-04 21:42:30]

OK, I think we've arrived at an acceptable solution,
albeit via a somewhat circuitous route, posted as patch
set 2.

I'll wait to see how this looks in the pdf version and
if all is well I'll add this recipe to the CG and change
the couple of other places where this level of structuring
is used.

[Trevor Daniels, 2012-08-07 21:19:00]

Pushed to staging as
593d611c5f63f3fedadf299e124a83ca4a709fe6
Leaving open until pdf has been checked

[Trevor Daniels, 2012-08-08 18:58:08]

On 2012/08/07 21:19:00, Trevor Daniels wrote:

> Leaving open until pdf has been checked

In the pdf all the headings below subsection are in the
same typeface, so it makes no difference to the pdf what
we do for these level 5 headings.

In html they are all in differently sized fonts, but  
using @unnumberedsubsubsec @i{@strong { .. }} uses the
same size font as @unnumberedsubsubsec (of course) and
also lists the heading in the contents.  Both of these
look wrong to me.  So I think @subsubheading @i{ .. }
would be best.  This should use a smaller font and
exclude the heading from the contents.  I'll try this next.

Trevor

[dak, 2012-08-08 19:13:42]

On 2012/08/08 18:58:08, Trevor Daniels wrote:
> On 2012/08/07 21:19:00, Trevor Daniels wrote:
> 
> > Leaving open until pdf has been checked
> 
> In the pdf all the headings below subsection are in the
> same typeface, so it makes no difference to the pdf what
> we do for these level 5 headings.
> 
> In html they are all in differently sized fonts, but  
> using @unnumberedsubsubsec @i{@strong { .. }} uses the
> same size font as @unnumberedsubsubsec (of course) and
> also lists the heading in the contents.  Both of these
> look wrong to me.  So I think @subsubheading @i{ .. }
> would be best.  This should use a smaller font and
> exclude the heading from the contents.  I'll try this next.

Sounds reasonable.  Thanks for staying with this until it pans out.

[Trevor Daniels, 2012-08-09 07:36:46]

Changed level 5 headings to @subsubheading @i{ .. }
and pushed directly to staging as
bc573af397a1b54f35fb1f95b3ee2e5360d4152f
If these look ok on grenouille I'll open a new issue
to track down and change all other occurrences of
level 5 headings and update the CG.

Trevor

[Trevor Daniels, 2012-08-10 07:54:51]

On 2012/08/09 07:36:46, Trevor Daniels wrote:

> Changed level 5 headings to @subsubheading @i{ .. }

These look fine to me in both pdf and html, so I'm
closing this review.  I'll open a new issue tracker 
to cover using level 5 headings uniformly.

Trevor

[dak, 2012-08-10 08:37:51]

On 2012/08/10 07:54:51, Trevor Daniels wrote:
> On 2012/08/09 07:36:46, Trevor Daniels wrote:
> 
> > Changed level 5 headings to @subsubheading @i{ .. }
> 
> These look fine to me in both pdf and html, so I'm
> closing this review.  I'll open a new issue tracker 
> to cover using level 5 headings uniformly.

If we need them semi-regularly, maybe we should invent a name for them and use a
macro?