Doc: Add how to change the notation fonts

Issue 5137/2: Doc: Add how to use set-global-fonts for non-music fonts


Issue 5137/1: Doc: Add how to change the notation fonts

[tisimst, 2017-08-17 20:19:58]

https://codereview.appspot.com/330040043/diff/1/Documentation/notation/input....
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/330040043/diff/1/Documentation/notation/input....
Documentation/notation/input.itely:2845: @end example
I think it would be prudent to show all the inputs in one place, at least their
defaults, so users know what acceptable. At the moment they are: 
- #:music
- #:brace
- #:roman
- #:sans
- #:typewriter

I know the text font keywords show up in text.itely, but I think they should all
show up together somewhere.

It is also important for users to understand that you can only apply
(set-global-fonts ... ) once per \book block since it resets the `fonts`
variable each time you call the function. The following does work, though:

\paper {
  #(set-global-fonts ... )
}
\book { ... }

\paper {
  #(set-global-fonts ... )
}
\book { ... }

where each call to set-global-fonts only affects the book(s) following it unless
re-called as shown.

https://codereview.appspot.com/330040043/diff/1/Documentation/notation/input....
Documentation/notation/input.itely:2866: you can use them in the same way as
Gonville.
This is true, but at the moment, the only allowed font names must have the
following suffixes: -11, -13, -14, -16, -18, -20, -23, -26, -brace. This is
easily remedied by modifying the internal function, but for now at the user
level, this is a significant limitation because it assumes that the music font
has ALL the above optical sizes and/or brace font. Not sure what information
here is most appropriate, but I think we would should at least raise this flag
so users realize that you can't use just any music font out there that might
work with other apps (like Sibelius, Finale, Dorico, etc.).

[tisimst, 2017-08-17 20:23:56]

https://codereview.appspot.com/330040043/diff/1/Documentation/notation/text.i...
File Documentation/notation/text.itely (right):

https://codereview.appspot.com/330040043/diff/1/Documentation/notation/text.i...
Documentation/notation/text.itely:1627: #:factor (/ staff-height pt 20)
I'm not sure showing the use of #:factor is helpful here, unless we also show
WHY, which is, if set-global-staff-size is used to change the staff size from
the default of 20pt.

So, I'd either recommend removing this line or adding a staff size change along
with an explanation.

[trueroad, 2017-08-18 03:30:22]

Add some explanation

[trueroad, 2017-08-18 03:36:36]

Thank you for your reviewing.

https://codereview.appspot.com/330040043/diff/1/Documentation/notation/input....
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/330040043/diff/1/Documentation/notation/input....
Documentation/notation/input.itely:2845: @end example
On 2017/08/17 20:19:58, tisimst wrote:
> I think it would be prudent to show all the inputs in one place, at least
their
> defaults, so users know what acceptable. At the moment they are: 
> - #:music
> - #:brace
> - #:roman
> - #:sans
> - #:typewriter
> 
> I know the text font keywords show up in text.itely, but I think they should
all
> show up together somewhere.
> 
> It is also important for users to understand that you can only apply
> (set-global-fonts ... ) once per \book block since it resets the `fonts`
> variable each time you call the function. The following does work, though:
> 
> \paper {
>   #(set-global-fonts ... )
> }
> \book { ... }
> 
> \paper {
>   #(set-global-fonts ... )
> }
> \book { ... }
> 
> where each call to set-global-fonts only affects the book(s) following it
unless
> re-called as shown.

I've added detail in `text.itely`.

https://codereview.appspot.com/330040043/diff/1/Documentation/notation/input....
Documentation/notation/input.itely:2866: you can use them in the same way as
Gonville.
On 2017/08/17 20:19:58, tisimst wrote:
> This is true, but at the moment, the only allowed font names must have the
> following suffixes: -11, -13, -14, -16, -18, -20, -23, -26, -brace. This is
> easily remedied by modifying the internal function, but for now at the user
> level, this is a significant limitation because it assumes that the music font
> has ALL the above optical sizes and/or brace font. Not sure what information
> here is most appropriate, but I think we would should at least raise this flag
> so users realize that you can't use just any music font out there that might
> work with other apps (like Sibelius, Finale, Dorico, etc.).

Done.

https://codereview.appspot.com/330040043/diff/1/Documentation/notation/text.i...
File Documentation/notation/text.itely (right):

