Richard Kenner wrote: >> That is true, but very often the documentation is needed in two >> places: in the code and in the manual. Especially for things like >> machine constraints, flags and options. > > Yes, but the audiences are different between users who read the manual and > developers who read the code.
Richard, your argument is a distraction from the important issue at hand. Unless you posit that there is no useful way in which to generate documentation from code (and comments therein), which seems an extreme statement, then it is desirable that we have the ability to do that. Right now we don't. That's bad. I certainly don't disagree that it might be desirable for documentation for constraints might be different for end users and for GCC developers. But, there is nothing that says that both kinds of documentation might not be located physically in the code, so that when you add/delete/modify a constraint you can also easily update the documentation. And, furthermore, just because it might be desirable for the documentation to be different for end-users and compiler developers doesn't mean that it's practical for them to be different. I don't see a mob of people beating down the doors to write GCC documentation. So, I'm not inclined to let perfect be the enemy of good. If we only get one "flavor" of documentation, that's a lot better than none at all! In any case, the key issue here isn't how we should write documentation. It's whether we can use a technological measure to generate documentation if we find cases where that is desirable. It makes no sense for the FSF to artificially erect legal barriers to using a given technical approach to creating documentation. If this is really about documentation quality, the FSF could simply have a policy saying that GNU maintainers should not do this -- there is no reason to have a legal prohibition preventing people from doing it! -- Mark Mitchell CodeSourcery m...@codesourcery.com (650) 331-3385 x713
