Re: ls 6.7 man page bugs (unterminated bold macros)

[Bob Proulx]

amores perros wrote:
> >From: Eric Blake
> >Thanks for the report.  However, the man page is generated using the
> >'help2man' tool from the 'ls --help' output, so you may want to
> >investigate whether these are bugs in that tool, rather than in ls.
> 
> If you're inviting me to take ownership of the bug, I'm afraid I must
> decline. I did try to look at the current coreutils source, as I mentioned,
> but the cvs viewer wasn't working -- and even if it was, I wouldn't have
> the autotools skill to be a package maintainer of something like that.

I read it as an invitation but one to look at the 'help2man' source,
not the coreutils source.  The help2man program is a perl script that
generates the man pages.  Making improvements there would improve all
of the generated man pages for the entire project, and if made in the
upstream help2man, would improve all projects that used it.

  http://git.sv.gnu.org/gitweb/?p=coreutils.git;a=blob;f=man/help2man;hb=HEAD

> >Manually writing man pages tends to be a pretty harsh way to do things.
> >Man pages are relatively obsolete, and not required by the GNU Coding
> >Standards.  These days, it is easier to generate a man page using an
> >automated tool that parses input from another format.
> 
> I am not writing them due to standards, but due to user requests,
> actually -- users are more fun to please than standards :)

I think that many of us agree that man pages are very useful.  But
keeping documentation in sync with the program is tedious if they are
separate.  By generating the documentation from the program they are
guaranteed to be in sync at all times after that point.  And it also
means that the online documentation is kept up to date just by
itself.  Those are really good things because the --help output is
then generally much more useful than it would be otherwise.

Many of us have moved away from writing man pages to writing program
online help that is automatically converted into a man page.  The end
goal is the same but the method is different.

Bob