svn commit: r284198 - head/bin/ls

[Bryan Drewery]

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 at 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