Re: [oll-user] 'snippets' Github interface idea

[Janek W. <lem...@gm...>]

Hi all,

2013/9/10 Urs Liska <ul...@op...>

> Hi folks,
>
> I try for the first time to use the oll-user list for the purpose of
> discussion of the new snippets repository.
>
> I suggest doing this in the future for two reasons:
> - automatically include anybody who might be interested
>    (including people one wouldn't have thought of in the first place)
> - keeping the content available in the public mailing list archive
>

+1


> I had an idea to improve the web presentation of the snippets on Github:
>
> Write a script that iterates over all snippets and generate a Markdown
> file to display the snippet in the Github interface.
> I see two options:
> - generate an accompanying .md file that can be clicked upon
> - place all snippets in its dedicated subdirectory and create a
> README.md file
>
> I would suggest the second solution although that will result in a large
> number of subdirectories.
> This way as soon as one opens the directory the README is displayed
> automatically.
>

The more i think about this, the more i like it.  Having one additional
layer of directories seems to be a small price to pay for user-friendly
interface.  In fact, with such an interface our repository would be almost
as functional as LSR currently is.


> In the basic version the generated file would contain
> - A heading and a general short introductory text
> - A generated image (the example output of the compilable file)
>    -> one more incentive to include good examples
> - The complete code listing
>    (unfortunately it isn't possible to provide code highlighting like in
> the blog posts)
>

This could simply be a link to the snippet file, if we wanted to make
things simple.

Actually, we may be able to provide syntax highligting: as far as i know,
you can insert HTML into markdown, so we could use your html-export from
Frescobaldi to produce html code and paste it into the .md file!
...for some reason this doesn't work as expected.  I've added a markdown
file containing html code generated using your Frescobaldi export, and it
isn't coloredd.  I think that Github isn't respecting some aspect of html
formatting, maybe that's a bug.
See my attempt here:
https://github.com/openlilylib/snippets/blob/markdown-test/notation-snippets/scaling-stencils.md

In a later version one could (quite easily) extract meta information
> from the snippet and provide them in a formatted and structured display.
>

In fact, we might want to switch to markdown in snippet descriptions
because of this.

The script would be run locally every now and then by an admin.
>

Easy to do with a cron job.


> Some issues to be considered:
> - Try to determine snippets to be processed (i. e. only new or modified
> ones)
>    recompiling snippets with differing LIlyPond versions would result in
> the images to be modified
>    (i.e. detected as changes by Git)
>

This should be easy: just store the committish of the revision of the
snippet that was used for producing .md and .png files, and check if think
that having a .png file in the snippet directory.  If there were changes in
the snippet file since that commit, recompile.


> - Determine appropriate LilyPond versions to compile the snippets
>
> I would write such a script in Python.
>
> What do you think?
>

go for it!

best,
Janek
-------------- next part --------------
An HTML attachment was scrubbed...