[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: `@lilycode` for highlighting LilyPond code snippets
From: |
Werner LEMBERG |
Subject: |
Re: `@lilycode` for highlighting LilyPond code snippets |
Date: |
Wed, 07 Dec 2022 11:06:35 +0000 (UTC) |
> ```
> blabla @lilycode{\relative { c'2 e }} blabla
> ```
>
> Example 2:
>
> ```
> blabla
>
> @lilycode
> \relative { c'2 e {
> @end lilycode
> ```
>
> While the use for the block command version (`@lilycode ... @end
> lilycode`) should be clear, the main question is what policy we are
> going to recommend for the inline version: I suggest to apply
> `@lilycode` only if highlighting has some useful effects, which
> means that in most cases it should be rather *not* used because
> inline code is very short. Has anyone a suggestion for a better
> formulation, or better constraints?
Another issue has come up in the discussion of MR 1753, namely whether
`@lilycode` should actually be named `@lilypond[code]`. There are
four proposals, and I would like to hear opinions.
https://gitlab.com/lilypond/lilypond/-/merge_requests/1753
(0) Two preliminaries.
* The discussed command can be used both inline
```
@lilypond{...}
```
or as a block environment
```
@lilypond
...
@end lilypond
```
* The discussed command only exists for `lilypond-book`'s Texinfo
backend; it is an internal command only to be used for
LilyPond's documentation.
(1) For orthogonality and consistency, use `@lilypond[code]`.
Pro: The command reuses a lot of the snippet infrastructure that
is already used behind `@lilypond`. It implements syntax
highlighting in the same way as the `verbatim` option.
Cons: More characters to type, also using `[` and `]`, which are
hard to use on non-US keyboards. See also the 'pro' section of
(2).
(2) Stay with `@lilycode`.
Pro: The command is actually a variation of `@code`, not
`@lilypond`, thus its name; it's rather short and easy to type;
you can use even invalid LilyPond syntax in its argument; it won't
collide with `lilypond-book`'s `--filter` command line option.
There also exists the command `@musicxmlfile`, which is a
precedent because it doesn't use the 'lilypond' namespace.
Cons: It uses the 'lily' as the namespace, which is not consistent
with the already existing commands `@lilypond` and
`@lilypondfile`. There is already the precedent of
`@lilypond[fragment]`, which also accepts invalid LilyPond code
(because it needs some fixed boilerplate code before and after).
(3) Use `@lilypondcode`.
Pro: This fullfils the 'lilypond' namespace issue and thus blends
in to existing commands.
Cons: More characters to type, which is tedious if you have to
write a lot of documentation.
(4) Introduce short aliases `@ly`, `@lyfile, `@lycode` (or
`@ly[code]`).
Pro: Short.
Cons: Might collide with user-defined Texinfo macros.
Please comment!
Werner