Han-Wen Nienhuys <hanw...@gmail.com> writes: > On Fri, Mar 13, 2009 at 8:50 AM, David Kastrup <d...@gnu.org> wrote: > >> It is a bit disappointing since the info documentation with images is >> essential for really getting moving smoothly with Lilypond, and the >> procedure for producing them is so broken or obfuscate that none, I >> repeat none of _any_ lilypond precompilated versions that I know of >> carries them, and there is no way even a clever user could be >> expected to arrive at usable docs. > > At the risk of putting more gasoline on the fire: I have never found > the info docs anything of a priority, not when Jan started it (back in > 2003 or whenever it was) and it was always Jan who had to fix build > errors in the process. Given that nobody (besides you) else ever > complained about the info pages leads me to believe that in reality > very few people care about info pages with images.
Very few people _know_ about them. I don't think that there are more than a dozen Emacs developers that actually know that Info supports images. The intersection with Lilypond users will be minuscule, and that is partly a chicken-and-egg problem: if you can't guess that Emacs info can show images _and_ you can't guess that Lilypond can produce images with info, why would you ask or complain? That's why Lilypond's makefile info targets should make it really hard to get info pages without images. Because people will totally be surprised by the presence of images. They don't expect them. Consequently, they won't go looking for them. If they are on the plate, the demand will voice itself. > There are other data that support this too: > > in March, we had 1689 windows downloads, 122 mac, and 107 linux ones > on lilypond.org. The latter number may be skewed because some people > will get lilypond through their distributor, but still. I believe > that the average windows user does not know what info is, and much > less has a viewer for it. Sure. The point is that HTML is a pain to navigate. It does not have structural movement. It does not have indexes. Browsers are slow. It does not have document-encompassing search. And that is the reason info has not been retired within Emacs. At some distant point of time in the future, the format might get changed to HTML (with structural tags), and with a special reader that gets along with a special HTML subset. > Speaking from personal experience, I tend to access documentation for > whatever I do by searching Google. I suspect this holds for many more > people. I have to bash that out of people's head for some of my project: if a project has a visible history of 15 years, people tend to find pages with 10-year old documentation of a version that worked and installed completely differently. Yes, I do receive occasional bug reports based on Google searches of outdated ill-advised pages from a computer account abandoned 10 years ago, when the software comes with very diligently and completely, painstakingly polished instructions. It makes life easier for developers if they can get the users hooked on the actual current documentation instead of search engine wisdom. >> It is my opinion that Lilypond developers are shooting themselves >> quite unnecessarily in the foot by the large discrepancy between the >> high quality of the documentation and the probability of actually >> getting to see it after a finite amount of effort. > > I think the lilypond doc developers are focusing on getting excellent > HTML documentation, and I think that is a smart use of resources. I was not suggesting replacing the HTML. I am not too sure about the HTML targets being produced and organized in the most obvious manner, but in contrast to the imaged info, people _expect_ this sort of doc. -- David Kastrup _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel