Re: Doc-string with newline character

[David Kastrup]

Thomas Morley  writes:

> Am Fr., 1. Jan. 2021 um 20:07 Uhr schrieb David Kastrup :
>>
>> Thomas Morley  writes:
>>
>> > rtfm tends to help ;)
>> > Alas, I've no good idea how a `texi-quote` could work. Iiuc, one needs
>> > more than a simple search/replace.
>>
>> Just put a @ in front of every @, {, or } ?
>>
>> --
>> David Kastrup
>
> David, I don't understand what the proposed texi-quote should do.
>
> A tool to
> - improve incorrect doc-strings?

A tool to add the necessary @ characters to make computer-generated
output (like default values) that happens to contain @ { and }
characters actually print those characters in Texinfo passages rather
than make Texinfo bomb out.

> - format a doc-string with respect to texinfo?

No, just add quote characters to computer-generated parts of the output.
You would not pass any stuff already formatted for Texinfo through
texi-quote.  Only stuff _not_ yet prepared to be passed into Texinfo.

> - format/improve only those parts of a doc-string, which are already
> wrapped in texinfo-code?

No, it would not analyse anything.  It would only change @ { } to @@ @{
and @}.  That's all.

In this case, you'd change something like
(format #f "~s" default-value) to (format #f "~a"
(texi-quote (format #f "~s" default-value)))

So that if default-value is a string that contains @ { } characters, it
will print properly.

> - do something else?
>
> Anyway, I've no clue how to do any of it.

-- 
David Kastrup

Re: Doc-string with newline character

[Thomas Morley]

Am Fr., 1. Jan. 2021 um 20:07 Uhr schrieb David Kastrup :
>
> Thomas Morley  writes:
>
> > rtfm tends to help ;)
> > Alas, I've no good idea how a `texi-quote` could work. Iiuc, one needs
> > more than a simple search/replace.
>
> Just put a @ in front of every @, {, or } ?
>
> --
> David Kastrup

David, I don't understand what the proposed texi-quote should do.

A tool to
- improve incorrect doc-strings?
- format a doc-string with respect to texinfo?
- format/improve only those parts of a doc-string, which are already
wrapped in texinfo-code?
- do something else?

Anyway, I've no clue how to do any of it.

Cheers,
  Harm

Re: state of the ’Pond for earnest tadpoles

[Kieren MacMillan]

Hi Michael (et al.),

> please use http://lilypond.org/doc/v2.21/Documentation/contributor/lilydev
> instead. I adjusted some parts of this section last year. However, I
> would be happy to hear if something remains still unclear.

This is great. Thanks.

I have now compiled Lilypond on my machine! Took ~10 minutes (though I was 
doing a lot of other processor-intensive things at the same time, didn’t 
minimize the terminal window, etc., so I expect that can be reduced). Despite 
multiple attempts in the past, this is the first time I’ve ever been able to do 
that — thanks to all for the help to this point.

The only suggestion I would have is to maybe mention that the initial build 
outputs *some* documentation. When I started seeing “Making Documentation/out” 
in the terminal output, I started to worry that I had somehow triggered the 
documentation build which would apparently take multiple hours.  =)

More soon!
Kieren.


Kieren MacMillan, composer (he/him/his)
‣ website: www.kierenmacmillan.info
‣ email: kie...@kierenmacmillan.info

Re: state of the ’Pond for earnest tadpoles

[Michael Käppler]

Hi Kieren,

Hi Jonas (et al.),


I would claim that the contributor experience has been pretty stable
since the initial switch to GitLab. Enabling CI and the recent work to
also run 'make check' automatically shouldn't change much from a
contributor's point of view, I hope.
I can't promise to give detailed guidance, the procedures should be
described in unstable's CG, but if there's anything unclear or even
wrong I'm more than happy to help you and of course fix the docs.

So here’s what I’ve done, as per 
:

please use http://lilypond.org/doc/v2.21/Documentation/contributor/lilydev
instead. I adjusted some parts of this section last year. However, I
would be happy to hear
if something remains still unclear.

Cheers,
Michael



1. Download & install VirtualBox. No problem!

2. Download LilyDev 2 from . Um… 
There’s only one file that seems like it’s the downloadable one (LilyDev-2-debian-vm.zip), and 
it’s not named as per the docs ("lilydev-vm-fedora-VERSION"). Is that a doc problem, 
or am I being daft?

3. Unzip the downloaded file. It becomes a folder containing an .img file. Okay… except 
the docs claim it should be a "raw" file. So do I try to convert that to VDI?

Note: I’m on Mac OS High Sierra (10.13.6).

Thanks,
Kieren.


Kieren MacMillan, composer (he/him/his)
‣ website: www.kierenmacmillan.info
‣ email: kie...@kierenmacmillan.info

Re: state of the ’Pond for earnest tadpoles

[Federico Bruni]

Il giorno ven, gen 1 2021 at 16:37:40 -0500, Kieren MacMillan 
 ha scritto:

Hi Jonas (et al.),


 I would claim that the contributor experience has been pretty stable
 since the initial switch to GitLab. Enabling CI and the recent work 
to

 also run 'make check' automatically shouldn't change much from a
 contributor's point of view, I hope.
 I can't promise to give detailed guidance, the procedures should be
 described in unstable's CG, but if there's anything unclear or even
 wrong I'm more than happy to help you and of course fix the docs.


So here’s what I’ve done, as per 
:


1. Download & install VirtualBox. No problem!

2. Download LilyDev 2 from 
. Um… 
There’s only one file that seems like it’s the downloadable one 
(LilyDev-2-debian-vm.zip), and it’s not named as per the docs 
("lilydev-vm-fedora-VERSION"). Is that a doc problem, or am I being 
daft?


3. Unzip the downloaded file. It becomes a folder containing an .img 
file. Okay… except the docs claim it should be a "raw" file. So do 
I try to convert that to VDI?


Note: I’m on Mac OS High Sierra (10.13.6).



Hi Kieren

Sorry, it's my fault: I've been busy in other stuff and I forgot 
LilyDev.

I'll try to make a new release soon.

The command to convert to VDI is here:
https://github.com/fedelibre/LilyDev/tree/master/mkosi

Re: state of the ’Pond for earnest tadpoles

[Kieren MacMillan]

Hi Jonas (et al.),

> I would claim that the contributor experience has been pretty stable
> since the initial switch to GitLab. Enabling CI and the recent work to
> also run 'make check' automatically shouldn't change much from a
> contributor's point of view, I hope.
> I can't promise to give detailed guidance, the procedures should be
> described in unstable's CG, but if there's anything unclear or even
> wrong I'm more than happy to help you and of course fix the docs.

So here’s what I’ve done, as per 
:

1. Download & install VirtualBox. No problem!

2. Download LilyDev 2 from 
. Um… There’s only one 
file that seems like it’s the downloadable one (LilyDev-2-debian-vm.zip), and 
it’s not named as per the docs ("lilydev-vm-fedora-VERSION"). Is that a doc 
problem, or am I being daft?

3. Unzip the downloaded file. It becomes a folder containing an .img file. 
Okay… except the docs claim it should be a "raw" file. So do I try to convert 
that to VDI?

Note: I’m on Mac OS High Sierra (10.13.6).

Thanks,
Kieren.


Kieren MacMillan, composer (he/him/his)
‣ website: www.kierenmacmillan.info
‣ email: kie...@kierenmacmillan.info

Re: Doc-string with newline character

[David Kastrup]

Thomas Morley  writes:

> rtfm tends to help ;)
> Alas, I've no good idea how a `texi-quote` could work. Iiuc, one needs
> more than a simple search/replace.

