subject:"Feedback wanted\: syntax highlighting in the LilyPond documentation"

Hello Paul,

The documentation does not specify any fonts. It simply uses the  and 
 tags. That means that the fonts used are whatever font your 
browser chooses as default font, which on Windows systems appears to be 
Courier for monospace and apparently in your case Georgia for the regular 
text.

If we want to specify the font we’d probably need to find good default fonts 
for every system or provide our own fonts, which would very much favour OFL/
Apache/MIT/ kind of fonts.

I strongly vote to remain with a monospace font. Regular fonts are created for 
readability of regular text. Code is fundamentally different from regular text, 
so code becomes really hard to read in regular fonts. (Basically reading of 
normal text works by recognizing the shape of the words. But code is usually 
not made up from words.

But as you’ve mentioned the Source Sans Pro: Adobe has also issued a Source 
Code Pro font for Code, which might work really well here. It comes in an 
insane amount of cuts and even has a proper italic cut!

Also Source * fonts are licensed under the OFL, so there is no problem with 
distributing them with the website.

Cheers,
Valentin

Am Dienstag, 4. Jänner 2022, 11:14:49 CET schrieb Paul McKay:
> 
> And this seems the appropriate place to ask why the examples are all in
> fixed pitch Courier in any case. I know this is kind of  industry standard
> but it's one I don't find particularly helpful. I was once adept on the
> card punch machines and mechanical typewriters, but I think most of us
> abandoned fixed pitch fonts long, long ago. I'd suggest a sans serif font
> so that there's a clear contrast with the Georgia used as the text font in
> the documentation. Helvetica, Franklin Gothic and Source Sans Pro look good
> but I realize they might not be available on some platforms.
> 
> HTH
> Paul McKay


signature.asc
Description: This is a digitally signed message part.

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

Le 04/01/2022 à 11:35, Thomas Morley a écrit :

Am Di., 4. Jan. 2022 um 11:15 Uhr schrieb Paul McKay :

Hi
Speaking as someone whose eyesight isn't quite as good as it used to be,

Same problem here

I'd like to suggest that anything in a colour is also in bold so that there are
enough pixels for me to see what the colour is.

I'd go even further, why not all bold, apart from comments?
At least that's the way I configured my own editor.

I think it would be too much. Bold conveys the
message of something important. To me, an example
that is all bold sounds a bit like shouting;
not sure if you see what I mean? Plus, testing
it with new_style.py (just set Token: "bold"
if you want to play with it), I get the feeling
of a discordance between the style of the text and
that of the code. Screenshot:

I think we should rather try to make it readable
without bold, possibly increasing the font size
a bit (it's quite small at the moment) and possibly
picking a different font.

I don't have strong feelings about colors, though. My own
configuration is indeed like "angry fruit salad", but I doubt there
will be any setting satisfying everyone.

This is possibly the wisest remark in this thread.

[Robin]
The stroke width I see is 1px (Firefox at 100%). This makes the
stroke dominated by edge effects; the surrounding white dilutes its
colour.
Do the WCAG recommendations recognise this? If not, please don't
apply their levels to this case.

I don't know. I am not a great specialist of all
the (complicated) WCAG rules. All I have been
interested in so far was the ones for color;
their criteria were a handy way to know if
the scheme was OK given that I could not experience
the highlighting from the point of view of a
colorblind person myself. The end goal is definitely
to have the documentation site readable for
everyone -- including those with disabilities --
and not just to follow recommendations blindly.

[Paul]
And this seems the appropriate place to ask why the examples are all
in fixed pitch Courier in any case. I know this is kind of industry
standard but it's one I don't find particularly helpful. I was once
adept on the card punch machines and mechanical typewriters, but I
think most of us abandoned fixed pitch fonts long, long ago. I'd
suggest a sans serif font so that there's a clear contrast with the
Georgia used as the text font in the documentation. Helvetica,
Franklin Gothic and Source Sans Pro look good but I realize they might
not be available on some platforms.

Independently of the fact that I'm not
fond of the idea, a number of documentation
examples rely on the alignment specific to
fixed-width fonts. This comes to mind for
example:

http://abou-samra.fr/highlighting-demo/notation/multiple-voices.html#writing-music-in-parallel

So there is more to such a shift than introducing
highlighting.

Regards,
Jean

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

Le 04/01/2022 à 23:19, Aaron Hill a écrit :

On 2022-01-04 1:42 pm, Jean Abou Samra wrote:

https://www.gnu.org/philosophy/javascript-trap.en.html
[ . . . ]
But I'm probably fretting for something that is
very easy in the end.

The code Lilypond's site would use would be entirely homegrown,
licensed under GPL. Not sure there is anything here to worry unless
we determine there is an external dependency that is required.

If we add a toggle for switching highlighting on and
off, then the next question will of course be what
the default should be. Without surprise, I would prefer
if it were on by default, but I wouldn't mind the
other way.

And honestly, I like the default being on, simply because it
advertises the new feature. If folks load up the docs and see the
familiar black and white, they might not know to look for the option
to enable highlighting.

Perhaps a good strategy would be to initially enable the feature for
an entire release cycle. This gets folks using it and providing
feedback. Most of the discussion so far has been limited in scope so
it is hard to know if the system works well over the entire manual and
for day-to-day usage.

I would not be surprised if some creative folks on the list end up
creating new color schemes to be included as options aside from the
default. A dark mode scheme is almost inevitable.

Absolutely agreed.

Are you sure about that? This is one page that drew
my attention:

https://law.stackexchange.com/questions/30739/do-the-gdpr-and-cookie-law-regulations-apply-to-localstorage

One of the posts a little further down talks about shopping carts.
The way I read this is that when a user is performing an action where
something being saved is reasonably expected as part of the
functionality, there is no need to ask permission. The question we
would have is whether selecting a color scheme carries an expectation
that it should persist.

Well, now that you say it: a way to go
about it would be to make it explicit,
with "Save my preference for all visits",
"Permanent setting" or something like that.
This would be a useful piece of information
regardless.

Thanks!
Jean

Re: Feedback wanted: syntax highlighting in the LilyPond documentation


Le 04/01/2022 à 00:33, David Kastrup a écrit :

Flaming Hakama by Elaine  writes:


In this sense, it seems like the place that has the most potential use
for helping people distinguish different data types is where the
syntax is the most complicated and dense, which is in music entry.

The ability to quickly distinguish articulations, dynamics, notes, and
durations seems like it would probably be most useful to people
reading examples in docs, since that is the most unusual aspect of
lilypond syntax.

I find splitting a8 into different colors about as helpful for reading
music as coloring note stems differently would be for reading score
sheets: there is a standard place they are attached to anyway and there
is no particular reason to look elsewhere.



Highlighting \breve and \longa is useful in my view
because it clarifies that they are not articulations
as their syntax might suggest.

And then there is still the problems that durations
are not recognized from numbers in general. I don't
have a whole lot of time this week; still have to
see if it looks good not to highlight any numbers
at all.




It would be much more useful to highlight note lengths separated by
space but still common to a preceding note or rest, like

\drummode { bd4 r r 4. 8 }

where the 4. is sucked into the second r likely unintentionally.
Highlighting this is helpful.



Then we are not talking about the same use cases
for highlighting. But while this might be helpful
in an editor, I don't see the relevance for
documentation. The goal is to help the reader,
not the documentation writer. Whether the input is
intentional or not -- and it should really be
for documentation --, focusing the reader's
attention on that is inappropriate. Not to mention
that \func a 8 where \func is some builtin or custom
function taking a pitch and a number will start
jumping out at the reader for no good reason.

The goal of my efforts is:

- Helping new users to grasp the syntax,

- Helping intermediately advanced users to understand
  the differences between categories of builtins
  (typically grobs vs. contexts),

- Helping all users to discern the structure
  of examples more easily.

But not to point at editing mistakes.


[snipped]


[Jacques]
I appreciate ‘light coloring’ of code to help locating islands in a 
large code base, here in my doc written with… Knuth’s (La)TeX:



Again there are several uses for highlighting that
don't necessarily agree on the way to do it :-)
The more you try to be helpful for understanding
syntax by making semantic categories (grobs vs.
contexts, music functions vs. markup commands, etc.),
the more the text becomes colored. Which is proving
a problem here because LilyPond documentation examples
are so dense in different constructs that as soon
as you try to convey semantic distinctions, most of
the code becomes colored.



[Peter]
There are various types of colour-blindness - red-green is the most 
common. I did a quick Google on "design for colour-blind" and got 
several useful hits, mostly for web designers. The basic message is 
"don't rely on colour to get a message across", which isn't much help 
to you.


One way round this might be to allow the user to select colours for 
the different distinguishable syntax elements (I think this has 
already been suggested somewhere in this thread). And not to make it 
too complicated. I personally get a bit fed up with Frescobaldi's 
colours but being normally-sighted I can live with it.





By "complicated", do you mean the number of
different colors or the complexity of the
distinctions that it tries to make between
syntactical elements while staying within a
limited pool of colors? I think we are touching
a core point.

Thanks,
Jean

Re: Feedback wanted: syntax highlighting in the LilyPond documentation


On 2022-01-04 1:42 pm, Jean Abou Samra wrote:

https://www.gnu.org/philosophy/javascript-trap.en.html
[ . . . ]
But I'm probably fretting for something that is
very easy in the end.


The code Lilypond's site would use would be entirely homegrown, licensed 
under GPL.  Not sure there is anything here to worry unless we determine 
there is an external dependency that is required.




If we add a toggle for switching highlighting on and
off, then the next question will of course be what
the default should be. Without surprise, I would prefer
if it were on by default, but I wouldn't mind the
other way.


And honestly, I like the default being on, simply because it advertises 
the new feature.  If folks load up the docs and see the familiar black 
and white, they might not know to look for the option to enable 
highlighting.


Perhaps a good strategy would be to initially enable the feature for an 
entire release cycle.  This gets folks using it and providing feedback.  
Most of the discussion so far has been limited in scope so it is hard to 
know if the system works well over the entire manual and for day-to-day 
usage.


I would not be surprised if some creative folks on the list end up 
creating new color schemes to be included as options aside from the 
default.  A dark mode scheme is almost inevitable.




Are you sure about that? This is one page that drew
my attention:

https://law.stackexchange.com/questions/30739/do-the-gdpr-and-cookie-law-regulations-apply-to-localstorage


One of the posts a little further down talks about shopping carts.  The 
way I read this is that when a user is performing an action where 
something being saved is reasonably expected as part of the 
functionality, there is no need to ask permission.  The question we 
would have is whether selecting a color scheme carries an expectation 
that it should persist.



-- Aaron Hill

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

[Aaron]

On 2022-01-04 11:32 am, Jean Abou Samra wrote:

Always best to consult a lawyer on legal matters.

The wife of my cousin is actually a lawyer.
Sadly (but very happily in fact), she gave
birth yesterday, so she will not be in a position
to answer before a while :-)

My layman understanding is that GDPR generally deals with information
that passes through servers that might be retained without offering
some form of end-user control. Use of localStorage, rather than
cookies, should mean no settings ever need to be sent to the server.
Users are entirely in control of this local data, although I suppose
some browsers make it easier to access than others.

For those with privacy or security concerns, the web site source still
remains entirely auditable as everything with styling is done local on
the browser. And the code in question should be so trivial that there
is no need to minify/uglify it, so that preserves readability and
hopefully earns some trust that we are not doing anything shady.

That would also be my expectation, but see below.

Other than that, well, there is still JavaScript.
That's may not be the thing to be most happy about, but
we could check how LibreJS handles that JavaScript,
possibly adding stylized license comments, so that
it would be no problem to those people refusing non-free
JavaScript using LibreJS/IceCat. All in all this approach
does look promising to me.

I think I am not understanding the concerns around licensing.

Me neither :-)

