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

[marc]

On 2012/10/23 09:03:32, J_lowe wrote:
> Mark,

> Nearly there.

Hey, sounds prominsing ;-)


> 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

Ok.


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.

Ok, will do.


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}

Ok. I found examples where @samp is used in similar circumstances,
but I trust you on this.


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.

I used typewriter and did not use verbatim, because I have to
define several bar lines which clutters the output IMHO.

But in combination with the proposed reordering, it may make more
sense.




> 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.

The reason is that the "=" is spaced according to the width of
the "S" sign; if you use this as a normal bar line, the internal
spacing in combination with the bar line padding looks way too ugly.

But I see your point: this explanation is probably too complicated;
I'll go for 'Do not use ...'


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?

Oh, I was somewhat proud to have *one* example where the
'-' *and* the ' ' were explained simultaneously and quite
naturally (at least IMHO).



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.

Oops.


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

Ok.



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