Re: coreutils: 'touch --date=STRING' docs don't tell what format STRING is.

[Bob Proulx]

A. Costa wrote:
> repopen 363011 !

How do you suggest that we resolve this issue?

> M. Stone wrote:
> > The info documentation does indicate that the "Date input formats"
> > can be used for -d. The difficulty in finding that documentation
> > continues to be the broken install-info program. If you use "info
> > coreutils" and drill down to the date command, you will find it.

Note for readers that the upstream documentation (and Mike has applied
as a Debian patch) has recently been changed to saying this

  info coreutils "date invocation"

instead now to help find the appropriate documentation.  Hopefully
this will help work around the previous problems seen in Debian with
finding info documentation pages.

> Consider how much less useful a dictionary would be if its pages were
> printed in random order.  Data in an unexpected location ('date' info)
> is as much a bug as no data.

The official documentation for GNU is the info documentation format.
Man pages are provided on a best effort basis.  For coreutils they are
currently generated from the online command --help output so that the
information is in sync with the command.  The man page directs the
user to the info docs for all of the details.  As such the info
documentation is not an unexpected location.  The info documentation
is where you should be looking for this information.

It is unfortunate that there have been problems on some systems of the
info system not being able to locate the files properly and falling
back to the man page.  That issue is documented in other bug reports.

> Users expect either 'info touch' or 'man touch' to have it. Please
> merge this bug with that 'install-info' bug if it's not a
> 'coreutils' problem.

The install-info problem is not a coreutils problem.  But if there are
suggestions to improve the documentation of coreutils then that does
fall within the coreutils umbrella.

> OTOH, it's almost 2 years unfixed, and I'd put odds it'll take two
> more years.  The expedient kludge would be to add a little man page
> text with an example.  A man page ought to define its own parameters
> anyway, even if the info page has more detail.

The problem is that the date format takes *eleven pages* of
documentation in the gnulib info system to describe it.  Trying to
maintain that in parallel in the man pages is a duplication of work
and an increase in upstream maintenance.  If you have a suggestion for
a concise addition to the manpages then I am sure that it would be
considered.

Bob