Basically, the root is this:

https://www.gnu.org/philosophy/javascript-trap.en.html

And this gives a bunch of advice for indicating
JavaScript code licenses:

https://www.gnu.org/software/librejs/free-your-javascript.html

Whatever your or my opinion, LilyPond is part of
GNU, so it has to stand with the FSF. Therefore
it is important to keep the website working with
LibreJS.

But I'm probably fretting for something that is
very easy in the end.

At the end of the day, if someone does not want to use JavaScript,
then the functionality will not work. We should make sure the default
behavior of the site is sound for such cases, so no one feels they
have to enable JS if they do not wish. That might mean the standard
styling needs to be black and white if that creates the least friction
for users.

Le 04/01/2022 à 21:31, Wol a écrit :

On 04/01/2022 19:32, Jean Abou Samra wrote:

Forgive my igorance with the inner workings of the
Internet: what does this mean in connection with GDPR
and all that? Am I right that the fact that the
information stored on the user's device serves
a purpose essential to satisfying the very request
of the user means that it would fall under PECR
exceptions to the requirement of a banner asking
for explicit consent of the user? Otherwise, as
far as I can read, the requirement is that you
must ask for permission before storing or using
the data, so this permission could be asked
to the reader just when toggling highlighting
and not for everyone reading the documentation,
right? I'm a bit at loss trying to understand
what is OK or not in this respect.

