Re: Bug: Repeated chords (via "q") are not rendered when using ly:book-process.
>> In contrast to Jean, I have a different point of view. I think it
>> would be *very* valuable to have documentation strings of *all*
>> functions that might be useful in the long run
>
> Oh, that's also my point of view — it *would* be very valuable.
> Just... IMO not realistic. It already took me weeks to write the
> extending-lilypond guide (not counting the effort to understand the
> code base in the first place). "rg '```\{func\}' | wc -l" tells me
> that currently 76 functions are documented in the guide, so the
> multiplier to get more usable documentation for all functions that
> are already documented is already ~10, and there are the
> undocumented ones also.
I'm very grateful for your work (and I should eventually have a closer
look whether some of the documentation can be ported to the IR)!
However, you probably did a systematic approach to the functions as
needed for the guide – this is something I don't suggest here.
Instead, I plead that interested users who stumble upon insufficient
documentation should be encouraged to provide patches *for whatever
they are interested in*. No need for being thorough; even the
smallest breadcrumbs are potentially useful for all users.
Werner
Re: Bug: Repeated chords (via "q") are not rendered when using ly:book-process.
> In contrast to Jean, I have a different point of view. I think it
> would be *very* valuable to have documentation strings of *all*
> functions that might be useful in the long run
Oh, that's also my point of view — it *would* be very valuable.
Just... IMO not realistic. It already took me weeks to write
the extending-lilypond guide (not counting the effort to understand
the code base in the first place). "rg '```\{func\}' | wc -l" tells
me that currently 76 functions are documented in the guide, so the
multiplier to get more usable documentation for all functions that
are already documented is already ~10, and there are the undocumented
ones also.
signature.asc
Description: This is a digitally signed message part
Re: Bug: Repeated chords (via "q") are not rendered when using ly:book-process.
> The naming of lilypond scheme functions can be really unintuitive > sometimes. At the very least, the internals reference could use > some major extensions making clear what the functions do and how, > with examples. Via [1], it would have been impossible for me to > understand what scorify-music does or that I need this function over > ly:make-score. Am I missing some other place where this is already > documented in more detail? In contrast to Jean, I have a different point of view. I think it would be *very* valuable to have documentation strings of *all* functions that might be useful in the long run (of course, it is debatable which functions these are exactly). A lot of code is written in Guile and C++, which is sometimes very hard to read for non-C++ programmers. So... > If not, I'd be happy to start investing my time to contribute to the > Internals reference documentation, especially Section 4 "Scheme > functions". In addition to better explanatory texts this section > could benefit from more crosslinks and examples - or maybe the > examples should be in a different (new) section to keep this > reference concise. I'd be happy to discuss this further. ... I'm very grateful for your offer. > As a start, here are my suggestions for the two functions in > question: [...] Thanks, see https://gitlab.com/lilypond/lilypond/-/merge_requests/2294 > If someone else is already working improving this Section, you may > let me know - I'd love to join in. You will be mostly a lone fighter, sorry :-| > Otherwise, as my understanding of the internals is still > fragmentary, I'd need some help getting things right. I could just > continue to send improvement suggestions as mentioned in [2] to this > mailinglist (or lilypond-devel?) and someone corrects me if I get > things wrong? Or is someone willing to "proofread" some suggestions > of mine in advance so I do not add too much noise to the > mailinglists? I could also give larger-scale structural improvement > suggestion as a start for debate if you would consider this > appropriate from a "newbie" to the mailinglists. I think the best way to contribute is to get an account on GitLab, clone the 'lilypond' git repository and submit Merging Requests, closely following the formatting of other documentation strings. All documentation that goes into the IR uses Texinfo syntax. And yes, larger-scale stuff should be discussed first on 'lilypond-devel'. Werner
Re: Bug: Repeated chords (via "q") are not rendered when using ly:book-process.
> Thank you so much, that did the trick. > > The naming of lilypond scheme functions can be really unintuitive > sometimes. At the very least, the internals reference could use > some major extensions making clear what the functions do and how, > with examples. Via [1], it would have been impossible for me to > understand what scorify-music does or that I need this function > over ly:make-score. Am I missing some other place where this is > already documented in more detail? > > If not, I'd be happy to start investing my time to contribute to > the Internals reference documentation, especially Section 4 "Scheme > functions". In addition to better explanatory texts this section > could benefit from more crosslinks and examples - or maybe the > examples should be in a different (new) section to keep this > reference concise. I'd be happy to discuss this further. Not that improvements like this are not welcome, but if you want my honest opinion, documenting public functions to the degree that one could use them just from the manual is a lost cause. There are way too many of them (740 functions in the current Internals Reference, but many more exist which are undocumented). I think we just have to accept that, these functions being largely the deep guts of LilyPond exposed for anyone to use, you have to be a bit familiar with the source code in order to use them correctly. I think the best we can do is high-level extending documentation — like what I've tried to do in https://extending-lilypond.gitlab.io — supplemented by a dose of "read the source code" for advanced usage. Note that I didn't know about scorify-music before you sent this bug report. I just knew that chord repeats are expanded by a music function in toplevel-music-functions, and I did a bit of grepping in order to find the call site. Best, Jean signature.asc Description: This is a digitally signed message part
Re: Bug: Repeated chords (via "q") are not rendered when using ly:book-process.
On Saturday, March 30th, 2024 at 18:01, Jean Abou Samra
wrote:
> Le samedi 30 mars 2024 à 16:47 +, Lovis B. Suchmann a écrit :
>
> > \version "2.24.3"
> >
> > % Repeated chords (via "q") are not rendered when using ly:book-process.
> >
> > test = { r4 r q | }
> >
> > \book { \score { \test \layout {} } }
> >
> > #(ly:book-process (ly:make-book $defaultpaper
> > #f
> > (ly:make-score test))
> > $defaultpaper
> > $defaultlayout
> > (string-append (ly:parser-output-name) "-1"))
>
>
>
>
> This isn't a bug. You probably want to use scorify-music instead of
> the low-level function ly:make-score.
Thank you so much, that did the trick.
The naming of lilypond scheme functions can be really unintuitive sometimes. At
the very least, the internals reference could use some major extensions making
clear what the functions do and how, with examples. Via [1], it would have been
impossible for me to understand what scorify-music does or that I need this
function over ly:make-score. Am I missing some other place where this is
already documented in more detail?
If not, I'd be happy to start investing my time to contribute to the Internals
reference documentation, especially Section 4 "Scheme functions". In addition
to better explanatory texts this section could benefit from more crosslinks and
examples - or maybe the examples should be in a different (new) section to keep
this reference concise. I'd be happy to discuss this further.
As a start, here are my suggestions for the two functions in question:
- - - - -
A) In Internals, Section 4 "Scheme functions", change the explanation text for
"scorify-music" as follows:
Preprocess _music_ and encapsulate it into a score smob.
Among other things, preprocessing replaces chord repetitions via `q` with the
correct actual chords.
B) In Internals, Section 4 "Scheme functions", change the explanation text for
"ly:make-score" as follows:
Encapsulate _music_ into a score smob.
Note: This is a low-level function that does not preprocess _music_ in any way.
You might be looking for `scorify-music` instead, which also preprocesses
_music_.
- - - - -
If someone else is already working improving this Section, you may let me know
- I'd love to join in. Otherwise, as my understanding of the internals is still
fragmentary, I'd need some help getting things right. I could just continue to
send improvement suggestions as mentioned in [2] to this mailinglist (or
lilypond-devel?) and someone corrects me if I get things wrong? Or is someone
willing to "proofread" some suggestions of mine in advance so I do not add too
much noise to the mailinglists? I could also give larger-scale structural
improvement suggestion as a start for debate if you would consider this
appropriate from a "newbie" to the mailinglists.
I'd be thankful for any pointers on the best way to keep contributing to this
part of the documentation and help this amazing project (which I have been
using for many years!) become even better.
Cheers!
Lovis
[1] https://lilypond.org/doc/v2.24/Documentation/internals/scheme-functions
[2]
https://lilypond.org/doc/v2.24/Documentation/contributor/documentation-suggestions
Re: Bug: Repeated chords (via "q") are not rendered when using ly:book-process.
Le samedi 30 mars 2024 à 16:47 +, Lovis B. Suchmann a écrit :
> \version "2.24.3"
>
> % Repeated chords (via "q") are not rendered when using ly:book-process.
>
> test = { r4 r q | }
>
> \book { \score { \test \layout {} } }
>
> #(ly:book-process (ly:make-book $defaultpaper
> #f
> (ly:make-score test))
> $defaultpaper
> $defaultlayout
> (string-append (ly:parser-output-name) "-1"))
This isn't a bug. You probably want to use scorify-music instead of
the low-level function ly:make-score.
signature.asc
Description: This is a digitally signed message part
Bug: Repeated chords (via "q") are not rendered when using ly:book-process.
\version "2.24.3"
% Repeated chords (via "q") are not rendered when using ly:book-process.
test = { r4 r q | }
\book { \score { \test \layout {} } }
#(ly:book-process (ly:make-book $defaultpaper
#f
(ly:make-score test))
$defaultpaper
$defaultlayout
(string-append (ly:parser-output-name) "-1"))
Sent with [Proton Mail](https://proton.me/) secure email.