https://codereview.appspot.com/330040043/diff/1/Documentation/notation/text.i...
Documentation/notation/text.itely:1627: #:factor (/ staff-height pt 20)
On 2017/08/17 20:23:56, tisimst wrote:
> I'm not sure showing the use of #:factor is helpful here, unless we also show
> WHY, which is, if set-global-staff-size is used to change the staff size from
> the default of 20pt.
> 
> So, I'd either recommend removing this line or adding a staff size change
along
> with an explanation.

Done.

[tisimst, 2017-08-23 18:23:43]

I like the changes. Just a few more comments for clarification.

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/in...
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/in...
Documentation/notation/input.itely:2847: Note: @code{set-global-fonts} can
change not only the notation fonts
Maybe change the wording slightly:

"Note: Each call to @code{set-global-fonts} completely resets both the main
notation and text fonts. If any category is left unspecified, then the default
font will be used for that category.

Each call to @code{set-global-fonts} changes the fonts for each @code{\book}
that follows it, whether created explicitly or implicitly. This means that each
@code{\book} can have its own set of main fonts by calling
@code{set-global-fonts} before it."

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/in...
Documentation/notation/input.itely:2881: Note: The only allowed font names must
have the
I would reword this to be a bit more specific so there's no confusion about what
is/isn't expected:

"Note: At the moment, LilyPond expects the font file names to have the following
suffixes, all of which must be present in the above installation folder(s) to
work properly:"

The only caveat is that the user doesn't technically need to have BOTH the music
font set (with the -11, -13, -14, -16, -18, -20, -23, and -26 suffixes) AND a
brace font (with the -brace suffix) for one or the other to work, but the music
font set must have a file for ALL of those suffixes and the brace font must have
its suffix.

The reason for this is that the internal functions are hard-wired to require
this, but can be modified quite easily to allow for more flexibility in the
number of music font files. They could also be changed so the brace font no
longer needs its -brace suffix, but maybe it should be kept that way since
there's only one brace font file. I have configured the functions to allow this
on my machine and haven't seen any issues in functionality.

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/in...
Documentation/notation/input.itely:2884: That is, @file{@var{fontname}-11.otf},
@file{@var{fontname}-20.svg},
I think it makes sense to be specific here, with something like "For example,
@file{emmentaler-11.otf}" instead of "That is, @file{@var{fontname}-11.otf}".

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/te...
File Documentation/notation/text.itely (right):

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:1618: as the above @code{make-pango-font-tree}
example.
Since users are now using other music fonts, I think we better add a note to
make-pango-font-tree that says this resets the music font to Emmentaler so that
no one is surprised when this happens. Should make-pango-font-tree be deprecated
in favor of set-global-fonts?

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:1644: #:brace "emmentaler"            ;
default
It is important to note that the user does NOT specify the suffix of the font
(e.g, "emmentaler-18" and "emmentaler-brace"), only the root font _file name_
"emmentaler" and NOT the internal font name "Emmentaler". The suffixes are added
internally when the font tree is being created and looking up the font files. A
simple note to say the suffixes are not needed (indeed, will cause an error if
given) would suffice, IMO. This only applies to the #:music and #:brace strings.
The text fonts expect the internal font names.

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:1654: Each call of @code{set-global-fonts}
affects only the following book(s).
Maybe reword this paragraph a little:

"Each call of @code{set-global-fonts} affects each @code{\book} blocks that
follow it.

If there are multiple @code{\book} blocks and you want to use different fonts
for each, simply call @code{set-global-fonts} again, like this:"

[trueroad, 2017-08-24 12:20:48]

Add more explanation

[trueroad, 2017-08-24 12:25:50]

Thank you for your suggestion.

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/in...
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/in...
Documentation/notation/input.itely:2847: Note: @code{set-global-fonts} can
change not only the notation fonts
On 2017/08/23 18:23:42, tisimst wrote:
> Maybe change the wording slightly:
> 
> "Note: Each call to @code{set-global-fonts} completely resets both the main
> notation and text fonts. If any category is left unspecified, then the default
> font will be used for that category.
> 
> Each call to @code{set-global-fonts} changes the fonts for each @code{\book}
> that follows it, whether created explicitly or implicitly. This means that
each
> @code{\book} can have its own set of main fonts by calling
> @code{set-global-fonts} before it."