The fact that it's stored on the user's own device (and the server
never sees it) means that the GDPR is irrelevant.

The GDPR places an onus on you to take appropriate care of OTHER
PEOPLES' information. If you never have that information, then the
GDPR is irrelevant. If you only have that information transiently, for
the purpose of satisfying the user's web session, then I guess you
just need to make sure that it's wiped when the session ends.

The big problem actually is with the webserver itself. If it keeps
logs of people accessing the website, those logs are far more of a
GDPR problem than all this stuff on the web site.

Are you sure about that? This is one page that drew
my attention:

https://law.stackexchange.com/questions/30739/do-the-gdpr-and-cookie-law-regulations-apply-to-localstorage

Emphasis mine:

Member States shall ensure that the **storing of information**, or
the gaining of access to information already stored, in the terminal
equipment of a subscriber or user is only allowed on condition that
the subscriber or user concerned has given his or her consent, having
been provided with clear and comprehensive information, in accordance
with

Directive 95/46/EC, inter alia, about the purposes of the processing.
This shall not prevent any technical storage or access for the sole
purpose of carrying out the transmission of a communication over an
electronic communications network, or as strictly necessary in order
for the provider of an information society service explicitly requested
by the subscriber or user to provide the service.

That is the part I wonder

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

2022-01-04 Thread Wol


