Re: [openlilylib] Discuss restructuring

[Paul Morris]

Uns Liska wrote
> 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.

Yep.


Uns Liska wrote
> 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).

Is your idea that the snippet-category would be restricted to a single
category per snippet and would be used for a "table of contents" in the
documentation?  While the tags would be used for an "index"?  With the table
of contents / categories being more standardized and predefined than the
index / tags?

A question this raises: Will categories also appear in tags field?  Or
rather, will categories be included as entries in the index?  Basically, can
I look in the index for the categories as well as the tags?  (If not then
the index is not as helpful because the primary topics that snippets fall
under is not in the index.)  

So I think it makes sense for the categories to also appear in the index.

Another way to do this would be to have only a tags field and have the first
tag entered in that field be the "primary tag" which is used for the table
of contents.  It would need to come from a predefined set of tags.  I'm not
sure if that's better or not.  


Uns Liska wrote
>>
>> (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)

Sounds fine to me.

-Paul




--
View this message in context: 
http://lilypond.1069038.n5.nabble.com/openlilylib-Discuss-restructuring-tp163922p164121.html
Sent from the User mailing list archive at Nabble.com.