Re: [openlilylib] Discuss restructuring
Hi folks, as you can see, i'm falling behind with lilypond stuff, but i wanted to let you know that i've skimmed through this discussion and it LGTM. The only comment i have is: try to make things as simple as possible (but not simpler, of course) - i wouldn't like openlilylib getting a java-smell from trying to be overly generic and all-encompassing. Please continue with my blessing ;-) best, Janek 2014-07-08 12:42 GMT+02:00 Urs Liska u...@openlilylib.org: Am 07.07.2014 16:48, schrieb Paul Morris: Urs 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. This might be a good opportunity to get my feet wet with PyQt, i.e. not to write a _script_ but an application. Initially this wouldn't do much more than a mere script, but with more convenient interactivity. Later it could add an interface to _edit_ the metadata (e.g. selecting from existing tags, batch renaming of tags etc.) and also the documentation strings themselves. And it can even incorporate a convenient documentation browser. I think we should target the documentation output to be a self-contained HTML site in the repository itself (in a /doc directory) and only them consider making it available online too. At least with the HTML part of such a documentation I'd be glad for assistance (if I really get this started at all). Not that I'm unable to do that part but others can do that better, and it's a convenient split-point to share work. Best Urs ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [SPAM] Re: [openlilylib] Discuss restructuring
Am 20.07.2014 11:10, schrieb Janek Warchoł: Hi folks, as you can see, i'm falling behind with lilypond stuff, but i wanted to let you know that i've skimmed through this discussion and it LGTM. The only comment i have is: try to make things as simple as possible (but not simpler, of course) - i wouldn't like openlilylib getting a java-smell from trying to be overly generic and all-encompassing. Please continue with my blessing ;-) best, Janek I'll try to find a way through the options. I think that when there is an automatic way to generate the documentation this will encourage authors to do it right in the first place. Just an example: The description header field will be used in the documentation. And when one sees this in the HTML docs one will voluntarily take care of having a good description. But I'll try to keep the complexity as low as possible. I think the decision to have a single directory for all include files was a good one in that respect. Best Urs 2014-07-08 12:42 GMT+02:00 Urs Liska u...@openlilylib.org: Am 07.07.2014 16:48, schrieb Paul Morris: Urs 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. This might be a good opportunity to get my feet wet with PyQt, i.e. not to write a _script_ but an application. Initially this wouldn't do much more than a mere script, but with more convenient interactivity. Later it could add an interface to _edit_ the metadata (e.g. selecting from existing tags, batch renaming of tags etc.) and also the documentation strings themselves. And it can even incorporate a convenient documentation browser. I think we should target the documentation output to be a self-contained HTML site in the repository itself (in a /doc directory) and only them consider making it available online too. At least with the HTML part of such a documentation I'd be glad for assistance (if I really get this started at all). Not that I'm unable to do that part but others can do that better, and it's a convenient split-point to share work. Best Urs ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Am 07.07.2014 16:48, schrieb Paul Morris: Urs 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. This might be a good opportunity to get my feet wet with PyQt, i.e. not to write a _script_ but an application. Initially this wouldn't do much more than a mere script, but with more convenient interactivity. Later it could add an interface to _edit_ the metadata (e.g. selecting from existing tags, batch renaming of tags etc.) and also the documentation strings themselves. And it can even incorporate a convenient documentation browser. I think we should target the documentation output to be a self-contained HTML site in the repository itself (in a /doc directory) and only them consider making it available online too. At least with the HTML part of such a documentation I'd be glad for assistance (if I really get this started at all). Not that I'm unable to do that part but others can do that better, and it's a convenient split-point to share work. Best Urs ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
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 lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Am 07.07.2014 09:55, schrieb Urs Liska: 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?) I have updated the snippet-template file which contains a suggestion for all required and optional metadata fields. It can be inspected at https://github.com/openlilylib/openlilylib/blob/reorganization/library/snippet-template.ily Best Urs ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Am 07.07.2014 10:37, schrieb Urs Liska: Am 07.07.2014 09:55, schrieb Urs Liska: 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?) I have updated the snippet-template file which contains a suggestion for all required and optional metadata fields. It can be inspected at https://github.com/openlilylib/openlilylib/blob/reorganization/library/snippet-template.ily ... and I have created a proof-of-concept pull request: https://github.com/openlilylib/openlilylib/pull/40 Urs ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [SPAM] Re: [openlilylib] Discuss restructuring
Hi Urs and all, I followed the discussion only roughly, but I think it is a step in the right direction. I'd like to bring up the scheme-modules, I came up with. They need a fixed folder-structure and need to be updated according to the path they are stored in. Should we have a dedicated folder for scheme-modules or shall we store them for example in includes? Best, Jan-Peter Am 05.07.2014 14:28, schrieb Urs Liska: Am 05.07.2014 10:31, schrieb Urs Liska: Thanks. I think we will have to reconsider our metadata section and then do the transfer in that reorganization branch. I strongly suggest to excusively do that using pull requests, even among the members with push access. One more thing I would suggest to implement is some more standardization for the examples files. These should have formalized headers that are created by pulling in the fields from the definitions file. This should be quite easy to implement: Create one file with the redefinition of \booktitlemarkup and place this somewhere outside the user-accessible files. Then each examples file can simply include this with a relative path and there you go. (- This implies that our metadata considerations take this into account too) I have updated the Wiki page https://github.com/openlilylib/openlilylib/wiki and added a note about the reorganization process in the README.md on the restructuring branch. Urs ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [SPAM] Re: [openlilylib] Discuss restructuring
Am 07.07.2014 11:37, schrieb Jan-Peter Voigt: Hi Urs and all, I followed the discussion only roughly, but I think it is a step in the right direction. I'd like to bring up the scheme-modules, I came up with. They need a fixed folder-structure and need to be updated according to the path they are stored in. Should we have a dedicated folder for scheme-modules or shall we store them for example in includes? I had thought about this too, but as I don't completely understand what's going on there I didn't look further so far. If that's OK with you I'd suggest to handle the scheme-modules only after the conversion of the snippets. Or does the conversion of some snippets already depend on that issue? I thought of putting them in /includes/scheme-modules Does that fit? BTW: I'm not sure about all the lalily stuff. Would you consider merging that among all the other snippets or should that rather have a dedicated folder below /library (i.e. beside oll, templates etc.)? Best Urs Best, Jan-Peter ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [SPAM] Re: [openlilylib] Discuss restructuring
Am 07.07.2014 11:46, schrieb Urs Liska: I followed the discussion only roughly, but I think it is a step in the right direction. I'd like to bring up the scheme-modules, I came up with. They need a fixed folder-structure and need to be updated according to the path they are stored in. Should we have a dedicated folder for scheme-modules or shall we store them for example in includes? I had thought about this too, but as I don't completely understand what's going on there I didn't look further so far. If that's OK with you I'd suggest to handle the scheme-modules only after the conversion of the snippets. Or does the conversion of some snippets already depend on that issue? The module naming will change inherently and that will affect some snippets. But that should be easy to identify as I seem to be the only one doing such nasty stuff ;) I thought of putting them in /includes/scheme-modules Does that fit? That's fine. Shall I prepare the scheme stuff? I would propose a root folder like suggested in the include files folder BTW: I'm not sure about all the lalily stuff. Would you consider merging that among all the other snippets or should that rather have a dedicated folder below /library (i.e. beside oll, templates etc.)? I might put snippets originating from lalily - templating, edition-engraver and such - into a folder 'lalily'. In fact, I might reconstruct the whole lalily-complex in that folder and probably make it more convenient to use only parts or the whole workflow. Best, Jan-Peter ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [SPAM] Re: [openlilylib] Discuss restructuring
Am 07.07.2014 12:01, schrieb Jan-Peter Voigt: Am 07.07.2014 11:46, schrieb Urs Liska: I followed the discussion only roughly, but I think it is a step in the right direction. I'd like to bring up the scheme-modules, I came up with. They need a fixed folder-structure and need to be updated according to the path they are stored in. Should we have a dedicated folder for scheme-modules or shall we store them for example in includes? I had thought about this too, but as I don't completely understand what's going on there I didn't look further so far. If that's OK with you I'd suggest to handle the scheme-modules only after the conversion of the snippets. Or does the conversion of some snippets already depend on that issue? The module naming will change inherently and that will affect some snippets. But that should be easy to identify as I seem to be the only one doing such nasty stuff ;) I thought of putting them in /includes/scheme-modules Does that fit? That's fine. Shall I prepare the scheme stuff? I would propose a root folder like suggested in the include files folder OK, then you can move the files to /includes/scheme-modules. Just keep in mind: Create a new branch from the head of `reorganization` and open a pull request, but not against `master` (which will be presented by default) but against `reorganization`. BTW: I'm not sure about all the lalily stuff. Would you consider merging that among all the other snippets or should that rather have a dedicated folder below /library (i.e. beside oll, templates etc.)? I might put snippets originating from lalily - templating, edition-engraver and such - into a folder 'lalily'. In fact, I might reconstruct the whole lalily-complex in that folder and probably make it more convenient to use only parts or the whole workflow. I would be fine with having /library/lalily next to /library/oll, but I'd prefer having some other opinions on this. Best Urs Best, Jan-Peter ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
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. ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [SPAM] Re: [openlilylib] Discuss restructuring
On 7. Juli 2014 16:48:44 MESZ, Paul Morris p...@paulwmorris.com 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 lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Uns Liska wrote Some of them are good, some of them less so, I think. Maybe we could start going through the existing snippets and consider possible tags for each of them. This will make a pool of suggestions where we can filter out from. One question I still have is: Should the tags be flat too, i.e. single independent tags, or could there also be a hierarchy (which would then be reflected in the documentation)? For example I could imagine tagging a snippet markup-headers or notation-rhythm-polymetrics I think non-hierarchical (flat) tags make sense, following the principle of doing the simplest thing that will do the job, in this case helping people find the files/snippets they're interested in. Starting by tagging the existing snippets sounds fine to me. -Paul -- View this message in context: http://lilypond.1069038.n5.nabble.com/openlilylib-Discuss-restructuring-tp163922p164079.html Sent from the User mailing list archive at Nabble.com. ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
On 6. Juli 2014 16:12:56 MESZ, Paul Morris p...@paulwmorris.com wrote: Uns Liska wrote Some of them are good, some of them less so, I think. Maybe we could start going through the existing snippets and consider possible tags for each of them. This will make a pool of suggestions where we can filter out from. One question I still have is: Should the tags be flat too, i.e. single independent tags, or could there also be a hierarchy (which would then be reflected in the documentation)? For example I could imagine tagging a snippet markup-headers or notation-rhythm-polymetrics I think non-hierarchical (flat) tags make sense, following the principle of doing the simplest thing that will do the job, in this case helping people find the files/snippets they're interested in. 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. Urs -Paul -- View this message in context: http://lilypond.1069038.n5.nabble.com/openlilylib-Discuss-restructuring-tp163922p164079.html Sent from the User mailing list archive at Nabble.com. ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
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. 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). (I guess this might mean moving the files first and then working on the tags?) -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 lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Am 05.07.2014 05:30, schrieb Paul Morris: Uns Liska wrote 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 Good point, and I think that's a good solution to it as well. The only drawback I see is that adding the root directory means you lose some of the separation between the files that are to be included and those that are not. Do you think it would be worth doing something like this to keep it? root/library/oll/filename.ily Users would add the library directory (limits access to just includable files), and it only contains the oll directory (provides namespace). Just an idea, not sure if the extra directory is worth it or not. Haha, that is *exactly* what I thought too yesterday. Go to https://github.com/openlilylib/openlilylib/tree/reorganization and have a look at the library and usage-examples folders. They are a first sketch :-) The rest of what you wrote all sounds fine to me. Thanks. I think we will have to reconsider our metadata section and then do the transfer in that reorganization branch. I strongly suggest to excusively do that using pull requests, even among the members with push access. One more thing I would suggest to implement is some more standardization for the examples files. These should have formalized headers that are created by pulling in the fields from the definitions file. This should be quite easy to implement: Create one file with the redefinition of \booktitlemarkup and place this somewhere outside the user-accessible files. Then each examples file can simply include this with a relative path and there you go. (- This implies that our metadata considerations take this into account too) Best Urs Cheers, -Paul ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [SPAM] Re: [openlilylib] Discuss restructuring
Am 05.07.2014 10:31, schrieb Urs Liska: Thanks. I think we will have to reconsider our metadata section and then do the transfer in that reorganization branch. I strongly suggest to excusively do that using pull requests, even among the members with push access. One more thing I would suggest to implement is some more standardization for the examples files. These should have formalized headers that are created by pulling in the fields from the definitions file. This should be quite easy to implement: Create one file with the redefinition of \booktitlemarkup and place this somewhere outside the user-accessible files. Then each examples file can simply include this with a relative path and there you go. (- This implies that our metadata considerations take this into account too) I have updated the Wiki page https://github.com/openlilylib/openlilylib/wiki and added a note about the reorganization process in the README.md on the restructuring branch. Urs ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [SPAM] Re: [openlilylib] Discuss restructuring
Uns Liska wrote I have updated the Wiki page https://github.com/openlilylib/openlilylib/wiki and added a note about the reorganization process in the README.md on the restructuring branch. It's looking good to me. From the wiki page: Probably it's a good idea to assign a primary tag (= category) to each snippet and an arbitrary number of secondary tags (like alternative index entries). The new directories you first suggested might be a good place to start for such primary tags (if there is to be such a primary tag). Here they are: instruments layout lyrics markup meta (naming?) git-commands lilypond-version-predicates notation period stylesheets tweaks There was some good feedback on these from earlier in the thread. If there are to be directories for stylesheets, templates, and custom-music-fonts, then shouldn't they all go under oll to get the namespace benefit? Users may want to use these directory names for their own templates, stylesheets, etc. that aren't part of oll. Seems like custom-music-fonts could be shortened to music-fonts. Cheers, -Paul -- View this message in context: http://lilypond.1069038.n5.nabble.com/openlilylib-Discuss-restructuring-tp163922p164033.html Sent from the User mailing list archive at Nabble.com. ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Am 05.07.2014 18:22, schrieb Paul Morris: Uns Liska wrote I have updated the Wiki page https://github.com/openlilylib/openlilylib/wiki and added a note about the reorganization process in the README.md on the restructuring branch. It's looking good to me. From the wiki page: Probably it's a good idea to assign a primary tag (= category) to each snippet and an arbitrary number of secondary tags (like alternative index entries). The new directories you first suggested might be a good place to start for such primary tags (if there is to be such a primary tag). Yes, that's what I thought too. Here they are: instruments layout lyrics markup meta (naming?) git-commands lilypond-version-predicates notation period stylesheets tweaks There was some good feedback on these from earlier in the thread. Some of them are good, some of them less so, I think. Maybe we could start going through the existing snippets and consider possible tags for each of them. This will make a pool of suggestions where we can filter out from. One question I still have is: Should the tags be flat too, i.e. single independent tags, or could there also be a hierarchy (which would then be reflected in the documentation)? For example I could imagine tagging a snippet markup-headers or notation-rhythm-polymetrics It would also make sense to use the same structure as in the Notation Reference. Hm? If there are to be directories for stylesheets, templates, and custom-music-fonts, then shouldn't they all go under oll to get the namespace benefit? Users may want to use these directory names for their own templates, stylesheets, etc. that aren't part of oll. Seems like custom-music-fonts could be shortened to music-fonts. I had partially done that already, but only on the Wiki, not in the README. I've now updated both (this duplication isn't intended to be persistent...). Urs Cheers, -Paul -- View this message in context: http://lilypond.1069038.n5.nabble.com/openlilylib-Discuss-restructuring-tp163922p164033.html Sent from the User mailing list archive at Nabble.com. ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Am 03.07.2014 19:50, schrieb Paul Morris: Uns Liska wrote I think that after an initial phase of trial error we should now do it right and create a structure we can live with for the future. 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. And: at least Frescobaldi can show you the available categories through autocompletion (at least after entering the start of the _first_ folder name). It seems the category directories are mainly for navigation purposes, i.e. for finding things, apart from what I wrote about explicitly having it in the input file. but could this be done (in a more flexible way) through tags and/or search? So a file can be tagged with more than one tag and you can see a list of the files for any given tag. I guess GitHub lends itself to organization by nested categories-by-directory rather than by a flat list with tags and search... I'm quite sure that Github doesn't offer that. Which seems clear because they concentrate on source code repositories where it doesn't seem to make much sense. So... one simple way to provide for navigation is to have a GitHub wiki page (or the main readme page?) that lists links to the files by category and/or tag, and use that for navigation. That has the advantage of giving you an overview of what's in each category/tag, on a single page, rather than having to open and close directories. (This could be maintained manually, but I suppose it could also be automated at some point.) 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. In any case, I think having fewer and broader categories is generally better. Thanks for the feedback Urs Cheers, -Paul -- View this message in context: http://lilypond.1069038.n5.nabble.com/openlilylib-Discuss-restructuring-tp163922p163950.html Sent from the User mailing list archive at Nabble.com. ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Sounds interesting, but I don't thing the time is ready for that. There has been discussion of providing a structure similar to the TEXMF tree in LaTeX distributions. This would be a place where library additions or packages could be stored to and made available in the official LilyPond distribution - without having to be checked and reviewed as thoroughly as a formal inclusion in LilyPond itself. Best Urs Am 04.07.2014 04:57, schrieb Jay Anderson: On Thu, Jul 3, 2014 at 1:06 AM, Urs Liska u...@openlilylib.org wrote: Our repository has now lived for some time, and I think it is a good thing to have and maintain. The recent renaming was partially intended to stress its nature as an _includable_ library (as opposed to the official LSR). But to make that work for a longer time and to make it scale with an increasing amount of content I think we now need a fundamental restructuring of its directory structure. One thing that would be useful is a way to define dependencies which would be automatically downloaded from some repository. Modern build systems do this (e.g. maven for java). This type of functionality is becoming standard with newer programming languages. I imagine something as simple as: = \library lilyjazz = At compile-time it would download the snippet or load it from its local cache. Even something which takes an extra step to request a download would still be useful. In this case the above would give a compile error until you do something like: $ lilypond package manager install lilyjazz Of course it can get complicated (versioning, caching, etc.). Just a thought. -Jay ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Am 03.07.2014 17:51, schrieb Noeck: Hi, I like your ideas on the wiki. - I'd like to second especially the renaming/reodering of the definitions file. It looks better without definition(s).ily at the end. However, it means that the content of the library doubles (one folder and one ily). I am not sure, if it is a good idea, but the readme and the examples do not need to be includable and internal files should then go to helper-files (as far as I understand), so: how about only .ily files in the include-path and the rest elsewhere? - I had problems distinguishing these categories: - general-tools - input-shorthands - notation-snippets - specific-solutions While I could understand some of those from their content (or the description), I found it hard to draw the line between them in each case. What you propose now (layout, tweaks, text, lyrics, notation) is more intuitive for me. I see some border-cases/issues: - Is notation only for music? A function for lyrics or text would go in their categories? Should be discussed. I'm not sure about that yet. - I don't see yet what would go into »specific instruments/repertoire« For example shortcuts for staff changes in piano music. Snippets for specific bending techniques for guitar. Lute tablature. Notation issues specific to specific historic styles (15. century, contemporary ...) - Where would the music-fonts go? (I would suggest the custom- because anything here is custom) Ah, forgot that, they should have their own folder just like now. - What is period? (historic style. Seems redundant, sorry) - Btw, I always found the »markup« annoying, because it is such a technical term. »text« would be more straightforward, even if it is extended with markup commands. If we should decide to throw text and lyrics into one main category I'd agree with that.. Otherwise I think we should find a way to differenciate between them. - Why is a 2nd »meta« folder inside library? OK, this should be improved. The top-level meta folder (as it's currently) contains meta stuff about the project, such as snippets templates, some images and contributor information. Maybe this should be dropped and all of its content moved to the Wiki. The meta folder _inside_ the library is meant for stuff that isn't really related to the actual engraving. I'd see snippets in there like the ones that are currently in general-tools - +1 for the lowercase-dash-naming - Will openlilylib and snippets be the same? Does openlilylib contain all the LilyPond resources or only the the includable part and the meta folders etc. I am a bit confused about the naming. lilylib is outdated, right? OK, sorry for causing confusion. lilylib is outdated (and has been for some time already). Currently we have an organization https://github.com/openlilylib One of the repos of the organization is https://github.com/openlilylib/openlilylib This contains all the resources, has the issue tracker and a Wiki. _Inside_ this should be (as per my suggestion) a directory library which is the root of the includable files. This is also the directory that should be made available to Lilypond's include path. - I would like to remind the idea of a preview-image-overview over the library. See my comment to Paul's message. Those are just my comments. Thanks Urs Cheers, Joram ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
2014-07-04 12:23 GMT+02:00 Urs Liska u...@openlilylib.org: - I don't see yet what would go into »specific instruments/repertoire« For example shortcuts for staff changes in piano music. Snippets for specific bending techniques for guitar. Lute tablature. This way the bending techniques for guitar would belong to two categories (notation/ and specific-instruments/). But this is not possible if we use directories to tag each snippet. That's why I find the proposal of Paul much more scalable and effective. I would manage the tagging stuff separately. I see the benefit of Frescobaldi's autocompletion of include files if we keep organizing the snippets in different directories, but I think that in the long run Paul's proposal is better. ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
2014-07-03 17:51 GMT+02:00 Noeck noeck.marb...@gmx.de: I'd like to second especially the renaming/reodering of the definitions file. It looks better without definition(s).ily at the end. Me too, speaking file names are much better ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
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. 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. 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.) 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. Cheers, -Paul -- View this message in context: http://lilypond.1069038.n5.nabble.com/openlilylib-Discuss-restructuring-tp163922p163986.html Sent from the User mailing list archive at Nabble.com. ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
2014-07-04 17:14 GMT+02:00 Paul Morris p...@paulwmorris.com: 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. +1 ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
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 ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Uns Liska wrote 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 Good point, and I think that's a good solution to it as well. The only drawback I see is that adding the root directory means you lose some of the separation between the files that are to be included and those that are not. Do you think it would be worth doing something like this to keep it? root/library/oll/filename.ily Users would add the library directory (limits access to just includable files), and it only contains the oll directory (provides namespace). Just an idea, not sure if the extra directory is worth it or not. The rest of what you wrote all sounds fine to me. Cheers, -Paul -- View this message in context: http://lilypond.1069038.n5.nabble.com/openlilylib-Discuss-restructuring-tp163922p163999.html Sent from the User mailing list archive at Nabble.com. ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Hi, I like your ideas on the wiki. - I'd like to second especially the renaming/reodering of the definitions file. It looks better without definition(s).ily at the end. However, it means that the content of the library doubles (one folder and one ily). I am not sure, if it is a good idea, but the readme and the examples do not need to be includable and internal files should then go to helper-files (as far as I understand), so: how about only .ily files in the include-path and the rest elsewhere? - I had problems distinguishing these categories: - general-tools - input-shorthands - notation-snippets - specific-solutions While I could understand some of those from their content (or the description), I found it hard to draw the line between them in each case. What you propose now (layout, tweaks, text, lyrics, notation) is more intuitive for me. I see some border-cases/issues: - Is notation only for music? A function for lyrics or text would go in their categories? - I don't see yet what would go into »specific instruments/repertoire« - Where would the music-fonts go? (I would suggest the custom- because anything here is custom) - What is period? - Btw, I always found the »markup« annoying, because it is such a technical term. »text« would be more straightforward, even if it is extended with markup commands. - Why is a 2nd »meta« folder inside library? - +1 for the lowercase-dash-naming - Will openlilylib and snippets be the same? Does openlilylib contain all the LilyPond resources or only the the includable part and the meta folders etc. I am a bit confused about the naming. lilylib is outdated, right? - I would like to remind the idea of a preview-image-overview over the library. Those are just my comments. Cheers, Joram ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
Uns Liska wrote I think that after an initial phase of trial error we should now do it right and create a structure we can live with for the future. 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?) It seems the category directories are mainly for navigation purposes, i.e. for finding things, but could this be done (in a more flexible way) through tags and/or search? So a file can be tagged with more than one tag and you can see a list of the files for any given tag. I guess GitHub lends itself to organization by nested categories-by-directory rather than by a flat list with tags and search... So... one simple way to provide for navigation is to have a GitHub wiki page (or the main readme page?) that lists links to the files by category and/or tag, and use that for navigation. That has the advantage of giving you an overview of what's in each category/tag, on a single page, rather than having to open and close directories. (This could be maintained manually, but I suppose it could also be automated at some point.) In any case, I think having fewer and broader categories is generally better. Cheers, -Paul -- View this message in context: http://lilypond.1069038.n5.nabble.com/openlilylib-Discuss-restructuring-tp163922p163950.html Sent from the User mailing list archive at Nabble.com. ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
Re: [openlilylib] Discuss restructuring
On Thu, Jul 3, 2014 at 1:06 AM, Urs Liska u...@openlilylib.org wrote: Our repository has now lived for some time, and I think it is a good thing to have and maintain. The recent renaming was partially intended to stress its nature as an _includable_ library (as opposed to the official LSR). But to make that work for a longer time and to make it scale with an increasing amount of content I think we now need a fundamental restructuring of its directory structure. One thing that would be useful is a way to define dependencies which would be automatically downloaded from some repository. Modern build systems do this (e.g. maven for java). This type of functionality is becoming standard with newer programming languages. I imagine something as simple as: = \library lilyjazz = At compile-time it would download the snippet or load it from its local cache. Even something which takes an extra step to request a download would still be useful. In this case the above would give a compile error until you do something like: $ lilypond package manager install lilyjazz Of course it can get complicated (versioning, caching, etc.). Just a thought. -Jay ___ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
