Re: Lyric separator

[David Kastrup]

Janek Warchoł <address@hidden> writes:

> 2013/9/20 David Kastrup <address@hidden>:
>> Janek Warchoł <address@hidden> writes:
>>>
>>> As far as i can see this engraver doesn't work with 2.14.2, so it
>>> cannot be added to LSR (unless i'm missing something big?), but it's
>>> way too awesome to let it become accidentally forgotten.
>>
>> If that is the case, is there a particular reason you don't add it to
>> Documentation/snippets in the regular LilyPond distribution?
>
> Honestly?  Here's why:
>
> 1) Why i didn't think about it in the first place:
>    a) the last time i tried to do something with snippets, i was
>       utterly confused as to how it's working.  This resulted in me not
>       touching this stuff again, and thus i've forgotten that it
>       exists.
>    b) i mistakenly believed that all snippets have to go through LSR.

It's in the CG, under LSR work, Adding and editing snippets:

       If the new snippet uses new features that are not available in the
    current LSR version, the snippet should be added to
    `Documentation/snippets/new' and a reference should be added to the
    manual.

       Snippets created or updated in `Documentation/snippets/new' should
    be copied to `Documentation/snippets' by invoking at top of the source
    tree

         scripts/auxiliar/makelsr.py

       Be sure that `make doc' runs successfully before submitting a patch,
    to prevent breaking compilation.

> 2) Why i haven't done it now?
>    a) Well, i tried.  I've looked at the documentation, but i
>       didn't manage to do this in 15 minutes (in particular, i don't
>       have time to run 'make doc' now, but even without that i didn't
>       manage to find all necessary information).

You add it to Documentation/snippets/new.  You can use an existing
snippet as template if you don't want to read the CG which states:

    Formatting snippets in `Documentation/snippets/new'
    ---------------------------------------------------

    When adding a file to this directory, please start the file with

         \version "2.x.y"
         \header {
         % Use existing LSR tags other than 'docs'; see makelsr.py for
         % the list of tags used to sort snippets.  E.g.:
           lsrtags = "rhythms,expressive-marks"
         % This texidoc string will be formatted by Texinfo
           texidoc = "
         This code demonstrates ...
         "
         % Please put doctitle last so that the '% begin verbatim'
         % mark will be added correctly by makelsr.py.
           doctitle = "Snippet title"
         }

    and name the file `snippet-title.ly'.

    Please ensure that the version number you use at the top of the example
    is the minimum version that the file will compile with: for example, if
    the LSR is currently at 2.14.2 and your example requires 2.15.30, but
    the current development version of `lilypond' is 2.17.5, put `\version
    "2.15.30"' in the example.

    Please also pay particular attention to the lines beginning `lsrtags =
    ' and `doctitle ='.  The tags must match tags used in the
    documentation, and the `doctitle' must match the filename.

>    b) The snippet is quite undocumented, and i don't have time to
>       write the documentation at the moment.  Maybe i would try it if
>       the previous step was shorter.

If you really don't want to run "make doc" yourself, start a regular
issue.  At some point in the process, either at a review or at the
latest when it appears in staging, it will appear.

>    c) I don't have time to go through the review.  It usually
>       involves fixing a lot of nitpicks, and i don't have time for
>       this.  And if anyone had any objections about the scheme code, i
>       wouldn't be able to fix them because it's beyond my head.  Anyway,
>       having to handle reviews in the current form is a distraction.

Janek, we are not just talking about work of your own but you are
actively trying to convince others to abandon working on LilyPond
resources and work on your GitHub projects _instead_ of the LilyPond
resources we have in place.

The problem is that it does not serve the project if we scatter the work
of contributors on this list across several places not easily found from
the LilyPond documentation.

So if you feel that our current processes for getting information and
documentation into LilyPond don't work, how about thinking about how
that could be improved?

> None of the above reasons would stop me if i had enough
> motivation. But i have 0 motivation at the moment, thanks to the
> "github" discussion and other recent experiences on the mailing
> list. Only because i care about LilyPond i've forced myself to spend
> 15 minutes trying to figure out how this works, and then 20 minutes
> writing this email. Don't ask me for more unless you can increase my
> motivation.

I'm asking you to think about where you want the project to go.  It's
not like we have a flood of contributors to the LSR that would be
endangered of we were to change procedures, so naturally there is a lot
of potential for changes in procedure that will result in more and/or
better documentation finding its way into LilyPond.

If you prefer creating a private collection of resources, it will
usually not be found by LilyPond users starting their search from the
LilyPond documentation, and it will more or less get lost in the mists
of time once you lose interest and move on.

Which apparently happened to some degree to the LSR server proper, which
is why we are having the current problems.

But in spite of the current problems, we _have_ LSR snippets updated to
the current version in our documentation, and we _have_ LSR snippets
relying on current features in the current version of our documentation.

So the system is pretty resilient against losing information and code
when the standalone repository is languishing.

If we feel we need to change our ways of doing online repository work,
it would be a bad idea to drop all that.

If you want to work with GitHub, there is nothing precluding you to
basically forking the LilyPond Documentation/snippets/new directory and
letting people give you merge and pull requests on all that, and then,
depending on your personal traffic, submit an issue once a month with
your collected new snippets and edited old ones.

You don't need to bother often with git-cl in that manner, your (and
others') collected works get linked in LilyPond Documentation, the
descriptions of your snippets automagically gain translations, they are
automatically upgraded (and checked for continued correctness) with new
LilyPond versions and so forth and so on.

And your main work and colloboration environment is GitHub which you
prefer.

-- 
David Kastrup