On 7. Juli 2014 16:48:44 MESZ, Paul Morris <[email protected]> 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 >[email protected] >https://lists.gnu.org/mailman/listinfo/lilypond-user _______________________________________________ lilypond-user mailing list [email protected] https://lists.gnu.org/mailman/listinfo/lilypond-user
