Re: [bug #38433] Example for "eval" in documentation contains error with "define"

[Philip Guenther]

On Wed, Feb 27, 2013 at 2:42 PM, Sebastian Pipping
<address@hidden> 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