Re: [bug #38433] Example for eval in documentation contains error with define
On Wed Feb 27 14:07:42 2013, guent...@gmail.com (Philip Guenther) wrote: Meanwhile, other people complain that the docs are too long; adding this feature was added in 3.8x throughout the guide just makes it longer and harder to read. It's not a costless addition. I completely disagree. Length is not an issue for documentation these days; reliability is. Right now I don't know whether documentation for make I find online matches the version I'm using. The documentation for the program on your box is on your box. WTP? It's usually easier to use Google these days. -- Reinier ___ Bug-make mailing list Bug-make@gnu.org https://lists.gnu.org/mailman/listinfo/bug-make
Re: [bug #38433] Example for eval in documentation contains error with define
On Wed Feb 27 17:02:03 2013, guent...@gmail.com (Philip Guenther) wrote: 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. Can you list one or two examples? Doesn't the amount of pain depend on how it's done? E.g. I can imagine that keeping a set of crosslinking footnotes of the form 'this has changed in version x, see the corresponding place in the x-1 docs' is a lot easier than trying to document several versions within the same document. [...] (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?) The problem is that people find documentation elsewhere and need to be aware which version of the bike or model it applies to. You can argue the issue rightfully belongs on someone else's plate, but the fact is that lots of make users appear to lose a lot of time over this, especially between 3.81 and 3.82 (I have been bitten by it as well). The prime purpose of documentation is to keep users from wasting time on figuring out things that can be looked up instead. -- Reinier ___ Bug-make mailing list Bug-make@gnu.org https://lists.gnu.org/mailman/listinfo/bug-make
Re: [bug #38433] Example for eval in documentation contains error with define
On Wed, Feb 27, 2013 at 11:25 AM, Daniel Wagenaar invalid.nore...@gnu.org wrote: The example for the eval function in the documentation at http://www.gnu.org/software/make/manual/html_node/Eval-Function.html contains a syntax error that causes the example to fail quietly. The problem is in the line define PROGRAM_template = This line should not have = at the end. No, that line is perfectly correct. The problem is that you're still running version 3.81, which was obsoleted almost 3 years ago. Upgrade to 3.82. Or use info make to read the documentation that's installed on your system and therefore matches the version you're running. Philip Guenther ___ Bug-make mailing list Bug-make@gnu.org https://lists.gnu.org/mailman/listinfo/bug-make
Re: [bug #38433] Example for eval in documentation contains error with define
On 02/27/2013 11:30 AM, Philip Guenther wrote: On Wed, Feb 27, 2013 at 11:25 AM, Daniel Wagenaar invalid.nore...@gnu.org wrote: The example for the eval function in the documentation at http://www.gnu.org/software/make/manual/html_node/Eval-Function.html contains a syntax error that causes the example to fail quietly. The problem is in the line define PROGRAM_template = This line should not have = at the end. No, that line is perfectly correct. The problem is that you're still running version 3.81, which was obsoleted almost 3 years ago. Upgrade to 3.82. Or use info make to read the documentation that's installed on your system and therefore matches the version you're running. Philip Guenther I appreciate your correction, but I still feel that the documentation on the website would be more helpful if it at least mentioned that older versions of make fail quietly when there is a = at the end of the line. The reason is that make v. 3.81 is still in very wide use. For instance, it is part of Ubuntu 12.04-LTS as well as Mint 14. - Daniel Wagenaar ___ Bug-make mailing list Bug-make@gnu.org https://lists.gnu.org/mailman/listinfo/bug-make
Re: [bug #38433] Example for eval in documentation contains error with define
On Wed, Feb 27, 2013 at 1:56 PM, Daniel Wagenaar d...@caltech.edu wrote: I appreciate your correction, but I still feel that the documentation on the website would be more helpful if it at least mentioned that older versions of make fail quietly when there is a = at the end of the line. The reason is that make v. 3.81 is still in very wide use. For instance, it is part of Ubuntu 12.04-LTS as well as Mint 14. That sounds like a bug in Ubuntu. Or maybe it's just a consequence of the choice of selecting a Long Term Support release. Meanwhile, other people complain that the docs are too long; adding this feature was added in 3.8x throughout the guide just makes it longer and harder to read. It's not a costless addition. The documentation for the program on your box is on your box. WTP? Philip ___ Bug-make mailing list Bug-make@gnu.org https://lists.gnu.org/mailman/listinfo/bug-make
Re: [bug #38433] Example for eval in documentation contains error with define
On 02/27/2013 02:07 PM, Philip Guenther wrote: On Wed, Feb 27, 2013 at 1:56 PM, Daniel Wagenaar d...@caltech.edu wrote: I appreciate your correction, but I still feel that the documentation on the website would be more helpful if it at least mentioned that older versions of make fail quietly when there is a = at the end of the line. The reason is that make v. 3.81 is still in very wide use. For instance, it is part of Ubuntu 12.04-LTS as well as Mint 14. That sounds like a bug in Ubuntu. Or maybe it's just a consequence of the choice of selecting a Long Term Support release. Meanwhile, other people complain that the docs are too long; adding this feature was added in 3.8x throughout the guide just makes it longer and harder to read. It's not a costless addition. The documentation for the program on your box is on your box. WTP? Philip I suppose the fundamental problem is make silently failing on illegal input. - Daniel ___ Bug-make mailing list Bug-make@gnu.org https://lists.gnu.org/mailman/listinfo/bug-make
Re: [bug #38433] Example for eval in documentation contains error with define
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
Re: [bug #38433] Example for eval in documentation contains error with define
On Wed, Feb 27, 2013 at 5:02 PM, Philip Guenther guent...@gmail.com wrote: 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. Likewise. IMO, the suggestion that was proposed would reduce the overall usability of the manual and increase the confusion. I think you and the others in the nay camp may be being a bit unfair. As far as I can see, nobody has proposed (in this thread) that the entire manual be reworked to note the version in which each feature appeared. You're absolutely right that that would stink but it's a straw man. The proposal, as I understand it, is to add a note about this particular incompatibility because of the mysterious, silent way it fails. I think any of us who've been reading this list for a long time can attest that it's one of the more common problems that people stumble over. It's a golden oldie, so I don't know why it would be so bad to add a sentence for it. There may even be a couple of other cases that could get similar treatment. It doesn't have to become a slippery slope. 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. Another nice example is the Python docs ( http://docs.python.org/2/index.html). Notice the dropdown at the top left where you get to pick the version you care about. David Boyce ___ Bug-make mailing list Bug-make@gnu.org https://lists.gnu.org/mailman/listinfo/bug-make