Just put a @ in front of every @, {, or } ?

-- 
David Kastrup

Re: Doc-string with newline character

[Thomas Morley]

Am Fr., 1. Jan. 2021 um 14:06 Uhr schrieb David Kastrup :
>
> Thomas Morley  writes:
>
> > Am Do., 31. Dez. 2020 um 21:04 Uhr schrieb David Kastrup :
> >>
> >> Come to think of it: on top of using ~s here, wouldn't it also be
> >> necessary to quote characters @ { } by preceding them with @ ?
> >
> > My knowledge of texinfo is rudimentary.
> > After a quick glance over doc-strings from our source it seems @{ and
> > @} are only used _inside_ of @code{ ... }.
> > @@ only once and as (@@ module-name binding-name), i.e. no texinfo.
> >
> > This makes me think it is not needed to add @ to { and } outside of
> > @code{ ... }.
> > I may be wrong, though.
> >
> > 5.4.6 Syntax survey -> Special characters
> > http://lilypond.org/doc/v2.21/Documentation/contributor/syntax-survey#special-characters
> > is not specific in this regard, though.
> >
> > Anyway, in `doc-markup-function-properties` from
> > scm/document-markup.scm only the property-names are set into @code{
> > ... }
> > Those or all either symbols or procedures. If my above assumption is
> > correct, then we're fine there.
> >
> >> Maybe scm/documentation-lib.scm should contain a function for that?  
> >> Something
> >> like texi-quote or so?
> >
> > You mean something like `ps-quote` from scm/framework-ps.scm?
> >
> > Cheers,
> >   Harm
> >
>
> File: texinfo.info,  Node: Special Characters,  Next: Inserting Quote 
> Characters,  Up: Insertions
>
> 12.1 Special Characters: Inserting @ {} , \ # &
> ===
>
> '@' and curly braces are the basic special characters in Texinfo.  To
> insert these characters so they appear in text, you must put an '@' in
> front of these characters to prevent Texinfo from misinterpreting them.
> Alphabetic commands are also provided.
>
>The other characters (comma, backslash, hash, ampersand) are special
> only in restricted contexts, as explained in the respective sections.
>
> * Menu:
>
> * Inserting an Atsign:: '@@', '@atchar{}'.
> * Inserting Braces::'@{ @}', '@l rbracechar{}'.
> * Inserting a Comma::   , and '@comma{}'.
> * Inserting a Backslash::   \ and '@backslashchar{}'.
> * Inserting a Hashsign::# and '@hashchar{}'.
> * Inserting an Ampersand::  & and '@ampchar{}'.
>
>
>
> File: texinfo.info,  Node: Inserting an Atsign,  Next: Inserting Braces,  Up: 
> Special Characters
>
> 12.1.1 Inserting '@' with '@@' and '@atchar{}'
> --
>
> '@@' produces a single '@' character in the output.  Do not put braces
> after an '@@' command.
>
>'@atchar{}' also produces a single '@' character in the output.  It
> does need following braces, as usual for alphabetic commands.  In inline
> conditionals (*note Inline Conditionals::), it can be necessary to avoid
> using the literal '@' character in the source (and may be clearer in
> other contexts).
>
>
> File: texinfo.info,  Node: Inserting Braces,  Next: Inserting a Comma,  Prev: 
> Inserting an Atsign,  Up: Special Characters
>
>
> 12.1.2 Inserting '{ '}' with '@{ @}' and '@l rbracechar{}'
> --
>
> '@{' produces a single '{' in the output, and '@}' produces a single
> '}'.  Do not put braces after either an '@{' or an '@}' command.
>
>'@lbracechar{}' and '@rbracechar{}' also produce single '{' and '}'
> characters in the output.  They do need following braces, as usual for
> alphabetic commands.  In inline conditionals (*note Inline
> Conditionals::), it can be necessary to avoid using literal brace
> characters in the source (and may be clearer in other contexts).
>
>
>
> --
> David Kastrup