On 04/01/2022 19:32, Jean Abou Samra wrote:

Forgive my igorance with the inner workings of the
Internet: what does this mean in connection with GDPR
and all that? Am I right that the fact that the
information stored on the user's device serves
a purpose essential to satisfying the very request
of the user means that it would fall under PECR
exceptions to the requirement of a banner asking
for explicit consent of the user? Otherwise, as
far as I can read, the requirement is that you
must ask for permission before storing or using
the data, so this permission could be asked
to the reader just when toggling highlighting
and not for everyone reading the documentation,
right? I'm a bit at loss trying to understand
what is OK or not in this respect.


The fact that it's stored on the user's own device (and the server never 
sees it) means that the GDPR is irrelevant.


The GDPR places an onus on you to take appropriate care of OTHER 
PEOPLES' information. If you never have that information, then the GDPR 
is irrelevant. If you only have that information transiently, for the 
purpose of satisfying the user's web session, then I guess you just need 
to make sure that it's wiped when the session ends.


The big problem actually is with the webserver itself. If it keeps logs 
of people accessing the website, those logs are far more of a GDPR 
problem than all this stuff on the web site.


Cheers,
Wol

Re: Feedback wanted: syntax highlighting in the LilyPond documentation


On 2022-01-04 11:32 am, Jean Abou Samra wrote:

Forgive my igorance with the inner workings of the
Internet: what does this mean in connection with GDPR
and all that? Am I right that the fact that the
information stored on the user's device serves
a purpose essential to satisfying the very request
of the user means that it would fall under PECR
exceptions to the requirement of a banner asking
for explicit consent of the user?


Always best to consult a lawyer on legal matters.

My layman understanding is that GDPR generally deals with information 
that passes through servers that might be retained without offering some 
form of end-user control.  Use of localStorage, rather than cookies, 
should mean no settings ever need to be sent to the server.  Users are 
entirely in control of this local data, although I suppose some browsers 
make it easier to access than others.


For those with privacy or security concerns, the web site source still 
remains entirely auditable as everything with styling is done local on 
the browser.  And the code in question should be so trivial that there 
is no need to minify/uglify it, so that preserves readability and 
hopefully earns some trust that we are not doing anything shady.




Other than that, well, there is still JavaScript.
That's may not be the thing to be most happy about, but
we could check how LibreJS handles that JavaScript,
possibly adding stylized license comments, so that
it would be no problem to those people refusing non-free
JavaScript using LibreJS/IceCat. All in all this approach
does look promising to me.


I think I am not understanding the concerns around licensing.

At the end of the day, if someone does not want to use JavaScript, then 
the functionality will not work.  We should make sure the default 
behavior of the site is sound for such cases, so no one feels they have 
to enable JS if they do not wish.  That might mean the standard styling 
needs to be black and white if that creates the least friction for 
users.



-- Aaron Hill

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

Hello Jean,

