Re: adds documentation for the new bar line interface (issue 6742061)

[pkx166h]

Mark,

Nearly there.

Some more general comments - some are Doc Policy, some are my own views
on how to organize this section, also can you make sure you use two
spaces after a full point (full stop) as this is also the CG policy
(even if it does go against every grain in my typographically-based
bones!).

James


https://codereview.appspot.com/6742061/diff/8001/Documentation/notation/rhythms.itely
File Documentation/notation/rhythms.itely (right):

https://codereview.appspot.com/6742061/diff/8001/Documentation/notation/rhythms.itely#newcode2693
Documentation/notation/rhythms.itely:2693: Further details of this
notation are explained in @ref{Typesetting Kievan square notation}.
Make sure you only use max 72 chars per line and dont break @ref{...}
over two lines

http://lilypond.org/doc/v2.16/Documentation/contributor/syntax-survey#cross-references

Causes problems in texinfo output

https://codereview.appspot.com/6742061/diff/8001/Documentation/notation/rhythms.itely#newcode2780
Documentation/notation/rhythms.itely:2780: \defineBarLine @var{bartype}
#'(@var{bar-line-at-end-of-line} @var{bar-line-at-begin-of-line}
@var{span-bar-line})
You probably aught to shorten the variable names for the doc (even if
the function names internally are called this, most users don't care and
you always have the @ref{} under the @seealso  at the end of the section
to link to the ly: file for those that are really curious.

@var{type} @var{end} @var{begin} @var{span} else if you do end up going
over 72 chars, break and indent the line as you would a lilypond
example.

Makes it clearer for readers.

https://codereview.appspot.com/6742061/diff/8001/Documentation/notation/rhythms.itely#newcode2784
Documentation/notation/rhythms.itely:2784: @samp{\bar "bartype"}.
Use @code{\bar} @var{bartype}

https://codereview.appspot.com/6742061/diff/8001/Documentation/notation/rhythms.itely#newcode2792
Documentation/notation/rhythms.itely:2792: bar line.
Move the Para above the previous (just after the @example).

The @code{\defineBarline} variables can include the @q{empty} string
@code{""},
which is equivalent to an invisible bar line being printed.  Or they can
be set
to @code{#f} which prints no bar line at all.

--

The implication being that an invisible bar line uses normal
padding/spacing.
This also saves you repeating all the @var{}s again.

https://codereview.appspot.com/6742061/diff/8001/Documentation/notation/rhythms.itely#newcode2822
Documentation/notation/rhythms.itely:2822: s1 \bar "]" \mark \markup {
\typewriter "]" }
I am guessing that \typewriter is used here to prevent century
schoolbook and so make the characters more obvious, however there is no
need if you use the normal @lilypond[verbatim, quote etc.] as this *is*
printed in 'typewriter' font in the doc (and is why we do this), so you
can rmeove all the \mark \markup { } from this if you use the correct
@lilypond variables.

Also, could we move this whole @lilypond section right up to  the
(almost) start, under the para

'After the definiton, the new bar line can be used by @samp{\bar
"bartype"}.'

---

That way we get right to the point and then can do the detail
afterwards, so to speak. It's not complicated to understand and so the
finer points can be explained as the reader reads through.

https://codereview.appspot.com/6742061/diff/8001/Documentation/notation/rhythms.itely#newcode2828
Documentation/notation/rhythms.itely:2828: combination with the segno
sign. It is not recommended for use as
could we have a short reason it is not recommended? Else I always just
say 'Do not use ....'. I prefer to be led than given choice if it's that
subtle or there is no explanation on why I might not 'prefer' to do
something.

https://codereview.appspot.com/6742061/diff/8001/Documentation/notation/rhythms.itely#newcode2829
Documentation/notation/rhythms.itely:2829: a standalone double thin bar
line; here, @samp{\bar "||"} is
... here, @code{\bar} @var{"||"} is ...

https://codereview.appspot.com/6742061/diff/8001/Documentation/notation/rhythms.itely#newcode2832
Documentation/notation/rhythms.itely:2832: The @code{"-"} sign
distinguishes bar lines with
The @code{"-"} sign separates (?). Could we have an @lilypond example
here to show like you do with the @code{" "} example below?

https://codereview.appspot.com/6742061/diff/8001/Documentation/notation/rhythms.itely#newcode2854
Documentation/notation/rhythms.itely:2854: If additional elements are
needed, Lilypond provides a simple
LilyPond not Lilypond.

https://codereview.appspot.com/6742061/diff/8001/Documentation/notation/rhythms.itely#newcode2856
Documentation/notation/rhythms.itely:2856: bar lines, see file
@file{scm/bar-line.scm}.
Add this @file{} reference to an @seealso at the end.

See:
http://lilypond.org/doc/v2.16/Documentation/contributor/syntax-survey#cross-references

and

http://lilypond.org/doc/v2.16/Documentation/contributor/section-organization

https://codereview.appspot.com/6742061/