Re: [openlilylib] Discuss restructuring

[Urs Liska]

Am 04.07.2014 17:14, schrieb Paul Morris:
> Uns Liska wrote
> > Am 03.07.2014 19:50, schrieb Paul Morris:
> > > Hi Urs,  This is looking like an improvement to me.  Here's a thought.
> > > If
> > > the emphasis is on include-ability, what about just having all the
> > > include
> > > files at the same level in the "Library" directory, without needing to
> > > categorize them by putting them in different directories by topic?  Then
> > > you
> > > could just do \include "filename.ily" without having to remember what
> > > category directory a file is in.  (Maybe stylesheets still gets a
> > > directory
> > > since they are a clear case of a different kind of file with a specific
> > > usage?)
> >
> > This is definitely something we should discuss. Although I actually like
> > having a category path explicitly written in the input file.
>
> You could always just add the category with a comment:
>
>    \include "file-name.ily" % category-name
>
> ;-)
> </kidding>
>
>
> Uns Liska wrote
> > And: at least Frescobaldi can show you the available categories through
> > autocompletion (at least after entering the start of the _first_ folder
> > name).
>
> True, but you still have to know which category the file is in, and there
> will probably always be files that might be in more than one.

OK.
I can see the point and I'm ready to accept that approach. There is one 
issue, however, that I'd like to discuss before making any decision.

    \include "file-name.ily"

opens the door wide for name conflicts. The more the names are speaking 
the more they will be likely to exist in other places too. Particularly 
as much of the stuff we have (and will have) is of quite similar 
characteristic as all the other files inside LilyPond which can be 
included directly.

So I would suggest inserting a kind of namespace through the following:

- don't name the root directory "library" but "oll"
  This is a good "prefix" as it is characteristic _and_ short
- let the user add the actual root directory instead of the "oll"
  subdirectory to the include path
- let the files be included with
  \include "oll/file-name.ily"

The idea of making the navigation work through tagging the actual 
snippets sounds like a good idea. This allows for more than one 
category, even a main category plus secondary entries in different 
categories.
It will require a stricter handling of snippet metadata, but I think 
this is more of a good thing than an annoyance ;-)

> Uns Liska wrote
> > This is probably the way to go anyway. Actually I had this in mind since
> > the first steps with the repository. I'd like to have a script that
> > walks through the whole library and generates documentation from the
> > metadata stored in the files. And just recently I realized that the Wiki
> > is the place for this to go. This script would then create the TOC,
> > together with some short descriptions of the categories, and
> > additionally it could create a detail page for each snippet/item, using
> > its example file to create png images.
>
> This sounds good!  Although not trivial to do.

Actually I don't think it's too complex if we enforce a certain level of 
standardization in the snippets metadata and internal file organization.

> You could list each item by
> category and/or by tags from the metadata.  The wiki could be the place for
> this, or even a website (openlilylib.org) outside of github, with links to
> the files on github.  (A website might offer easier automated page
> generation (?), more flexibility, and no one would be tempted to manually
> edit the page like on the wiki.)

There's two aspects to that. From a user's perspective you're completely 
right that openlilylib.org would be a suitable place for that documentation.
The issue with that is that currently I'm the only one with push access 
to that domain (it's driven by Git, and I can't give any others access 
to that without giving them _full_ access to my server. The content 
itself is maintained in a Github repository, but in order to make it 
available at the web site I have to push to another remote.).
I'm considering moving to a different server with root access - which 
would allow me to create a dedicated "user" for git. But I'm still 
having issues with the mail server at the new provider, so I'm reluctant 
to follow with my remaining materials there too.

On the other hand we can easily restrict editing of the Wiki to 
registered project members which would drastically simplify the situation.

However I assume that I'll rather solve my server issues than finish an 
auto-documentation script before that ...

> One nice thing about decoupling the actual location of the files (their
> include path) from the categories/tags/navigation structure, is that you can
> change the latter as needed as the library changes and matures, without
> breaking compatibility with existing files that are already using the
> library.

Very good point!

Best
Urs

> Cheers,
> -Paul