rtfm tends to help ;)
Alas, I've no good idea how a `texi-quote` could work. Iiuc, one needs
more than a simple search/replace.


Cheers,
  Harm

Re: Doc-string with newline character

[David Kastrup]

Thomas Morley  writes:

> Am Do., 31. Dez. 2020 um 21:04 Uhr schrieb David Kastrup :
>>
>> Come to think of it: on top of using ~s here, wouldn't it also be
>> necessary to quote characters @ { } by preceding them with @ ?
>
> My knowledge of texinfo is rudimentary.
> After a quick glance over doc-strings from our source it seems @{ and
> @} are only used _inside_ of @code{ ... }.
> @@ only once and as (@@ module-name binding-name), i.e. no texinfo.
>
> This makes me think it is not needed to add @ to { and } outside of
> @code{ ... }.
> I may be wrong, though.
>
> 5.4.6 Syntax survey -> Special characters
> http://lilypond.org/doc/v2.21/Documentation/contributor/syntax-survey#special-characters
> is not specific in this regard, though.
>
> Anyway, in `doc-markup-function-properties` from
> scm/document-markup.scm only the property-names are set into @code{
> ... }
> Those or all either symbols or procedures. If my above assumption is
> correct, then we're fine there.
>
>> Maybe scm/documentation-lib.scm should contain a function for that?  
>> Something
>> like texi-quote or so?
>
> You mean something like `ps-quote` from scm/framework-ps.scm?
>
> Cheers,
>   Harm
>

