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: [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: [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: [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
