Re: [SPAM] Re: [openlilylib] Discuss restructuring

[Urs Liska]

On 7. Juli 2014 16:48:44 MESZ, Paul Morris <address@hidden> wrote:
>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.

I think that's good. Should be no problem to realize either.

>
>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.  
>

I'd prefer a clear separation in two fields. Makes clearer that we have two 
things. And makes the idea of using only valid categories easier to digest.

Urs
>
>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.
>
>_______________________________________________
>lilypond-user mailing list
>address@hidden
>https://lists.gnu.org/mailman/listinfo/lilypond-user