Re: Issue 1526 in lilypond: Building only English docs

[lilypond]

Comment #14 on issue 1526 by address@hidden: Building only  
English docs
http://code.google.com/p/lilypond/issues/detail?id=1526

I agree with #3 as a general rule.  I agree that #1 is easily solved by  
just typing more and that's no issue for unix people; I'm not certain that  
I agree that this is a non-issue for windows users.

As for #2, I benchmarked this on my core2quad desktop (running a single  
thread, though) for "recompiling" with no changes:

$ time make doc
...
real    1m50.679s
user    1m36.030s
sys     0m16.309s

$ time ../scripts/auxiliar/doc-section.sh learning tutorial
...
real    0m0.963s
user    0m0.948s
sys     0m0.176s


When I make a single typo fix (in normal text, not @lilypond) to  
tutorial.itely, I get this:
$ time make doc
...
real    2m54.828s
user    2m38.502s
sys     0m12.801s


$ time ../scripts/auxiliar/doc-section.sh learning tutorial
real    0m0.957s
user    0m0.940s
sys     0m0.156s


It's a pretty hard sell to tell people "just use the build system; so what  
if it takes 182 times as long".  Admittedly I could cut down the compile  
time my using multiple threads, but I don't think that's an open in the  
open-source virtualbox (which is our officially recommended build  
environment for osx and windows users).  I'd expect the difference to be  
even more extreme inside the virtualized environment.

I should clarify that I don't like doc-section.sh, I've never liked it;  
it's the worst kind of "alternate build system" hack... but mao, just look  
at those numbers.  3 minutes vs. less than 1 second ?!  I hadn't realized  
the difference was that extreme.  I'm sorely tempted to spend some time to  
fix up a few bugs in doc-section.sh and then make it the official method  
for doc editors to work.


I've skimmed some articles saying that recursive make is terrible and  
projects should always use non-recursive make with included files.  I don't  
know how invasive a change that would be, nor whether I'm correctly  
remembering those articles, nor whether those articles were correct in the  
first place.  But I think that doc editors have a point when they object  
to "make doc".