[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: amores perros
Subject: Re: ls 6.7 man page bugs (unterminated bold macros)
Date: Mon, 16 Apr 2007 00:57:57 +0000

From: address@hidden
Subject: Re: ls 6.7 man page bugs (unterminated bold macros)
Date: Sun, 15 Apr 2007 18:47:01 -0600

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.

I am running on cygwin, and I don't appear to have the help2man program.
Anyway, trying "help2man<enter>" tells me it doesn't know about it.

Also, the groff macros seem buggy here -- \fR isn't resetting to roman
when in bold, and .B is affecting subsequent lines (and .R isn't undoing it),
so even the man samples aren't coming out right.

So, it may not be the ls command at all, it may be something somewhere
in the groff... ? ... man pipeline.

So it's getting way over my head, and I no longer report it as a bug
against ls or coreutils -- I think it is something more systemic, and
quite possibly due to something involving the cygwin platform.

Thanks for the info.


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

That sounds very nifty.

So, does the help2man stuff, if you have it, invoke the program
by calling it with --help, and then postprocess the results of that
into man or groff or whatever format?

Thanks to all of you for all the info and suggestions.

Interest Rates Fall Again! $430,000 Mortgage for $1,399/mo - Calculate new payment http://www.lowermybills.com/lre/index.jsp?sourceid=lmb-9632-18679&moid=7581

reply via email to

[Prev in Thread] Current Thread [Next in Thread]