From owner-svn-src-all@FreeBSD.ORG Mon Jun 15 16:49:36 2015 Return-Path: Delivered-To: svn-src-all@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 949998F9; Mon, 15 Jun 2015 16:49:36 +0000 (UTC) (envelope-from bdrewery@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:1900:2254:206c::16:87]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 75D9CEB7; Mon, 15 Jun 2015 16:49:36 +0000 (UTC) (envelope-from bdrewery@FreeBSD.org) Received: from mail.xzibition.com (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.9/8.14.9) with ESMTP id t5FGnahU016089; Mon, 15 Jun 2015 16:49:36 GMT (envelope-from bdrewery@FreeBSD.org) Received: from mail.xzibition.com (localhost [172.31.3.2]) by mail.xzibition.com (Postfix) with ESMTP id 1828E9993; Mon, 15 Jun 2015 16:49:36 +0000 (UTC) X-Virus-Scanned: amavisd-new at mail.xzibition.com Received: from mail.xzibition.com ([172.31.3.2]) by mail.xzibition.com (mail.xzibition.com [172.31.3.2]) (amavisd-new, port 10026) with LMTP id UIeJ-KFjfRaM; Mon, 15 Jun 2015 16:49:33 +0000 (UTC) Message-ID: <557F021C.1000509@FreeBSD.org> DKIM-Filter: OpenDKIM Filter v2.9.2 mail.xzibition.com 10D83998B Date: Mon, 15 Jun 2015 12:49:32 -0400 From: Bryan Drewery Organization: FreeBSD User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:31.0) Gecko/20100101 Thunderbird/31.7.0 MIME-Version: 1.0 To: Steve Kargl , Craig Rodrigues CC: Marcel Moolenaar , Marcel Moolenaar , "src-committers@freebsd.org" , "svn-src-all@freebsd.org" , "svn-src-head@freebsd.org" Subject: Re: svn commit: r284198 - head/bin/ls References: <201506100127.t5A1RdX6051959@svn.freebsd.org> <20150612204309.11dd3391@kan> <20150613024916.GA98218@troutmask.apl.washington.edu> <1434208622.1415.57.camel@freebsd.org> <557C661F.8080104@freebsd.org> <860017ED-D754-450C-865D-2D81A30C2212@xcllnt.net> <20150614002640.GA2746@troutmask.apl.washington.edu> <20150614012924.GA2965@troutmask.apl.washington.edu> In-Reply-To: <20150614012924.GA2965@troutmask.apl.washington.edu> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 15 Jun 2015 16:49:36 -0000 On 6/13/15 9:29 PM, Steve Kargl wrote: > On Sat, Jun 13, 2015 at 05:40:59PM -0700, Craig Rodrigues wrote: >> On Sat, Jun 13, 2015 at 5:26 PM, Steve Kargl < >> sgk@troutmask.apl.washington.edu> wrote: >>> >>> Given the horrid state of the manpages, which I showed >>> in March, one can only wonder about the internals of >>> the libxo itself. >>> >> >> Are you talking about this comment you made? >> https://lists.freebsd.org/pipermail/freebsd-current/2015-March/054899.html >> >> I can't make heads or tails of what you wrote, other than you seemed very >> angry. >> > > I wasn't very angry. I'm simply pointing out that the libxo > manpages, which should document what libxo is/does, are > horrible documentation. If the quality of the manpages > matches the quality of library, and the brokeness that > we have been witnesses bears this out, should be questioned. > > % cd src/contrib/libxo/libxo > % grep Nd *.3 | grep formatted > xo_attr.3:.Nd emit formatted output based on format string and arguments > xo_create.3:.Nd emit formatted output based on format string and arguments > xo_emit.3:.Nd emit formatted output based on format string and arguments > xo_finish.3:.Nd emit formatted output based on format string and arguments > xo_flush.3:.Nd emit formatted output based on format string and arguments > xo_open_list.3:.Nd emit formatted output based on format string and arguments > xo_set_allocator.3:.Nd emit formatted output based on format string and arguments > xo_set_flags.3:.Nd emit formatted output based on format string and arguments > xo_set_info.3:.Nd emit formatted output based on format string and arguments > xo_set_style.3:.Nd emit formatted output based on format string and arguments > xo_set_writer.3:.Nd emit formatted output based on format string and arguments > > Do you really believe that the Nd entries for these manpages are > correct? > I also found that from simple 'man ls' (etc) there is no real mention of what --libxo even is or how it works. Following the manpage cross-references leads me to have to go to a webpage to see what params --libxo even takes. The --libxo flag needs much more documentation in these manpages. -- Regards, Bryan Drewery