Re: GDP: the snippets vs. texinfo
On 10 Nov 2007, at 06:02, Graham Percival wrote: PDF vs. HTML: pdf readers generally prefer to have consecutive documentation, with few links. HTML readers generally prefer to have links everywhere. Those that produce both seem to choose a format that can produce both automatically by some program. For example the texinfo format. But that might unsuitable for LilyPond. So you might need you own format. Stable docs vs. wiki: some people want an unchanging, complete, finished set of docs, particularly if they print them out. Other people like the constant flux of web 2.0 stuff. These do different things. The docs should be designed to lower the need ask questions on the lists, I think. A wiki can in fact be used to replace the LilyPond site altogether. One example is http://haskell.org/ which nowadays expand to http://haskell.org/haskellwiki/Haskell So it is possibly the whole Haskell site. Once upon the time, the Haskell wiki was a separate project. Hans Åberg ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: the snippets vs. texinfo
On 10 Nov 2007, at 06:02, Graham Percival wrote: Consider NR 1.2.1 Tuplets, for example. (if you haven't already, please see the LSR-lilypond docs email) Currently, the Commonly tweaked properties contains five examples. These demonstrate a number of neat tricks you can do with tuplets... but what happens if something needs to be updated? (ie a property name changes, somebody thinks of a better explanation, there's a nicer way to achieve a particular tweak, etc) Personally, I don't care were stuff is put, if only the main document is having certain keyword to search for and an indication of where to read more about it. If I type a keyword in Preview (Mac OS X), I can see all occurrences. So, for example, suppose I want to typeset less common meters. These are called by names such as irregular, asymmetrical, compound, complex, aksak, limping, etc. I could search for a few of those names to get a hit. If there is a line in the document that this is discussed in more detail elsewhere, it would be fine with me. In this context, I have found examples in the main document to be useful because sometimes I have some LilyPond code, and then I can search for occurrences of some keywords in that code. This way, I can get places where the topic I am looking for might be discussed. Hans Aberg ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: the snippets vs. texinfo
On 09.11.2007 (21:02), Graham Percival wrote: OK, it's finally time for the big fight! In managing the docs, I need to weigh multiple contradictory demands. PDF vs. HTML: pdf readers generally prefer to have consecutive documentation, with few links. HTML readers generally prefer to have links everywhere. Slight correction: pdf readers do like links -- internal ones -- it's a Good Thing. Having unneccessary divisions into separate documents which then cannot be linked, is a Bad Thing. Stable docs vs. wiki: some people want an unchanging, complete, finished set of docs, particularly if they print them out. Other people like the constant flux of web 2.0 stuff. I agree completely with your position that there should be one stable, complete, fixed set of docs, and that a wiki solution is not good for a complex piece of software like LP. On the other hand, I see the numerous private LP-tips-and-tricks-pages as a result of this: a feeling something like: I have figured out some neat things but since the docs are stable, complete, fixed, there is no way in there, so I'll make my own page. This is fine, but for the user who is looking for that extra information, it means that he has to hunt around among disparate pages of varying quality, organization, and up-to-date-ness. This may not be an accurate description anymore: with the LSR as a well-established and semi-official entity, there is hardly any need for the private pages anymore. In other words: I think it's fine as it is now: a fixed documentation and an officially endorsed repo of user-contributed stuff. One might still discuss practicalities: should the LSR only be snippets, is snippets the right term (or does it give too much associations in the direction of trifles?), etc. but that is another discussion for another thread. Out of all of these concerns, I naturally feel that my own position is the most important. If anybody wants me to relax my we don't have the resources to do this position, please volunteer in GDP. If I have more resources, of course I'll accept more good doc ideas, As an aside: I did volunteer, but I still get the we don't have the resources reply. :-) Some PDF users may not be so fond of the snippets because they move material out of the main docs. I'd like to point out that the Snippets are available as PDF, so that might mitigate this concern. The pdf does not contain the LP code, so it is fairly useless, at least in its current state. My proposal, taking into consideration all the contradictory demands laid out at the top of this email, is to have one or two tweaks in the @commonprop. The main goal of @commonprop is to pique the interest of a reader, to encourage him to follow the Snippets: foo, bar links. Finally, the reason why I started writing this: is this really the purpose of @commonprops? Or phrased differently: given the lack of resources and the concern that the documentation files grow too big, is it really a good idea to fill it up with appetizers? What I want to say is: if what you're saying is that everything which is now in @commonprop is just appetizers, some of it could even be removed, and what remains will remain as appetizers, I disagree, but if you're saying that the @commonprops should be revised so that all that which is necessary to accomplish normal typesetting tasks, i.e. solve commonly encountered problems, or as Trevor recently wrote: to reproduce anything in a score found on their bookshelves, should be elevated to main documentation text whereas that which is more of the btw, you can also do THIS kind could be moved to the LSR, I do agree. In any case, the flow should go in both directions: important tweaks in the LSR should be moved into the docs (but I think we agree on that). On the whole: the NR should contain everything and nothing but that which is necessary for the score on the bookshelf test. Eyolf -- Several years ago, an international chess tournament was being held in a swank hotel in New York. Most of the major stars of the chess world were there, and after a grueling day of chess, the players and their entourages retired to the lobby of the hotel for a little refreshment. In the lobby, some players got into a heated argument about who was the brightest, the fastest, and the best chess player in the world. The argument got quite loud, as various players claimed that honor. At that point, a security guard in the lobby turned to another guard and commented, If there's anything I just can't stand, it's chess nuts boasting in an open foyer. ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: the snippets vs. texinfo
Eyolf Østrem wrote: On 09.11.2007 (21:02), Graham Percival wrote: PDF vs. HTML: pdf readers generally prefer to have consecutive documentation, with few links. HTML readers generally prefer to have links everywhere. Slight correction: pdf readers do like links -- internal ones -- it's a Good Thing. Having unneccessary divisions into separate documents which then cannot be linked, is a Bad Thing. Oh, was that your concern? Separate documents can still be linked. I thought we already had that, but apparently it wasn't working. Take a look at tomorrow's GDP. (I think the files need to be in the same directory, however) (also, they look uglier than they should. As always, I'm accepting technical help) However, these links don't help people who print out PDFs. (well, they help slightly, but they're not ideal. OTOH, there's no difference between a link to a different document and a link to the same document -- actually, if anything I'd suggest that links to other documents are better, since you can have two printed manuals open at the same time) On the other hand, I see the numerous private LP-tips-and-tricks-pages as a result of this: a feeling something like: I have figured out some neat things but since the docs are stable, complete, fixed, there is no way in there, so I'll make my own page. This is fine, but for the user who is looking for that extra information, it means that he has to hunt around among disparate pages of varying quality, organization, and up-to-date-ness. I would argue that this is _not_ fine, for precisely the reasons you state. Ideally, users should look for info in two places: - official docs (be it NR, IR, LM, etc) - LSR (which is massively promoted, and linked to, from the official docs) One might still discuss practicalities: should the LSR only be snippets, is snippets the right term (or does it give too much associations in the direction of trifles?), etc. but that is another discussion for another thread. The real music tag in LSR is aimed at longer pieces. (it currently doesn't do that, simply because we don't have any pieces to tag with this) Out of all of these concerns, I naturally feel that my own position is the most important. If anybody wants me to relax my we don't have the resources to do this position, please volunteer in GDP. If I have more resources, of course I'll accept more good doc ideas, As an aside: I did volunteer, but I still get the we don't have the resources reply. :-) The volunteer more. Eyolf, currently you are the *only* person working on Rewriting NR 1. The entire chapter needs to be done before the end of 2007. Now do you see why I keep on saying we can't do X? :( Some PDF users may not be so fond of the snippets because they move material out of the main docs. I'd like to point out that the Snippets are available as PDF, so that might mitigate this concern. The pdf does not contain the LP code, so it is fairly useless, at least in its current state. That's on the todo list. My proposal, taking into consideration all the contradictory demands laid out at the top of this email, is to have one or two tweaks in the @commonprop. The main goal of @commonprop is to pique the interest of a reader, to encourage him to follow the Snippets: foo, bar links. Finally, the reason why I started writing this: is this really the purpose of @commonprops? Well, that's the main question in this discussion. :-) My proposal -- only a *proposal* -- is to use it as appetizers. In any case, the flow should go in both directions: important tweaks in the LSR should be moved into the docs (but I think we agree on that). Important tweaks in LSR are moved into the docs by giving them a docs tag. My rule of thumb for the docs: after the end of GDP, the NR should not change for the next five years. This obviously isn't possible -- no matter how careful we are, we'll miss a few typos or have some badly worded English. Lilypond will get some new features, which will need to some docs. The syntax will change, but this can/should/might be updateable with convert-ly. The non-tweaking syntax is fairly stable, at least. Stuff which might be changing more often -- the exact syntax of tweaks, making tweaks more interesting/complicated/simpler/etc, adding new tweaks -- should be done in a manner which allows easy updating. LSR is such a method. In this case, about 80% of my argument relies on lack of resources rather than I think that documentation looks better this way. Or in other words, documentation is a process, not a product. And we have very few resources which we direct towards that process. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: the snippets vs. texinfo
On 10.11.2007 (06:17), Graham Percival wrote: Eyolf Østrem wrote: Slight correction: pdf readers do like links -- internal ones -- it's a Good Thing. Having unneccessary divisions into separate documents which then cannot be linked, is a Bad Thing. Oh, was that your concern? Half of it. The other -- main -- half is searching. Furthermore, cross-document linking isn't as uncomplicated as you make it appear: as you say, the files must be in the same dir, and they have to exist in the first place (what if I use my own copy of the NR and for some reason haven't downloaded the PU?). On the other hand, I see the numerous private LP-tips-and-tricks-pages as a result of this: a feeling something like: I have figured out some neat things but since the docs are stable, complete, fixed, there is no way in there, so I'll make my own page. This is fine, but for the user who is looking for that extra information, it means that he has to hunt around among disparate pages of varying quality, organization, and up-to-date-ness. I would argue that this is _not_ fine, for precisely the reasons you state. Ideally, users should look for info in two places: - official docs (be it NR, IR, LM, etc) - LSR (which is massively promoted, and linked to, from the official docs) Agreed - that's what I meant too, and I think it's a great step when we have in fact got these two channels. At the time, i.e. before LSR was firmly established, it was fine, because there was no easy outlet for that kind of wiki-like contributions, but now the LSR should take care of that. As an aside: I did volunteer, but I still get the we don't have the resources reply. :-) The volunteer more. Eyolf, currently you are the *only* person working on Rewriting NR 1. The entire chapter needs to be done before the end of 2007. Well, if what you say below is the goal, that on the whole the docs should not change after the GDP, I'd say there is no need to rush it, especially if there are so few people to do the work. As for me, I have a daytime job too... Now do you see why I keep on saying we can't do X? :( Of course. As long as it doesn't turn into a We can't do X, so we won't even consider it, not even if it would make Y -- which we can and must do -- easier. But I'm not advocating featuritis. Finally, the reason why I started writing this: is this really the purpose of @commonprops? Well, that's the main question in this discussion. :-) My proposal -- only a *proposal* -- is to use it as appetizers. In any case, the flow should go in both directions: important tweaks in the LSR should be moved into the docs (but I think we agree on that). Important tweaks in LSR are moved into the docs by giving them a docs tag. but that will only include them in the snippet part of the docs, right? This may of course be enough in many cases, but there are some snippets which are central enough to merit inclusion in the main text as well. The snippet Adding an extra staff (http://lsr.dsi.unimi.it/LSR/Item?id=110) IMHO should be included directly, and Adding beams, slurs, ties, etc. (http://lsr.dsi.unimi.it/LSR/Item?id=321) is even *formulated* in a Documentation way, as an extension to what is already in there, rather than an additional piece of information. Those two could go almost straight in. eyolf (who will now stop spending time writing list mail and instead do some volunteer work...) -- Delay not, Caesar. Read it instantly. -- Shakespeare, Julius Caesar 3,1 Here is a letter, read it at your leisure. -- Shakespeare, Merchant of Venice 5,1 [Quoted in VMS Internals and Data Structures, V4.4, when referring to I/O system services.] ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: the snippets vs. texinfo
Eyolf Østrem wrote: The entire chapter needs to be done before the end of 2007. Well, if what you say below is the goal, that on the whole the docs should not change after the GDP, I'd say there is no need to rush it, especially if there are so few people to do the work. Two phases: before 2007, get GDP no worse than the 2.11 docs. That means somebody spending a week looking at each section in NR 1 and cleaning up the worst TODO / FIXMEs. After 2007, if anybody is still interested, we'll try go bring GDP from not worse than to significantly better than. Or perhaps even perfect. :) Now do you see why I keep on saying we can't do X? :( Of course. As long as it doesn't turn into a We can't do X, so we won't even consider it, not even if it would make Y -- which we can and must do -- easier. True. Important tweaks in LSR are moved into the docs by giving them a docs tag. but that will only include them in the snippet part of the docs, right? This may of course be enough in many cases, but there are some snippets which are central enough to merit inclusion in the main text as well. The snippet Adding an extra staff (http://lsr.dsi.unimi.it/LSR/Item?id=110) IMHO should be included directly, and Adding beams, slurs, ties, etc. (http://lsr.dsi.unimi.it/LSR/Item?id=321) is even *formulated* in a Documentation way, as an extension to what is already in there, rather than an additional piece of information. Those two could go almost straight in. First, THANK YOU!!! for bringing up specific examples. Especially in this case, since I was thought you were talking about a totally different kind of snippet. Second, yes I totally agree; these kinds of snippets should be in the main docs. In fact, 321 is already verbatim in LM 3.3.1. 110 doesn't appear anywhere, but I'm adding it to LM 3 right now. eyolf (who will now stop spending time writing list mail and instead do some volunteer work...) :) Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
GDP: the snippets vs. texinfo
OK, it's finally time for the big fight! In managing the docs, I need to weigh multiple contradictory demands. PDF vs. HTML: pdf readers generally prefer to have consecutive documentation, with few links. HTML readers generally prefer to have links everywhere. Stable docs vs. wiki: some people want an unchanging, complete, finished set of docs, particularly if they print them out. Other people like the constant flux of web 2.0 stuff. Me vs. everybody: I want a set of easily maintained docs. I also want to set realistic goals. I feel no compunction about rejecting any suggestion -- no matter how good from a documentation standpoint -- which we do not have the resources (ie volunteer time/effort) to create and/or maintain. Out of all of these concerns, I naturally feel that my own position is the most important. If anybody wants me to relax my we don't have the resources to do this position, please volunteer in GDP. If I have more resources, of course I'll accept more good doc ideas, Consider NR 1.2.1 Tuplets, for example. (if you haven't already, please see the LSR-lilypond docs email) Currently, the Commonly tweaked properties contains five examples. These demonstrate a number of neat tricks you can do with tuplets... but what happens if something needs to be updated? (ie a property name changes, somebody thinks of a better explanation, there's a nicer way to achieve a particular tweak, etc) 1) The helpful user could download the lilypond source, edit rhythms.tely, compile the docs to check that it works, make a patch, send it to -devel. That's a lot to expect from people. 2) The helpful user could send an email explaining what to do, according to the documentation suggestions page. I honestly don't think that's too much to ask from helpful users, but in the past two years I've received less than ten such emails. Clearly people are shy about sending emails. Now, suppose (for the sake of argument) that all of these tweaks were in the Snippets: rhythms/ link at the bottom of that page. This means that these tweaks are in LSR, and that gives helpful users a third option to fix examples: 3) The helpful users edits the snippet in LSR. The LSR editor is notified about the modified snippet, approves it, and the main lilypond docs are magically updated in a few days. I confess that I'm not totally convinced that hordes of users are going to follow #3... but whenever I complain about the lack of users helping with the docs (pointing out #2, all you need to do is send an email to me -- if you can complain about the docs on this mailist, then you can help fix the docs!) I always get people claiming that if there was a wiki, they would be committing updates. Some PDF users may not be so fond of the snippets because they move material out of the main docs. I'd like to point out that the Snippets are available as PDF, so that might mitigate this concern. Now that we have the technology in place and a description of how it might work, we need to decide how this affects the docs. In particular, what do we keep in @commonprop, and what do we move into LSR (and the Snippets) ? My proposal, taking into consideration all the contradictory demands laid out at the top of this email, is to have one or two tweaks in the @commonprop. The main goal of @commonprop is to pique the interest of a reader, to encourage him to follow the Snippets: foo, bar links. For example, in Tuplets I would suggest keeping the first and second-last examples in the @commonprop section, and moving everything else into Snippets. Not because I don't think the tweaks are useful, but just to direct readers to the Snippets, and from there the LSR. Hopefully the easily-updateable LSR will generate a culture of doc-improvement. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
