From owner-freebsd-current@freebsd.org Fri Apr 6 03:00:58 2018 Return-Path: Delivered-To: freebsd-current@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 45452F99DE2 for ; Fri, 6 Apr 2018 03:00:58 +0000 (UTC) (envelope-from sgk@troutmask.apl.washington.edu) Received: from troutmask.apl.washington.edu (troutmask.apl.washington.edu [128.95.76.21]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "troutmask", Issuer "troutmask" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id C601A80030; Fri, 6 Apr 2018 03:00:57 +0000 (UTC) (envelope-from sgk@troutmask.apl.washington.edu) Received: from troutmask.apl.washington.edu (localhost [127.0.0.1]) by troutmask.apl.washington.edu (8.15.2/8.15.2) with ESMTPS id w3630ujG044831 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Thu, 5 Apr 2018 20:00:56 -0700 (PDT) (envelope-from sgk@troutmask.apl.washington.edu) Received: (from sgk@localhost) by troutmask.apl.washington.edu (8.15.2/8.15.2/Submit) id w3630uV1044830; Thu, 5 Apr 2018 20:00:56 -0700 (PDT) (envelope-from sgk) Date: Thu, 5 Apr 2018 20:00:56 -0700 From: Steve Kargl To: Benjamin Kaduk Cc: freebsd-current Subject: Re: clang manual page? Message-ID: <20180406030056.GA44536@troutmask.apl.washington.edu> Reply-To: sgk@troutmask.apl.washington.edu References: <20180405223852.GA43120@troutmask.apl.washington.edu> <20180406001514.GA43793@troutmask.apl.washington.edu> <20180406005624.GB43998@troutmask.apl.washington.edu> <20180406011149.GF80088@mit.edu> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20180406011149.GF80088@mit.edu> User-Agent: Mutt/1.9.2 (2017-12-15) X-BeenThere: freebsd-current@freebsd.org X-Mailman-Version: 2.1.25 Precedence: list List-Id: Discussions about the use of FreeBSD-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 06 Apr 2018 03:00:58 -0000 On Thu, Apr 05, 2018 at 08:11:50PM -0500, Benjamin Kaduk wrote: > On Thu, Apr 05, 2018 at 05:56:24PM -0700, Steve Kargl wrote: > > I never said that you said it was in base. I'm noting that > > referring a user to a non-existent manual page is of little > > help. In fact, your 7 word response is an affirmation that > > the tools supplied in base should be properly documented. > > It would probably be more useful to file explicit bug reports > (or even write a patch) about missing or poor documentation, than > to proffer passive-aggressive inquiries on public mailing lists > that merely suggest but do not explicitly state that the > documentation is deficient. > There is nothing passive nor aggressive in asking about how to use the tools supplied in base because its accompanying documentation is substantially lacking in quality. It should be the responsibility of the individual (or individuals) who import new software into base to ensure that it has proper documentation. Of course, the assumption is that this individual has (or these individuals have) a familiarity with the software, which should facilitate writing said documentation. This started 8 year 10 months ago when clang pre-2.8 was committed without a manpage. The initial version of clang.1 appeared 7 year 6 months ago. FreeBSD is now at clang 6.0.0. I fully anticipate that the next import of clang will again have poor documentation. To preempt a retort about "stop complaining and contribute a fix", I'll note that all of my previous contributions that are in base have been accompanied by documentation. -- Steve