Subject: Re: Duplicate documentation of MK* make options
To: None <firstname.lastname@example.org>
From: Valeriy E. Ushakov <email@example.com>
Date: 12/21/2005 10:05:40
Hubert Feyrer <firstname.lastname@example.org> wrote:
> [moved from tech-x11]
You should have warned about that.
> On Tue, 20 Dec 2005, Hubert Feyrer wrote:
>> What's the way to enable/disable IPv6 in NetBSD?
>> According to src/share/mk/bsd.own.mk it's MKINET6=no, but
>> .../bsd.x11.mk checks for USE_INET6!=no.
>> Maybe that should be changed? (s/USE_INET6/MKINET6/)
> I have sent a pullup to get the IPv6 variables into bsd.README.
I requested releng to put it on hold. That change is bad. It was
done hastily and without proper consideration.
> Now there's another (even worse, IMHO) issue: many of those
> variables are ALSO documented in mk.conf.4. Right now I dare saying
> that bsd.README is more complete than mk.conf.4, what shall we do -
> try to maintain redundant documentation, or merge into one place?
> Which one?
Nit pick: mk.conf.5
I think that properly converting bsd.README into a set of cat5 pages
is the right way to do it.
> What place is more likely to get maintained by our documentation-shy
> developers? :)
I appreciate your recent drive to improve the documentation, but
randomly yanking pieces of a readme file into an unrelated man page
doesn't qualify as a good documentation practice.
An obvious example is NOxxx vars. They were underdocumented in
bsd.README already, but at least they were underdocumented in the
right place. NOxxx vars are intended for individual makefiles, e.g. a
program w/out a man page would set NOMAN to indicate that.
"NOxxx" text cleary says "Not intended for users.", yet you have moved
that paragraph to mk.conf(5) - a manual page for *system wide* mk
configuration that *users* can do.
email@example.com | Zu Grunde kommen
http://snark.ptc.spbu.ru/~uwe/ | Ist zu Grunde gehen