Re: doc reorg (especially Usage) possibly finished
On Mon, Sep 28, 2009 at 09:08:46PM -0600, Andrew Hawryluk wrote: > On Sun, Sep 27, 2009 at 6:57 AM, Graham Percival > wrote: > > What do people think about the doc reorg shown in: > > http://kainhofer.com/~lilypond/Documentation/general/Manuals.html > > (and the actual manual pages, of course) > > Is it worth mentioning in the essay page that the detailed > typographical examples are easier to analyze in the PDF version than > the HTML version? Sure; done. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
On Sun, Sep 27, 2009 at 6:57 AM, Graham Percival wrote: > What do people think about the doc reorg shown in: > http://kainhofer.com/~lilypond/Documentation/general/Manuals.html > (and the actual manual pages, of course) Is it worth mentioning in the essay page that the detailed typographical examples are easier to analyze in the PDF version than the HTML version? -AH ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
2009/9/28 Graham Percival : > Really? I could have sworn that I did the "touch > Documentation/*.te??" test... or maybe this doesn't trigger a full > rebuild after all? That won't rebuild the translations though, will it? Here's the error message I got: make[3]: *** No rule to make target `/home/neil/lilypond/./out-www/xref-maps/application.fr.xref-map', needed by `local-WWW-1'. Stop. make[3]: *** Waiting for unfinished jobs > Sorry about this; I should have checked with a full make > doc-clean. No problem, for the time being I can make do with a local revert; I just need to finish a clean build before checking a few docs changes I've prepared. >> If it's just the application -> usage change, then I'll be happy to sort it >> out. > > I don't mind doing it tomorrow morning. I held off making this > change just in case anybody had a huge problem with the new doc > structure, but it seems that we're all basically ok with it. OK, if you're sure, I'll let you get on with it. Regards, Neil ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
On Mon, Sep 28, 2009 at 05:56:27PM +0100, Neil Puttock wrote: > 2009/9/27 John Mandereau : > > > A few files have been moved in English docs, could somebody do the same > > for translated docs? I'm asking just in case somebody may volunteer, > > otherwise I'll do this after October 5th and not before I get an > > Internet connection at home. > > Ah, this probably explains why I can do a clean docs build; it's > currently breaking in Documentation/fr. Really? I could have sworn that I did the "touch Documentation/*.te??" test... or maybe this doesn't trigger a full rebuild after all? Sorry about this; I should have checked with a full make doc-clean. > If it's just the application -> usage change, then I'll be happy to sort it > out. I don't mind doing it tomorrow morning. I held off making this change just in case anybody had a huge problem with the new doc structure, but it seems that we're all basically ok with it. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
2009/9/27 John Mandereau : > A few files have been moved in English docs, could somebody do the same > for translated docs? I'm asking just in case somebody may volunteer, > otherwise I'll do this after October 5th and not before I get an > Internet connection at home. Ah, this probably explains why I can do a clean docs build; it's currently breaking in Documentation/fr. If it's just the application -> usage change, then I'll be happy to sort it out. Regards, Neil ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
On Mon, Sep 28, 2009 at 06:23:12PM +0200, Mats Bengtsson wrote: > Quoting John Mandereau : > >> Le dimanche 27 septembre 2009 à 19:08 +0100, Graham Percival a écrit : >>> I'm wondering if we can call them "Function index" and "Concept >>> index". Or something like that. It just seems weird to have a >>> "LilyPond index" for every manual. >> >> Maybe "Function and concept index", as this index actually merges >> concept index and function index? I'm not sure this is better than >> "LilyPond index". > > Still, it would be much better if we simply could call it "Index". Do > we still have the silly technical problem that this would translate > into file called index.html in the web version? Yes... what about naming them by the book name? Learning manual index, Notation reference index, etc? Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
Quoting John Mandereau : Le dimanche 27 septembre 2009 à 19:08 +0100, Graham Percival a écrit : I'm wondering if we can call them "Function index" and "Concept index". Or something like that. It just seems weird to have a "LilyPond index" for every manual. Maybe "Function and concept index", as this index actually merges concept index and function index? I'm not sure this is better than "LilyPond index". Still, it would be much better if we simply could call it "Index". Do we still have the silly technical problem that this would translate into file called index.html in the web version? /Mats ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
On Sun, Sep 27, 2009 at 08:12:26PM +0200, John Mandereau wrote: > Le dimanche 27 septembre 2009 à 13:57 +0100, Graham Percival a écrit : > > What do people think about the doc reorg shown in: > > http://kainhofer.com/~lilypond/Documentation/general/Manuals.html > > (and the actual manual pages, of course) > > I think the frame "Read it now" is superfluous, a simple link "Read it > now" at the beginning of the frame "MANUAL NAME" or assiging "MANUAL > NAME" the URL of the manual should be enough (I prefer the former to > make sure that the reader immediately sees it). I was trying to avoid the reader *immediately* seeing the link -- I wanted them to read the intro text first (and especially the warning for the Notation Reference). That said, I wanted a regular user to know where to find the link on each doc page. The current setup gives regular people a common place (mid-right on the page), but I don't /think/ that new readers will skip over the warning. That said, even if it were in 40-point flashing red, some people would still fumble around in Notation without knowing the musical terms. :( Anybody else want to voice opinions about this? I don't mind changing the layout of the page, but I'd like a few more thoughts first. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
On 9/27/09 11:55 AM, "John Mandereau" wrote: > Le dimanche 27 septembre 2009 à 17:37 +0100, Graham Percival a écrit : >> How much of scheme do we get into, though? I mean, what about >> moving it back into Notation? > > This would be wrong: even if we expanded it up to make a big chapter, it > would not become reference documentation (we alreadhy have Notation Ref. > 6 "Interfaces for programmers" and the Internals Reference for this), it > would remain learning material. > > >> As far as I'm concerned, as long as newbies know that it's >> *possible* to do all sorts of funky stuff with this magical scheme >> stuff, that's all they need to know. I mean, nobody can seriously >> complain that we're newbie-unfriendly by not explaining how to >> make noteheads automatically change size based on their staff >> position! > > Certainly. However, when we decide time has come to significantly > expand this appendix and it gets too big to remain an appendix, we'll > have to reword the reading guidelines so the reader doesn't feel he > should even read this chapter, e.g. by recommending that "all this > manual should be read from cover to cover, except the last chapter > "Scheme tutorial", that can be read later to make better use of Chapters > 5 and 6 of the Notation Reference, for example." I think that my preference would actually to create a LilyPond Programming manual, with the Scheme Tutorial and a rewritten NR6. I don't think that NR6 is actually Notation Reference. That particular chapter has seemed to me to be out of place anyway. Thanks, Carl ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
Le dimanche 27 septembre 2009 à 19:08 +0100, Graham Percival a écrit : > I'm wondering if we can call them "Function index" and "Concept > index". Or something like that. It just seems weird to have a > "LilyPond index" for every manual. Maybe "Function and concept index", as this index actually merges concept index and function index? I'm not sure this is better than "LilyPond index". Best, John signature.asc Description: Ceci est une partie de message numériquement signée ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
Le dimanche 27 septembre 2009 à 13:57 +0100, Graham Percival a écrit : > What do people think about the doc reorg shown in: > http://kainhofer.com/~lilypond/Documentation/general/Manuals.html > (and the actual manual pages, of course) I think the frame "Read it now" is superfluous, a simple link "Read it now" at the beginning of the frame "MANUAL NAME" or assiging "MANUAL NAME" the URL of the manual should be enough (I prefer the former to make sure that the reader immediately sees it). A few files have been moved in English docs, could somebody do the same for translated docs? I'm asking just in case somebody may volunteer, otherwise I'll do this after October 5th and not before I get an Internet connection at home. Best, John signature.asc Description: Ceci est une partie de message numériquement signée ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
On Sun, Sep 27, 2009 at 07:55:32PM +0200, John Mandereau wrote: > Le dimanche 27 septembre 2009 à 17:37 +0100, Graham Percival a écrit : > > As far as I'm concerned, as long as newbies know that it's > > *possible* to do all sorts of funky stuff with this magical scheme > > stuff, that's all they need to know. > Certainly. However, when we decide time has come to significantly > expand this appendix and it gets too big to remain an appendix, we'll > have to reword the reading guidelines so the reader doesn't feel he > should even read this chapter, I guess. We'd also need to reword the intro to Notation, since that "assumes the reader has read and understood the Learning manual". > > Was that seriously the reason? I don't follow... I mean, the html > > filename is "LilyPond-index.html". > > So, why do you criticize the name "LilyPond index"? The constraint is > that we must have a node name other than "Index", otherwise the splitted > HTML page name would clash with Top node HTML page index.html (not on > Unix systems, but on Windows). I'm wondering if we can call them "Function index" and "Concept index". Or something like that. It just seems weird to have a "LilyPond index" for every manual. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
Le dimanche 27 septembre 2009 à 17:37 +0100, Graham Percival a écrit : > How much of scheme do we get into, though? I mean, what about > moving it back into Notation? This would be wrong: even if we expanded it up to make a big chapter, it would not become reference documentation (we alreadhy have Notation Ref. 6 "Interfaces for programmers" and the Internals Reference for this), it would remain learning material. > As far as I'm concerned, as long as newbies know that it's > *possible* to do all sorts of funky stuff with this magical scheme > stuff, that's all they need to know. I mean, nobody can seriously > complain that we're newbie-unfriendly by not explaining how to > make noteheads automatically change size based on their staff > position! Certainly. However, when we decide time has come to significantly expand this appendix and it gets too big to remain an appendix, we'll have to reword the reading guidelines so the reader doesn't feel he should even read this chapter, e.g. by recommending that "all this manual should be read from cover to cover, except the last chapter "Scheme tutorial", that can be read later to make better use of Chapters 5 and 6 of the Notation Reference, for example." > > index.html is the default page for a website. Hence, we wanted LilyPond > > index. > > Was that seriously the reason? I don't follow... I mean, the html > filename is "LilyPond-index.html". So, why do you criticize the name "LilyPond index"? The constraint is that we must have a node name other than "Index", otherwise the splitted HTML page name would clash with Top node HTML page index.html (not on Unix systems, but on Windows). Cheers, John signature.asc Description: Ceci est une partie de message numériquement signée ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
On Sun, Sep 27, 2009 at 10:15:30AM -0600, Carl Sorensen wrote: > > On 9/27/09 6:57 AM, "Graham Percival" wrote: > > > 1) Learning B. Scheme tutorial -- do we want to keep this here, or > > integrate into Learning 4? Or _possibly_ make a Learning 5 > > Programming inside LilyPond? > > I don't think we want to put this in the main body of the Learning Manual, > since we ask readers to read the LM cover to cover. I think that having it > as an appendix is the right thing to do. But I like the name Programming > inside LilyPond much better than Scheme tutorial. How much of scheme do we get into, though? I mean, what about moving it back into Notation? As far as I'm concerned, as long as newbies know that it's *possible* to do all sorts of funky stuff with this magical scheme stuff, that's all they need to know. I mean, nobody can seriously complain that we're newbie-unfriendly by not explaining how to make noteheads automatically change size based on their staff position! > > 2) Was there some reason why all the indices are called "LilyPond > > index"? I have a vaugue recollection that it worked better in the > > info format or something like that...? > > index.html is the default page for a website. Hence, we wanted LilyPond > index. Was that seriously the reason? I don't follow... I mean, the html filename is "LilyPond-index.html". > > 3) I'm not convinced about the order of material inside each > > chapter of Usage yet -- at the moment, I just want people to > > consider the division of stuff into chapters, not within each > > chapter. > > I think there should be at least a pointer to OooLilyPond in Usage 3.2., It's in Usage 3.6. IMO, Usage 3 is the worst chapter in our existing documentation, but I'm not getting into that until other projects are finished up. > I do have a minor nit to pick: on the Manuals page, the regular use section > is ordered > Notation, Snippets, Usage, > but the menu bar is ordered > Notation, Snippets, Usage. I see there was a similar thinko when you wrote that! The meaning got through, though; thanks, fixed. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: doc reorg (especially Usage) possibly finished
On 9/27/09 6:57 AM, "Graham Percival" wrote: > What do people think about the doc reorg shown in: > http://kainhofer.com/~lilypond/Documentation/general/Manuals.html > (and the actual manual pages, of course) > > > I think I have the balance between Learning and Usage good now. > The only remaining issues are: > > 1) Learning B. Scheme tutorial -- do we want to keep this here, or > integrate into Learning 4? Or _possibly_ make a Learning 5 > Programming inside LilyPond? I don't think we want to put this in the main body of the Learning Manual, since we ask readers to read the LM cover to cover. I think that having it as an appendix is the right thing to do. But I like the name Programming inside LilyPond much better than Scheme tutorial. > > 2) Was there some reason why all the indices are called "LilyPond > index"? I have a vaugue recollection that it worked better in the > info format or something like that...? index.html is the default page for a website. Hence, we wanted LilyPond index. > If somebody could search the archives to look for any such reason, > that would be nice. If there's no such reason, then I'd rather > rename them in some way. > > 3) I'm not convinced about the order of material inside each > chapter of Usage yet -- at the moment, I just want people to > consider the division of stuff into chapters, not within each > chapter. I like the division of stuff into chapters. Looks good! I think there should be at least a pointer to OooLilyPond in Usage 3.2., I do have a minor nit to pick: on the Manuals page, the regular use section is ordered Notation, Snippets, Usage, but the menu bar is ordered Notation, Snippets, Usage. All the rest are in order. Thanks for your great work! Carl ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
doc reorg (especially Usage) possibly finished
What do people think about the doc reorg shown in: http://kainhofer.com/~lilypond/Documentation/general/Manuals.html (and the actual manual pages, of course) I think I have the balance between Learning and Usage good now. The only remaining issues are: 1) Learning B. Scheme tutorial -- do we want to keep this here, or integrate into Learning 4? Or _possibly_ make a Learning 5 Programming inside LilyPond? 2) Was there some reason why all the indices are called "LilyPond index"? I have a vaugue recollection that it worked better in the info format or something like that...? If somebody could search the archives to look for any such reason, that would be nice. If there's no such reason, then I'd rather rename them in some way. 3) I'm not convinced about the order of material inside each chapter of Usage yet -- at the moment, I just want people to consider the division of stuff into chapters, not within each chapter. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
