Issue 551270043: Doc: NR - Doc CSS colour support
|
Created:
5 years, 4 months ago by pkx166h-lilypond Modified:
5 years, 4 months ago CC:
lilypond-devel_gnu.org Visibility:
Public. |
DescriptionDoc: NR - Doc CSS colour support
Issue 5537
Document support for CSS colour.
This function was added in
commit 7ecc24c5
Includes minor layout fixes
and edits to incorporate both
X11 and CSS support in the same
NR section and appendixes.
(note: as this enhancement is already in 2.20 branch, I have created a new tracker (#5644) specifically for the changes.tely entry so that it can be merged into 2.20 separately.
Patch Set 1 #
Total comments: 6
Patch Set 2 : Typos from Werner L. #Patch Set 3 : Removal of i.e. and e.g. (and so ugly commas) #
Total comments: 2
MessagesTotal messages: 10
LGTM, with some minor remarks. https://codereview.appspot.com/551270043/diff/575420043/Documentation/notatio... File Documentation/notation/editorial.itely (right): https://codereview.appspot.com/551270043/diff/575420043/Documentation/notatio... Documentation/notation/editorial.itely:496: symbol in the form @code{'@var{FooBar}} or a string in the form If you use 'FooBar' as an example for an argument, it's better to *not* use '@var'. If you want to use '@var', say @code{'@var{color}} to make 'color' a meta-variable and use @var{color} in the surrounding text as a reference to it. https://codereview.appspot.com/551270043/diff/575420043/Documentation/notatio... Documentation/notation/editorial.itely:579: Not all colors are distinguishable in a web browser, i.e. a web browser There should always a comma after 'i.e.', as far as I know. And please avoid lines longer than 80 characters. https://codereview.appspot.com/551270043/diff/575420043/Documentation/notatio... File Documentation/notation/notation-appendices.itely (right): https://codereview.appspot.com/551270043/diff/575420043/Documentation/notatio... Documentation/notation/notation-appendices.itely:863: Any name that is spelled as a single word with capitalization (e.g. AFAIK, there should always be a comma after 'e.g.'. This is especially important for the PDFs since by default `texinfo.tex` doesn't use frenchspacing, thus inserting a larger horizontal space after a full stop.
Sign in to reply to this message.
Typos from Werner L.
Sign in to reply to this message.
https://codereview.appspot.com/551270043/diff/575420043/Documentation/notatio... File Documentation/notation/editorial.itely (right): https://codereview.appspot.com/551270043/diff/575420043/Documentation/notatio... Documentation/notation/editorial.itely:496: symbol in the form @code{'@var{FooBar}} or a string in the form On 2019/12/18 18:02:33, lemzwerg wrote: > If you use 'FooBar' as an example for an argument, it's better to *not* use > '@var'. If you want to use '@var', say > > @code{'@var{color}} > > to make 'color' a meta-variable and use @var{color} in the surrounding text as a > reference to it. Thanks, that is better. Done. https://codereview.appspot.com/551270043/diff/575420043/Documentation/notatio... Documentation/notation/editorial.itely:579: Not all colors are distinguishable in a web browser, i.e. a web browser On 2019/12/18 18:02:33, lemzwerg wrote: > There should always a comma after 'i.e.', as far as I know. > Nope. It's grammatical dogma (in the same vein as not starting sentences with the words 'And' or 'Because). I think commas after these abbreviations look ugly. It's not CG policy either - I checked - and, in fact, the examples we give in CG 5.4.7 don't use commas either. > And please avoid lines longer than 80 characters. Thanks, fixed. https://codereview.appspot.com/551270043/diff/575420043/Documentation/notatio... File Documentation/notation/notation-appendices.itely (right): https://codereview.appspot.com/551270043/diff/575420043/Documentation/notatio... Documentation/notation/notation-appendices.itely:863: Any name that is spelled as a single word with capitalization (e.g. On 2019/12/18 18:02:33, lemzwerg wrote: > AFAIK, there should always be a comma after 'e.g.'. See my comment on the other file about this. > > This is especially important for the PDFs since by default `texinfo.tex` doesn't > use frenchspacing, thus inserting a larger horizontal space after a full stop. So? If it were that bad why are we using two spaces after a full point then? Which has nothing to do with grammar and would mean this would have to be made policy (which it isn't) and fixed throughout the entire doc.
Sign in to reply to this message.
> > There should always a comma after 'i.e.', as far as I know. > > Nope. It's grammatical dogma (in the same vein as not > starting sentences with the words 'And' or 'Because). > I think commas after these abbreviations look ugly. I'm not a native speaker, but I think exactly the opposite, given that 'i.e.' means 'that is' and 'e.g.' means 'for example'. > > This is especially important for the PDFs since by default > > `texinfo.tex` doesn't use frenchspacing, thus inserting a > larger horizontal space after a full stop. > > So? If it were that bad why are we using two spaces after > a full point then? I'm talking about the printed *output*. Having two spaces in the *input* files is a convention to better support editors like Emacs who use those spaces to recognize sentence endings, allowing quick sentence-wise navigation. > Which has nothing to do with grammar and would mean this would have to be made > policy (which it isn't) and fixed throughout the entire doc. By default, texinfo follows the convention of inserting more horizontal space after a full stop in the printed output (both info and PDF). Having this additional space looks extremely ugly if it is not the end of a sentence (like in abbreviations 'e.g.' or 'i.e.'). We have three possibilities to fix this. (1) Insert a comma after such abbreviations. This is what I would do, and I already tried to handle that in a uniform way in a few previous commits (at least for the NR). BTW, you might check whether the majority cases in the docs are either 'e.g.,' or 'e.g.'. (2) Insert `@:` after a full stop that doesn't end a sentence. (3) Insert the command `@frenchspacing on` in the preamble to disable this American typography feature. We *must* do one of the three solutions. Otherwise we get really ugly output in the info and PDF formats.
Sign in to reply to this message.
On 2019/12/20 00:01:59, lemzwerg wrote: > > > There should always a comma after 'i.e.', as far as I know. > > > > Nope. It's grammatical dogma (in the same vein as not > > starting sentences with the words 'And' or 'Because). > > I think commas after these abbreviations look ugly. > > I'm not a native speaker, but I think exactly the opposite, given that 'i.e.' > means 'that is' and 'e.g.' means 'for example'. > > > > This is especially important for the PDFs since by default > > > `texinfo.tex` doesn't use frenchspacing, thus inserting a > > larger horizontal space after a full stop. > > > > So? If it were that bad why are we using two spaces after > > a full point then? > > I'm talking about the printed *output*. Having two spaces in the *input* files > is a convention to better support editors like Emacs who use those spaces to > recognize sentence endings, allowing quick sentence-wise navigation. > > > Which has nothing to do with grammar and would mean this would have to be made > > policy (which it isn't) and fixed throughout the entire doc. > > By default, texinfo follows the convention of inserting more horizontal space > after a full stop in the printed output (both info and PDF). Having this > additional space looks extremely ugly if it is not the end of a sentence (like > in abbreviations 'e.g.' or 'i.e.'). We have three possibilities to fix this. > > (1) Insert a comma after such abbreviations. This is what I would do, and I > already tried to handle that in a uniform way in a few previous commits (at > least for the NR). BTW, you might check whether the majority cases in the docs > are either 'e.g.,' or 'e.g.'. > (2) Insert `@:` after a full stop that doesn't end a sentence. > (3) Insert the command `@frenchspacing on` in the preamble to disable this > American typography feature. > > We *must* do one of the three solutions. Otherwise we get really ugly output in > the info and PDF formats. Chicago manual of style says: <https://writingexplained.org/chicago-style/ie-and-eg>, namely use a comma here. The two-space after period rule for Emacs is not just for sentence navigation but also for auto-fill-mode (and various other commands) to refrain from creating a line wrap in the middle of an abbreviation. Whether or not we care about the grammatical dogma of the U.S. centric Chicago Manual of Style, TeX (and in consequence Texinfo) have doctored their input conventions around that. TeX does not add sentence-end space after a capital letter followed by a period, like Donald E. Knuth, but has no such qualms after lowercase letters. And for better or worse, we do follow U.S. usage (like with spellings of color and center rather than colour and centre) in the LilyPond documentation in general.
Sign in to reply to this message.
Removal of i.e. and e.g. (and so ugly commas)
Sign in to reply to this message.
On 2019/12/20 00:45:05, dak wrote: > On 2019/12/20 00:01:59, lemzwerg wrote: > > > > There should always a comma after 'i.e.', as far as I know. > > > > > > Nope. It's grammatical dogma (in the same vein as not > > > starting sentences with the words 'And' or 'Because). > > > I think commas after these abbreviations look ugly. > > > > I'm not a native speaker, but I think exactly the opposite, given that 'i.e.' > > means 'that is' and 'e.g.' means 'for example'. I don't understand your point. The lack of commas here does not in any way, shape, or form, create an ambiguity of meaning. If I were to write out the 'translation' of i.e. in full then perhaps you'd have a point, but then only if the sentence required it. > > > > > > This is especially important for the PDFs since by default > > > > `texinfo.tex` doesn't use frenchspacing, thus inserting a > > > larger horizontal space after a full stop. > > > > > > So? If it were that bad why are we using two spaces after > > > a full point then? > > > > I'm talking about the printed *output*. Having two spaces in the *input* > files > > is a convention to better support editors like Emacs who use those spaces to > > recognize sentence endings, allowing quick sentence-wise navigation. > > > > > Which has nothing to do with grammar and would mean this would have to be > made > > > policy (which it isn't) and fixed throughout the entire doc. > > > > By default, texinfo follows the convention of inserting more horizontal space > > after a full stop in the printed output (both info and PDF). Having this > > additional space looks extremely ugly if it is not the end of a sentence (like > > in abbreviations 'e.g.' or 'i.e.'). We have three possibilities to fix this. > > > > (1) Insert a comma after such abbreviations. This is what I would do, and I > > already tried to handle that in a uniform way in a few previous commits (at > > least for the NR). BTW, you might check whether the majority cases in the > docs > > are either 'e.g.,' or 'e.g.'. > > (2) Insert `@:` after a full stop that doesn't end a sentence. > > (3) Insert the command `@frenchspacing on` in the preamble to disable this > > American typography feature. > > > > We *must* do one of the three solutions. Otherwise we get really ugly output > in > > the info and PDF formats. > > Chicago manual of style says: > <https://writingexplained.org/chicago-style/ie-and-eg>, namely use a comma here. > The two-space after period rule for Emacs is not just for sentence navigation > but also for auto-fill-mode (and various other commands) to refrain from > creating a line wrap in the middle of an abbreviation. > > Whether or not we care about the grammatical dogma of the U.S. centric Chicago > Manual of Style, TeX (and in consequence Texinfo) have doctored their input > conventions around that. TeX does not add sentence-end space after a capital > letter followed by a period, like Donald E. Knuth, but has no such qualms after > lowercase letters. And for better or worse, we do follow U.S. usage (like with > spellings of color and center rather than colour and centre) in the LilyPond > documentation in general. I've never understood the point of two spaces after a full point - and and yes, I've read all the (unconvincing) arguments for it. Yet at the same time, I see the amount of hand wringing and discussion on these lists about all the various spacing preferences (slurs-vs-ties differences or the size of a ball on the end of a clef) as well as all the other musical notation minutiae that is so important to us, which is why I find this discussion rather disappointing. Bugger to the Chicago Manual of (so called) Style! New patch uploaded.
Sign in to reply to this message.
LGTM, thanks! https://codereview.appspot.com/551270043/diff/583260043/Documentation/notatio... File Documentation/notation/editorial.itely (right): https://codereview.appspot.com/551270043/diff/583260043/Documentation/notatio... Documentation/notation/editorial.itely:576: X11 and CSS colors will not always be exactly the same as a similarly Wouldn't it be better to use present tense? At least this is the recommendation in the GNU coding standards, see https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html https://codereview.appspot.com/551270043/diff/583260043/Documentation/notatio... Documentation/notation/editorial.itely:584: Hex codes for either CSS or X11 cannot be used. s/hex codes/hexadecimal values/
Sign in to reply to this message.
> > > I'm not a native speaker, but I think exactly the opposite, > > > given that 'i.e.' means 'that is' and 'e.g.' means 'for > > > example'. > > I don't understand your point. [...] It's a matter of style, not a matter of grammar correctness. > I've never understood the point of two spaces after a full point > - and and yes, I've read all the (unconvincing) arguments for it. Again, it's a matter of style, and maybe for the benefit of editors (at least Emacs). > Yet at the same time, I see the amount of hand wringing and > discussion on these lists about all the various spacing > preferences (slurs-vs-ties differences or the size of a ball > on the end of a clef) as well as all the other musical > notation minutiae that is so important to us, which is why I > find this discussion rather disappointing. Well, whatever we are going to use it should be *consistent*. This has very high priority to me. I hope you can understand this, and I also hope that you second it. > Bugger to the Chicago Manual of (so called) Style! I don't mind if we follow a different style. What would you recommend?
Sign in to reply to this message.
> I don't mind if we follow a different style. What would > you recommend? Of course, changing the style would mean that all occurrences should be fixed.
Sign in to reply to this message.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
