[Top][All Lists]

[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.

(0) Two preliminaries.

    * The discussed command can be used both inline


       or as a block environment

       @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) 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

    Pro: Short.

    Cons: Might collide with user-defined Texinfo macros.

Please comment!


reply via email to

[Prev in Thread] Current Thread [Next in Thread]