Done.

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/in...
Documentation/notation/input.itely:2881: Note: The only allowed font names must
have the
On 2017/08/23 18:23:43, tisimst wrote:
> I would reword this to be a bit more specific so there's no confusion about
what
> is/isn't expected:
> 
> "Note: At the moment, LilyPond expects the font file names to have the
following
> suffixes, all of which must be present in the above installation folder(s) to
> work properly:"
> 
> The only caveat is that the user doesn't technically need to have BOTH the
music
> font set (with the -11, -13, -14, -16, -18, -20, -23, and -26 suffixes) AND a
> brace font (with the -brace suffix) for one or the other to work, but the
music
> font set must have a file for ALL of those suffixes and the brace font must
have
> its suffix.
> 
> The reason for this is that the internal functions are hard-wired to require
> this, but can be modified quite easily to allow for more flexibility in the
> number of music font files. They could also be changed so the brace font no
> longer needs its -brace suffix, but maybe it should be kept that way since
> there's only one brace font file. I have configured the functions to allow
this
> on my machine and haven't seen any issues in functionality.

Done.

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/in...
Documentation/notation/input.itely:2884: That is, @file{@var{fontname}-11.otf},
@file{@var{fontname}-20.svg},
On 2017/08/23 18:23:43, tisimst wrote:
> I think it makes sense to be specific here, with something like "For example,
> @file{emmentaler-11.otf}" instead of "That is,
mailto:@file{@var{fontname}-11.otf}.

Done.

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/te...
File Documentation/notation/text.itely (right):

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:1618: as the above @code{make-pango-font-tree}
example.
On 2017/08/23 18:23:43, tisimst wrote:
> Since users are now using other music fonts, I think we better add a note to
> make-pango-font-tree that says this resets the music font to Emmentaler so
that
> no one is surprised when this happens. Should make-pango-font-tree be
deprecated
> in favor of set-global-fonts?

I've added the note to `make-pango-font-tree`.

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:1644: #:brace "emmentaler"            ;
default
On 2017/08/23 18:23:43, tisimst wrote:
> It is important to note that the user does NOT specify the suffix of the font
> (e.g, "emmentaler-18" and "emmentaler-brace"), only the root font _file name_
> "emmentaler" and NOT the internal font name "Emmentaler". The suffixes are
added
> internally when the font tree is being created and looking up the font files.
A
> simple note to say the suffixes are not needed (indeed, will cause an error if
> given) would suffice, IMO. This only applies to the #:music and #:brace
strings.
> The text fonts expect the internal font names.

I've added the note to `input.itely`.

https://codereview.appspot.com/330040043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:1654: Each call of @code{set-global-fonts}
affects only the following book(s).
On 2017/08/23 18:23:43, tisimst wrote:
> Maybe reword this paragraph a little:
> 
> "Each call of @code{set-global-fonts} affects each @code{\book} blocks that
> follow it.
> 
> If there are multiple @code{\book} blocks and you want to use different fonts
> for each, simply call @code{set-global-fonts} again, like this:"

Done.

[tisimst, 2017-08-24 18:38:17]

LGTM

[Jean-Charles, 2017-08-26 08:16:26]

otherwise, LGTM

https://codereview.appspot.com/330040043/diff/40001/Documentation/notation/te...
File Documentation/notation/text.itely (right):

https://codereview.appspot.com/330040043/diff/40001/Documentation/notation/te...
Documentation/notation/text.itely:1624: @code{sans}, and @code{typewriter}
categoriles.
typo: categories

[trueroad, 2017-08-26 09:37:48]

Fix typo

[trueroad, 2017-08-26 09:39:18]

Thank you for your reviewing.

https://codereview.appspot.com/330040043/diff/40001/Documentation/notation/te...
File Documentation/notation/text.itely (right):

https://codereview.appspot.com/330040043/diff/40001/Documentation/notation/te...
Documentation/notation/text.itely:1624: @code{sans}, and @code{typewriter}
categoriles.
On 2017/08/26 08:16:26, Jean-Charles wrote:
> typo: categories

Done.

[trueroad, 2017-09-01 15:26:57]

I've pushed to staging.

commit 4ca9913c540dfbfc7f598c07735c90139138327b
Issue 5137/2: Doc: Add how to use set-global-fonts for non-music fonts

commit e6c53f51c9a9f9226a89bcfb49595b468b3c3262
Issue 5137/1: Doc: Add how to change the notation fonts