Doc: Issue 5032: Using \with with \chords, \drums and \figures

Doc: Issue 5032: Using \with with \chords, \drums and \figures

Document the use of \with with the short forms of the
input-mode-specifying commands.

[thomasmorley651, 2017-01-17 00:13:53]

A nit, otherwise

LGTM

Please see the tracker for some other general comments

https://codereview.appspot.com/313330043/diff/1/Documentation/notation/changi...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/313330043/diff/1/Documentation/notation/changi...
Documentation/notation/changing-defaults.itely:1023: mode-specifying short forms
(@code{\drums}, @code{\figures}), see
As a general consideration:
What about \lyrics ?
It's still a valid command but rarely used in the docs more in the regtests (do
a git grep).
I think we should either deprecate it, removing it at some in the future.
(\notes is gone for some time now...) or we should document it. At least in NR
"Input modes"

https://codereview.appspot.com/313330043/diff/1/Documentation/notation/changi...
Documentation/notation/changing-defaults.itely:1026: Since context modifications
specified in @code{\with} blocks are inside
Why not keep @q{context modification}?

[Trevor Daniels, 2017-01-19 20:24:52]

On 2017/01/17 00:13:53, thomasmorley651 wrote:

> LGTM

Thanks for the review!
 
> Please see the tracker for some other general comments

I've created a new issue - 5034 - to deal with these.
 
> As a general consideration:
> What about \lyrics ?
> It's still a valid command but rarely used in the docs more in the regtests
(do
> a git grep).
> I think we should either deprecate it, removing it at some in the future.
> (\notes is gone for some time now...) or we should document it. At least in NR
> "Input modes"

I agree we need to document it.  See Issue 5034.
 
> Documentation/notation/changing-defaults.itely:1026: Since context
modifications
> specified in @code{\with} blocks are inside
> Why not keep @q{context modification}?

Well, I didn't think the quotes adding any meaning.  Quotes are usually added
when a term is unusual, slightly inaccurate or slightly inappropriate, but the
term seems entirely appropriate to me.  What meaning do you think is added by
the quotes?

Trevor

[thomasmorley651, 2017-01-22 12:09:25]

On 2017/01/19 20:24:52, Trevor Daniels wrote:
> On 2017/01/17 00:13:53, thomasmorley651 wrote:
>  
> > Documentation/notation/changing-defaults.itely:1026: Since context
> modifications
> > specified in @code{\with} blocks are inside
> > Why not keep @q{context modification}?
> 
> Well, I didn't think the quotes adding any meaning.  Quotes are usually added
> when a term is unusual, slightly inaccurate or slightly inappropriate, but the
> term seems entirely appropriate to me.

I'd use quotes for well defined and used technical terms as well. Simply to sort
of emphasize it.

> What meaning do you think is added by
> the quotes?

My thought was to point the user to this "well defined and used technical term",
but I did a git grep for "context modification".
Turns out it is used only three times in the docs (three more in the regtests).

Regarding those, I'm not sure one can speak of a "well defined and used
technical term".

So it's up to you.
I'm fine with either way.

[Trevor Daniels, 2017-01-22 18:02:49]

On 2017/01/22 12:09:25, thomasmorley651 wrote:
> On 2017/01/19 20:24:52, Trevor Daniels wrote:
> > On 2017/01/17 00:13:53, thomasmorley651 wrote:
> >  
> > > Documentation/notation/changing-defaults.itely:1026: Since context
> > modifications
> > > specified in @code{\with} blocks are inside
> > > Why not keep @q{context modification}?
> > 
> > Well, I didn't think the quotes adding any meaning.  Quotes are usually
added
> > when a term is unusual, slightly inaccurate or slightly inappropriate, but
the
> > term seems entirely appropriate to me.
> 
> I'd use quotes for well defined and used technical terms as well. Simply to
sort
> of emphasize it.
> 
> > What meaning do you think is added by
> > the quotes?
> 
> My thought was to point the user to this "well defined and used technical
term",
> but I did a git grep for "context modification".
> Turns out it is used only three times in the docs (three more in the
regtests).
> 
> Regarding those, I'm not sure one can speak of a "well defined and used
> technical term".
> 
> So it's up to you.
> I'm fine with either way.

Thanks for the explanation.  I think I prefer it without "".

Pushed to staging as 27661bd698d2f501ee621beb598dd9a3b48cdbb2

Closing ...