The code Aaron provided is quite nice, but I suggest to rather use a linked 
stylesheet like



And then use JS like
document.getElementById("syntax-highlighting") = "highlighting1.css"

This results in less complicated JS and allows for multiple styles.

Cheers,
Valentin

Am Dienstag, 4. Jänner 2022, 20:32:50 CET schrieb Jean Abou Samra:
> > [Aaron]
> 
> > It is fairly straightforward with CSS and a little JavaScript:
> Yeah, that is also what I was starting to muse with
> more seriously. Thanks for providing ready-made code.
> 
> Forgive my igorance with the inner workings of the
> Internet: what does this mean in connection with GDPR
> and all that? Am I right that the fact that the
> information stored on the user's device serves
> a purpose essential to satisfying the very request
> of the user means that it would fall under PECR
> exceptions to the requirement of a banner asking
> for explicit consent of the user? Otherwise, as
> far as I can read, the requirement is that you
> must ask for permission before storing or using
> the data, so this permission could be asked
> to the reader just when toggling highlighting
> and not for everyone reading the documentation,
> right? I'm a bit at loss trying to understand
> what is OK or not in this respect.
> 
> Other than that, well, there is still JavaScript.
> That's may not be the thing to be most happy about, but
> we could check how LibreJS handles that JavaScript,
> possibly adding stylized license comments, so that
> it would be no problem to those people refusing non-free
> JavaScript using LibreJS/IceCat. All in all this approach
> does look promising to me.
> 
> 
> [Wol]
> 
> > Is that on the web page, or down to the reader?
> 
> On the web page.
> 
> Regards,
> Jean

signature.asc
Description: This is a digitally signed message part.

Re: Feedback wanted: syntax highlighting in the LilyPond documentation


[Aaron]
It is fairly straightforward with CSS and a little JavaScript:


Yeah, that is also what I was starting to muse with
more seriously. Thanks for providing ready-made code.

Forgive my igorance with the inner workings of the
Internet: what does this mean in connection with GDPR
and all that? Am I right that the fact that the
information stored on the user's device serves
a purpose essential to satisfying the very request
of the user means that it would fall under PECR
exceptions to the requirement of a banner asking
for explicit consent of the user? Otherwise, as
far as I can read, the requirement is that you
must ask for permission before storing or using
the data, so this permission could be asked
to the reader just when toggling highlighting
and not for everyone reading the documentation,
right? I'm a bit at loss trying to understand
what is OK or not in this respect.

Other than that, well, there is still JavaScript.
That's may not be the thing to be most happy about, but
we could check how LibreJS handles that JavaScript,
possibly adding stylized license comments, so that
it would be no problem to those people refusing non-free
JavaScript using LibreJS/IceCat. All in all this approach
does look promising to me.


[Wol]

Is that on the web page, or down to the reader?


On the web page.

Regards,
Jean

Re: Feedback wanted: syntax highlighting in the LilyPond documentation


On 2022-01-04 10:04 am, Valentin Petzel wrote:

The problem is that we probably want to
remember the set color scheme for longer than just the current page,
so we'd need something like cookies.


Not a problem in the slightest.  But not cookies... localStorage [1].

[1]: 
https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage



-- Aaron Hill

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

In fact it is sufficient to have multiple stylesheets and load the one you want 
to switch to. The problem is that we probably want to remember the set color 
scheme for longer than just the current page, so we'd need something like 
cookies.

We could also do this without JS by generating multiple versions of the docs 
referencing different stylesheet.

Of course this would kind of blow up the size of the documentation for changing 
a single line.

Sadly the browser functionality for multiple stylesheets usually consists of an 
obscure list hidden in some menu.

