Re: Doc-string with newline character

[Thomas Morley]

Am Do., 31. Dez. 2020 um 21:04 Uhr schrieb David Kastrup <dak@gnu.org>:
>
> Thomas Morley <thomasmorley65@gmail.com> writes:
>
> > Am Do., 31. Dez. 2020 um 12:31 Uhr schrieb David Kastrup <dak@gnu.org>:
> >>
> >> Thomas Morley <thomasmorley65@gmail.com> writes:
> >>
> >> > Am Do., 31. Dez. 2020 um 00:11 Uhr schrieb Thomas Morley
> >> > <thomasmorley65@gmail.com>:
> >> >>
> >> >> Am Do., 31. Dez. 2020 um 00:00 Uhr schrieb David Kastrup <dak@gnu.org>:
> >> >> >
> >> >> > 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