On Wed, Feb 27, 2013 at 2:42 PM, Sebastian Pipping <invalid.nore...@gnu.org> wrote: > Paul and Philipp,
Side note: I should make clear that I am not committer to GNU make and do not speak for the project. I'm just a contributer to the lists, answering questions where I can. > Daniel has a valid point here. You could be a lot more welcoming on this > case, why so hard on him? I hit the very same thing myself some time ago, > just forgot to speak up myself. That documentation "bug" is the reason meta > programming in GNU make took my too starts, rather than one. IMO, the suggestion that was proposed would reduce the overall usability of the manual and increase the confusion. I seen it tried in multiple ways** in other open source projects (and at my day job) and the results were never complete (there were nuances left out), took a large amount of effort, and always made a small set of people happy and a much larger set of people unhappy. I'll note that glibc, which has a much larger development group including commercial funding for several, doesn't describe when something was added or changed in its manual. gcc's manual only mentions inter-version changes for the -fabi-version option (whose whole purpose is inter-version support) and for a single specific removed feature, with no comment when describing the multiple new options and extensions. (Did the manual to your car or bike or computer include comments throughout it describing how this year's model is different from the previous years?) If you have an example of a manual that does that and does it *well*, without compromising readability, I would be glad to be wrong and interested it seeing it so that I can see how they pulled it off. If the GNU website were to require you to select the version of make you wanted to see the documentation for, I think that would be a reasonable 'solution'. Perhaps a layout like http://gcc.gnu.org/onlinedocs/ could be done without too much complexity. > While I appreciate progress in GNU make, version 3.82 has produced costs over > 3.81 to many parities, see the list of bugs related to 3.82-caused breakage in > Gentoo Linux alone: <https://bugs.gentoo.org/show_bug.cgi?id=331977>. That was 2 years ago. When does it end? When the last Linux distributor's Long Term Support version is off it? They get to choose how long that cost is imposed on this project? > To summarize: people need all the support with the transition and with > understanding the differences betwen 3.81 and 3.82 they can get. That information is provided in the form of the NEWS file. Perhaps those should be more easily obtainable via the website, but spreading it throughout the manual is not, IMNSHO, a solution. > Daniel could have prepared a patch for the docs by now and be motivated to > do more later, > if you had instructed him about it. The good part about it: you may have a > second chance. Don't let it pass. Or you could try doing that yourself. No one needs my approval to do it, or to put it on Daniel, and Paul could easily decide that your patch is an improvement and check it in. (Oops, guess I screwed up my second chance.) Philip Guenther _______________________________________________ Bug-make mailing list Bug-make@gnu.org https://lists.gnu.org/mailman/listinfo/bug-make