File: texinfo.info,  Node: Special Characters,  Next: Inserting Quote 
Characters,  Up: Insertions

12.1 Special Characters: Inserting @ {} , \ # &
===

'@' and curly braces are the basic special characters in Texinfo.  To
insert these characters so they appear in text, you must put an '@' in
front of these characters to prevent Texinfo from misinterpreting them.
Alphabetic commands are also provided.

   The other characters (comma, backslash, hash, ampersand) are special
only in restricted contexts, as explained in the respective sections.

* Menu:

* Inserting an Atsign:: '@@', '@atchar{}'.
* Inserting Braces::'@{ @}', '@l rbracechar{}'.
* Inserting a Comma::   , and '@comma{}'.
* Inserting a Backslash::   \ and '@backslashchar{}'.
* Inserting a Hashsign::# and '@hashchar{}'.
* Inserting an Ampersand::  & and '@ampchar{}'.



File: texinfo.info,  Node: Inserting an Atsign,  Next: Inserting Braces,  Up: 
Special Characters

12.1.1 Inserting '@' with '@@' and '@atchar{}'
--

'@@' produces a single '@' character in the output.  Do not put braces
after an '@@' command.

   '@atchar{}' also produces a single '@' character in the output.  It
does need following braces, as usual for alphabetic commands.  In inline
conditionals (*note Inline Conditionals::), it can be necessary to avoid
using the literal '@' character in the source (and may be clearer in
other contexts).


File: texinfo.info,  Node: Inserting Braces,  Next: Inserting a Comma,  Prev: 
Inserting an Atsign,  Up: Special Characters


12.1.2 Inserting '{ '}' with '@{ @}' and '@l rbracechar{}'
--

'@{' produces a single '{' in the output, and '@}' produces a single
'}'.  Do not put braces after either an '@{' or an '@}' command.

   '@lbracechar{}' and '@rbracechar{}' also produce single '{' and '}'
characters in the output.  They do need following braces, as usual for
alphabetic commands.  In inline conditionals (*note Inline
Conditionals::), it can be necessary to avoid using literal brace
characters in the source (and may be clearer in other contexts).



-- 
David Kastrup

PATCHES - Countdown for January 1st.

[James]

Hello and Happy New Year to everyone!

  


Here is the current
patch countdown list. The next countdown will be on January
3rd.

  
A list of all merge requests can be found here:
https://gitlab.com/lilypond/lilypond/-/merge_requests?sort=label_priority

 Push:
!566 Engraver/Performer: remove unused code and virtuality - Dan Eble
https://gitlab.com/lilypond/lilypond/-/merge_requests/566
!565 Encoding fixes for Guile 2.x - Jonas Hahnfeld
https://gitlab.com/lilypond/lilypond/-/merge_requests/565
!564 Auto_beam_engraver: clean up the use of whichBar - Dan Eble
https://gitlab.com/lilypond/lilypond/-/merge_requests/564
!563 backend-library.scm: Sort font definitions in output. - Werner
Lemberghttps://gitlab.com/lilypond/lilypond/-/merge_requests/563

 Countdown:
!577 Open_type_font: use std::unordered_map bbox table - Han-Wen
Nienhuyshttps://gitlab.com/lilypond/lilypond/-/merge_requests/577
!576 Bar_number_engraver: fix order dependence - Dan Eble
https://gitlab.com/lilypond/lilypond/-/merge_requests/576
!575 Timing_translator: measureStartNow and \partial - Dan Eble
https://gitlab.com/lilypond/lilypond/-/merge_requests/575
!574 Add ly:smob-counts, a histogram of live smob types - Han-Wen
Nienhuyshttps://gitlab.com/lilypond/lilypond/-/merge_requests/574
!573 Remove separate CSS files for Internet Explorer - Jonas Hahnfeld
https://gitlab.com/lilypond/lilypond/-/merge_requests/573
!571 Add option -ddebug-eval - Han-Wen Nienhuys
https://gitlab.com/lilypond/lilypond/-/merge_requests/571
!570 Remove -ddebug-gc-assert-parsed-dead - Han-Wen Nienhuys
https://gitlab.com/lilypond/lilypond/-/merge_requests/570

 Review:
