Re: [openlilylib] Discuss restructuring

[Urs Liska]

Am 06.07.2014 17:15, schrieb Paul Morris:
> Uns Liska wrote
> > > Starting by tagging the existing snippets sounds fine to me.
> >
> > But not tagging directly but collecting suggestions first. Then decide
> > about a set of tags and apply them during the move.
>
> Ok, sure.
>
> Something to consider: since you are planning on writing a script to walk
> through the library and give some output about what files have what tags, it
> might make sense to go ahead and start that and then you'd have it as a tool
> to help with the process of editing the tags.

Hm, I think I _must not_ start with such a script right now, since I 
know that this - although being not too complex - will eat up too much 
of my time and concentration.

But your message triggered a little bit of thought, and I came to the 
conclusion that we should use a website (i.e. openlilylib.org) for the 
documentation.
The script will have two stages: parsing the content of the library and 
generating documentation from the resulting internal representation. I 
think generating complete HTML pages isn't more complicated than 
generating Markdown, but the results are better to use: We have more 
control over the layout and formatting options than on a Github Wiki, 
_and_ we have a self-contained HTML site that can also be deployed locally.

> For example, it would be nice
> to know what tags have already been entered for all of the files (which is
> how their authors were tagging them).

This raises yet another questions: the relation between pre-selected and 
free-form tags. Maybe a good compromise would be to have a (new) field 
"snippet-category" where only a number of predefined entries are valid 
(and if someone wants to add a category this should be discussed) and 
the existing field "tags" where free-form tags can be used. For this it 
would make sense to have a list with all used tags available and 
encourage authors to reuse existing tags rather than adding new ones 
(particularly it doesn't make sense to have singular and plural forms of 
the same tags).

> (I guess this might mean moving the files first and then working on the
> tags?)

Yes, that would mean that.
Maybe we can have a compromise. A script parsing the content of the tags 
field from all files shouldn't be hard to write. So we could:
- agree upon an initial set of categories
- agree upon a naming convention for tags
  (e.g. the same dashed-lowercase-scheme as for filenames).
- reconsider the metadata structure
  (which fields are mandatory, which optional, default values?)
- move all files in one go
  (that is: one commit for each snippet, as the files are not only 
moved but also renamed)
- clean up and tag the snippets. One by one and using pull request.
  (I think this should be done _with_ review and not be left to
  the authors' discretion)

Urs

> -Paul
>
>
>
> --
> View this message in context: 
> http://lilypond.1069038.n5.nabble.com/openlilylib-Discuss-restructuring-tp163922p164086.html
> Sent from the User mailing list archive at Nabble.com.
>
> _______________________________________________
> lilypond-user mailing list
> address@hidden
> https://lists.gnu.org/mailman/listinfo/lilypond-user