In my opinion the best thing would be if the browser did some notification like 
"This page offers multiple styles" along with some selector. But as things are 
we can only do this either dynamically on the server (which we probably do not 
want), dynamically on the client by JS (which we probably don't want) or 
statically by with multiple versions (which would be rather unelegant).

Cheers,
Valentin

04.01.2022 17:23:59 Aaron Hill :

> On 2022-01-04 7:29 am, Erika Pirnes wrote:
>> Would it be terribly difficult to have a color setting on the
>> documentation page, so that people can choose between black and color?
> 
> It is fairly straightforward with CSS and a little JavaScript:
> 
> 
> 
> 
> 
>    
>    
>    
>    Dynamic styles
>    
>  body { font-size: 36pt; }
>  .button {
>    background: #999; border-radius: 9pt;
>    cursor: pointer; display: inline-block;
>    padding: 9pt; user-select: none;
>  }
>  .colors > code > .type { color: purple; }
>  .colors > code > .identifier { color: blue; }
>  .colors > code > .keyword { color: brown; }
>  .colors > code > .number { color: darkgoldenrod; }
>  .colors > code > .string { color: green; }
>  .colors > code > .punctuation { color: gray; }
>    
> 
> 
>    
>  function toggleColors() {
>    if (document.body.classList.contains('colors')) {
>  document.body.classList.remove('colors');
>    } else {
>  document.body.classList.add('colors');
>    }
>  }
>    
>    Toggle Colors
> 
>    
>  int
>  main() 
> {
>  printf class="punctuation">("Hello, 
> World!\n");
>  return
>  0;
>  }
>    
> 
> 
> 
> 
> -- Aaron Hill

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

2022-01-04 Thread Wols Lists


On 04/01/2022 16:23, Aaron Hill wrote:

On 2022-01-04 7:29 am, Erika Pirnes wrote:

Would it be terribly difficult to have a color setting on the
documentation page, so that people can choose between black and color?


It is fairly straightforward with CSS and a little JavaScript:


Is that on the web page, or down to the reader?

I'm only just getting into Google Sheets and GoogleScript so calling it 
"fairly straightforward" is something I'd disagree with if I'm expected 
to do it. Not for somebody who has had no reason to go near 
js/gs/whatever before...


Cheers,
Wol

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

2022-01-04 Thread Wols Lists


On 04/01/2022 15:14, J Martin Rushton wrote:

OK, I'll admit I only skimmed it, hence "I've saved the paper to read
later"!  I've got Doob's "A Gentle Introduction to TeX" and Oetiker's
"The Not So Short Introduction to LaTeX2e" both of which keep to the
fixed width convention.  Again, I'll be honest, I rarely use them since
I've retired though.


Reading through this, I'd just like to say I think we're confusing two 
things. Iirc someone said "Courier is a crap font" and the discussion 
rapidly veered off into fixed width.


While I have no real comment to make about Courier, and I think there 
are much better fonts out there, I do think we should keep fixed-width 
for code. Just look for a better font :-)


Cheers,
Wol

Re: Feedback wanted: syntax highlighting in the LilyPond documentation


On 2022-01-04 7:29 am, Erika Pirnes wrote:

Would it be terribly difficult to have a color setting on the
documentation page, so that people can choose between black and color?


It is fairly straightforward with CSS and a little JavaScript:





  
  
  
  Dynamic styles
  
body { font-size: 36pt; }
.button {
  background: #999; border-radius: 9pt;
  cursor: pointer; display: inline-block;
  padding: 9pt; user-select: none;
}
.colors > code > .type { color: purple; }
.colors > code > .identifier { color: blue; }
.colors > code > .keyword { color: brown; }
.colors > code > .number { color: darkgoldenrod; }
.colors > code > .string { color: green; }
.colors > code > .punctuation { color: gray; }
  


  
function toggleColors() {
  if (document.body.classList.contains('colors')) {
document.body.classList.remove('colors');
  } else {
document.body.classList.add('colors');
  }
}
  
  Toggle Colors

  
int
main() 
{
printfclass="punctuation">("Hello, 
World!\n");

return
0;
}
  




-- Aaron Hill

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

2022-01-04 Thread Erika Pirnes

I personally find the black text much easier to read than the syntax-highlighed 
one in colors. I still have young eyes, but somehow the colored text feels 
tiring. Maybe this is just what I am used to, as I am still using the standard 
text editor to write my .ly files. Would it be terribly difficult to have a 
color setting on the documentation page, so that people can choose between 
black and color?

Erika

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

2022-01-04 Thread J Martin Rushton

OK, I'll admit I only skimmed it, hence "I've saved the paper to read
later"!  I've got Doob's "A Gentle Introduction to TeX" and Oetiker's
"The Not So Short Introduction to LaTeX2e" both of which keep to the
fixed width convention.  Again, I'll be honest, I rarely use them since
I've retired though.

On Tue, 2022-01-04 at 15:48 +0100, David Kastrup wrote:
> J Martin Rushton  writes:
> 
> > Interesting Aaron, but I do note that the paper is from 1983 and
> > didn't
> > catch on.  I wonder if there is a reason for that?  I've saved the
> > paper to read later.  Personally I don't know of a single language
> > that
> > is happy with word processor output as source code, but then I may
> > be
> > proved wrong.  Knuth seems to be addressing issues that have been
> > effectively bypassed by the rise of object orientated code.  I was
> > trained in a macro assembler (VAX-Macro) and am well aware of their
> > advantage for repeated idioms, but if they are just another layer
> > on
> > the top they can merely double the size of the language to master.
> > 
> > In passing, although Knuth uses variable width fonts in the first
> > six
> > pages, I note that as soon as he starts to give firm code on page 7
> > onwards he uses fixed width!
> 
> Uh, you are talking about "D. HOW THE EXAMPLE WAS SPECIFIED" which
> displays the macros used for typesetting the Literate Programming
> example.
> 
> That's sort of like complaining that someone lauding some computer
> language bootstraps his compiler from a different system.
> 
> Knuth has written both TeX and METAFONT entirely in his WEB
> programming
> system for Literate Programming.  I have the printed book for TeX.
> 
> > On Tue, 2022-01-04 at 05:10 -0800, Aaron Hill wrote:
> > > On 2022-01-04 4:19 am, J Martin Rushton wrote:
> > > > Sorry to disagree, but fixed pitch is _so_ much easier to lay
> > > > out
> > > > in an
> > > > editor.  Documentation flows nicely with variable pitch and
> > > > fancy
> > > > hidden formats, but for code (and Lily's input is a programming
> > > > language) you just want the plain line-by-line ASCII.  It is,
> > > > as
> > > > you
> > > > say, industry standard; and that is for a good reason.
> > > 
> > > As a counterpoint, Knuth's work with literate programming [1]
> > > showed
> > > it 
> > > was possible to have typographically beautiful setting of code
> > > for
> > > use 
> > > in print.  His style largely used proportional fonts though some 
> > > elements were still rendered in fixed width to provide useful
> > > contrast.  
> > > While Knuth's approach is not perfect for every language, I argue
> > > the 
> > > vast majority of programming books out there really should have
> > > followed 
> > > suit.  Editors (the people, not programs) seem to struggle with 
> > > fixed-width typefaces, and typos were abundant.
> > > 
> > > Going beyond printed documentation, some IDEs like Source
> > > Insight 
> > > enabled and encouraged programmers to use proportional fonts,
> > > where 
> > > horizontal alignment was something handled by the system not the 
> > > programmer.  Though I do concede this was probably a novelty,
> > > seeing
> > > as 
> > > these days terminals and editors still rely on fixed pitch.
> > > 
> > > [1]: http://www.literateprogramming.com/knuthweb.pdf
> > > 
> > > 
> > > -- Aaron Hill
-- 
J Martin Rushton MBCS

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

2022-01-04 Thread David Kastrup

J Martin Rushton  writes:

> Interesting Aaron, but I do note that the paper is from 1983 and didn't
> catch on.  I wonder if there is a reason for that?  I've saved the
> paper to read later.  Personally I don't know of a single language that
> is happy with word processor output as source code, but then I may be
> proved wrong.  Knuth seems to be addressing issues that have been
> effectively bypassed by the rise of object orientated code.  I was
> trained in a macro assembler (VAX-Macro) and am well aware of their
> advantage for repeated idioms, but if they are just another layer on
> the top they can merely double the size of the language to master.
>
> In passing, although Knuth uses variable width fonts in the first six
> pages, I note that as soon as he starts to give firm code on page 7
> onwards he uses fixed width!

Uh, you are talking about "D. HOW THE EXAMPLE WAS SPECIFIED" which
displays the macros used for typesetting the Literate Programming
example.

That's sort of like complaining that someone lauding some computer
language bootstraps his compiler from a different system.

Knuth has written both TeX and METAFONT entirely in his WEB programming
system for Literate Programming.  I have the printed book for TeX.

>
> On Tue, 2022-01-04 at 05:10 -0800, Aaron Hill wrote:
>> On 2022-01-04 4:19 am, J Martin Rushton wrote:
>> > Sorry to disagree, but fixed pitch is _so_ much easier to lay out
>> > in an
>> > editor.  Documentation flows nicely with variable pitch and fancy
>> > hidden formats, but for code (and Lily's input is a programming
>> > language) you just want the plain line-by-line ASCII.  It is, as
>> > you
>> > say, industry standard; and that is for a good reason.
>> 
>> As a counterpoint, Knuth's work with literate programming [1] showed
>> it 
>> was possible to have typographically beautiful setting of code for
>> use 
>> in print.  His style largely used proportional fonts though some 
>> elements were still rendered in fixed width to provide useful
>> contrast.  
>> While Knuth's approach is not perfect for every language, I argue
>> the 
>> vast majority of programming books out there really should have
>> followed 
>> suit.  Editors (the people, not programs) seem to struggle with 
>> fixed-width typefaces, and typos were abundant.
>> 
>> Going beyond printed documentation, some IDEs like Source Insight 
>> enabled and encouraged programmers to use proportional fonts, where 
>> horizontal alignment was something handled by the system not the 
>> programmer.  Though I do concede this was probably a novelty, seeing
>> as 
>> these days terminals and editors still rely on fixed pitch.
>> 
>> [1]: http://www.literateprogramming.com/knuthweb.pdf
>> 
>> 
>> -- Aaron Hill

-- 
David Kastrup

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

Hello Robin,

as far as I know the Lilypond Documentation does not specify the font to be 
used for this. So the system defaults to a standard monospace font.

So the font will depend on the system. We could ship a dedicated font with the 
documentation, but I'm not sure if we want that.

Cheers,
Valentin

04.01.2022 13:01:47 Robin Bannister :

> 
> 'Hear hear' to these recent posts from Thomas, Paul and the two Davids!
> 
> I don't object to the fixed width, but the code font has always been spindly 
> compared to the rest of the documentation text.  I find this makes it harder 
> to read anyway.
> 
> The stroke width I see is 1px (Firefox at 100%).  This makes the stroke 
> dominated by edge effects; the surrounding white dilutes its colour.
> Do the WCAG recommendations recognise this?  If not, please don't apply their 
> levels to this case.
> 
> 
> The demo shows me text that is slightly discoloured.  The differences in 
> colour are so vague that they require attention.  Attention to the 
> differences detracts from attention to the colours.  I don't get as far as 
> judging if attention to the colours aids attention to the text.
> 
> 
> Cheers,
> Robin

Re: Feedback wanted: syntax highlighting in the LilyPond documentation

2022-01-04 Thread J Martin Rushton

Interesting Aaron, but I do note that the paper is from 1983 and didn't
catch on.  I wonder if there is a reason for that?  I've saved the
paper to read later.  Personally I don't know of a single language that
is happy with word processor output as source code, but then I may be
proved wrong.  Knuth seems to be addressing issues that have been
effectively bypassed by the rise of object orientated code.  I was
trained in a macro assembler (VAX-Macro) and am well aware of their
advantage for repeated idioms, but if they are just another layer on
the top they can merely double the size of the language to master.

In passing, although Knuth uses variable width fonts in the first six
pages, I note that as soon as he starts to give firm code on page 7
onwards he uses fixed width!

On Tue, 2022-01-04 at 05:10 -0800, Aaron Hill wrote:
> On 2022-01-04 4:19 am, J Martin Rushton wrote:
> > Sorry to disagree, but fixed pitch is _so_ much easier to lay out
> > in an
> > editor.  Documentation flows nicely with variable pitch and fancy
> > hidden formats, but for code (and Lily's input is a programming
> > language) you just want the plain line-by-line ASCII.  It is, as
> > you
> > say, industry standard; and that is for a good reason.
> 
> As a counterpoint, Knuth's work with literate programming [1] showed
> it 
> was possible to have typographically beautiful setting of code for
> use 
> in print.  His style largely used proportional fonts though some 
> elements were still rendered in fixed width to provide useful
> contrast.  
> While Knuth's approach is not perfect for every language, I argue
> the 
> vast majority of programming books out there really should have
> followed 
> suit.  Editors (the people, not programs) seem to struggle with 
> fixed-width typefaces, and typos were abundant.
> 
> Going beyond printed documentation, some IDEs like Source Insight 
> enabled and encouraged programmers to use proportional fonts, where 
> horizontal alignment was something handled by the system not the 
> programmer.  Though I do concede this was probably a novelty, seeing
> as 
> these days terminals and editors still rely on fixed pitch.
> 
> [1]: http://www.literateprogramming.com/knuthweb.pdf
> 
> 
> -- Aaron Hill
-- 
J Martin Rushton MBCS

Re: Feedback wanted: syntax highlighting in the LilyPond documentation