!589 Volta repeat cleanup - Dan Eble
https://gitlab.com/lilypond/lilypond/-/merge_requests/589
!588 Improve doc-markup-function-properties from document-markup.scm -
Thomas Morleyhttps://gitlab.com/lilypond/lilypond/-/merge_requests/588
!587 Remove unused functions from general-scheme.cc - Jonas Hahnfeld
https://gitlab.com/lilypond/lilypond/-/merge_requests/587
!586 Correct interfaces in multi-measure-rest-reminder.ly - Jonas
Hahnfeldhttps://gitlab.com/lilypond/lilypond/-/merge_requests/586
!581 Add markup-list-command string-lines - Thomas Morley
https://gitlab.com/lilypond/lilypond/-/merge_requests/581

 New:
No patches in New at this time.

 Waiting:
No patches in Waiting at this time.***
 

  

  Regards,

  

  James


  

Re: Doc-string with newline character

[Thomas Morley]

Am Do., 31. Dez. 2020 um 21:04 Uhr schrieb David Kastrup :
>
> Thomas Morley  writes:
>
> > Am Do., 31. Dez. 2020 um 12:31 Uhr schrieb David Kastrup :
> >>
> >> Thomas Morley  writes:
> >>
> >> > Am Do., 31. Dez. 2020 um 00:11 Uhr schrieb Thomas Morley
> >> > :
> >> >>
> >> >> Am Do., 31. Dez. 2020 um 00:00 Uhr schrieb David Kastrup :
> >> >> >
> >> >> > It's probably a bug.  Try replacing in
> >> >> >
> >> >> > (format #f "@item @code{~a} 
> >> >> > (~a)\n"
> >> >> >
> >> >> > in the function doc-markup-function-properties in
> >> >> > scm/document-markup.scm the second ~a with ~s (which should quote
> >> >> > everything in read syntax).  This would likely have more consequences,
> >> >> > like when there are string defaults.
> >> >> >
> >> >> > --
> >> >> > David Kastrup
> >> >>
> >> >> I'll have a look.
> >> >
> >> > While using ~s #\newline is displayed properly:
> >> > Used properties:
> >> > • split-char (#\newline)
> >> >
> >> > Though, empty lists would be displayed without quote (p.e. from
> >> > markup-command \whiteout):
> >> > Used properties:
> >> > • thickness (())
> >>
> >> That is correct: values are not quoted in such lists (there would be
> >> scheme-expr->lily-string if push came to shove, but I doubt it is a good
> >> idea here).
> >>
> >> > I regard the formatting code a bit cryptic.
> >> > How are opinions about keeping the apostrophe for empty lists?
> >>
> >> That would be really inconsistent.  If you don't like ((...)) one could
> >> try to come up with a different kind of formatting the default values.
> >>
> >> > Pairs don't display it anyway. P.e. from \overtie:
> >> > Used properties:
> >> > • shorten-pair ((0 . 0))
> >>
> >> --
> >> David Kastrup
> >
> > A patch is now up, dropping apostrophes.
> > https://gitlab.com/lilypond/lilypond/-/merge_requests/588
>
> Come to think of it: on top of using ~s here, wouldn't it also be
> necessary to quote characters @ { } by preceding them with @ ?

My knowledge of texinfo is rudimentary.
After a quick glance over doc-strings from our source it seems @{ and
@} are only used _inside_ of @code{ ... }.
@@ only once and as (@@ module-name binding-name), i.e. no texinfo.

This makes me think it is not needed to add @ to { and } outside of
@code{ ... }.
I may be wrong, though.

5.4.6 Syntax survey -> Special characters
http://lilypond.org/doc/v2.21/Documentation/contributor/syntax-survey#special-characters
is not specific in this regard, though.

Anyway, in `doc-markup-function-properties` from
scm/document-markup.scm only the property-names are set into @code{
... }
Those or all either symbols or procedures. If my above assumption is
correct, then we're fine there.

> Maybe scm/documentation-lib.scm should contain a function for that?  Something
> like texi-quote or so?

You mean something like `ps-quote` from scm/framework-ps.scm?

Cheers,
  Harm