Some small doc bugs in cygwin and tar packages

Some small doc bugs in cygwin and tar packages

[Robert Thorpe]

I recently did a fresh install of cygwin on a machine.  I noticed a couple of small issues.

The Info files for libc are included in two places, firstly in the package "cygwin-1.5.19-4.tar.bz2".  They are also in "cygwin-doc-1.4-3.tar.bz2".
One of the info files is split into three ie "libc.info", "libc.info-1" and "libc.info-2".  The other is gzipped - "libc.info.gz".
Even accounting for this the two files have slightly different contents.

In the tar package "tar-1.15.1-4.tar.bz2" there are three info files "tar.info.gz", "tar.info-1" and "tar.info-2".
"tar.info.gz" is a compressed info file containing the whole manual.  "tar.info-1" and "tar.info-2" contain the whole manual again split into two pieces.
They are misnamed, the first part of an info file should be called "tar.info", the second "tar.info-1", the third "tar.info-2" etc.
Also the tar package does not install a man page - there again, I don't know if it should.

Thanks for the good work,

Rob




--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Problem reports:       http://cygwin.com/problems.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Some small doc bugs in cygwin and tar packages

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Robert Thorpe on 5/29/2006 10:10 AM:
> 
> Also the tar package does not install a man page - there again, I don't know if it should.

That's because the upstream tar package does not provide a man page.  I'm
not really inclined to go creating man pages where upstream did not think
they were worth it; you can use 'info tar' instead.

- --
Life is short - so eat dessert first!

Eric Blake             ebb9@byu.net
volunteer cygwin tar maintainer
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.1 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFEex/984KuGfSFAYARAubtAJ9tOOL4ij12XQ8ZWXA0h5UzbKeuKQCg2BRe
UyFqTCe4yB0cGv81u1gZNhI=
=/wiT
-----END PGP SIGNATURE-----

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Problem reports:       http://cygwin.com/problems.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Some small doc bugs in cygwin and tar packages

[Robert Thorpe]

-------- Original Message --------
> From:
> Sent: Monday, May 29, 2006 8:52 PM
> To:
> Subject: Re: Some small doc bugs in cygwin and tar packages
> > > That's because the upstream tar package does not provide a man page.  I'm
> > > not really inclined to go creating man pages where upstream did not think
> > > they were worth it; you can use 'info tar' instead.
> 
> > OK, I never use man , but a lot of other people seem to.
> > I thought GNU tar was such an old program someone must have got around to 
> > writing a man page for it.
> 
...
> And while tar may be old, some of its options are new (hence it being at
> version 1.15.90 right now), and the upstream maintainer does not
> want to document each new option in the man format, since GNU
> coding standards do not require it.

I agree, I'd probably do the same thing as the tar maintainer if I were maintaining a package like that.
 
> Other packagers have different attitudes; coreutils uses a help2man script
> to convert the --help output into a reasonable man page, and the findutils
> packager actually maintains parallel man and info pages (and tries to
> fix inconsistencies between them whenever they are pointed out).

Yes.  Glibc also tries to do this too.  It doesn't work very well, some facitilies are only mentioned in the info files, others only mentioned in the man pages.
(Anyway, I'm straying from the subject).

>  But
> as packager, my attitude is to do the minimal amount of work above
> what the upstream maintainer does.

Fair enough

> > 
> > The issue with installing both .info.gz and .info- files though I think is a 
> > real bug.  Info readers should show one or the other, but I don't think there 
> > will be any gaurantee which.  It seemed to put Emacs in a tizzy on my machine 
> > anyway.
> 
> But that problem wasn't related to the tar package, so I can't
> do anything about it.

The tar packages 1.15.1-4 and 1.5.90 presently have in them...
One info file called "tar.info.gz" which is correctly formatted.
Another two info files called "tar.info-1" and "tar.info-2" which duplicate the material in "tar.info.gz".  These are not named correctly, the first should be "tar.info" and the second "tar.info-1"
I think there should only be one info file, it doesn't matter what sort, and it should be named in the conventional way.

(The cygwin-doc files are similar, but that's a separate issue)

Sorry for breaking mailing list rules.

Thanks,
Rob





--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Problem reports:       http://cygwin.com/problems.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: Some small doc bugs in cygwin and tar packages

[Eric Blake]

http://cygwin.com/acronyms/#PPIOSPE - forwarding to the list

http://cygwin.com/acronyms/#TOFU - reformatted

> 
> -------- Original Message --------
> > From: Eric Blake <ebb9 AT byu DOT net>
                          ^^^^   ^^^^^

http://cygwin.com/acronyms/#PCYMTNQREAIYR - raw email munged

> > That's because the upstream tar package does not provide a man page.  I'm
> > not really inclined to go creating man pages where upstream did not think
> > they were worth it; you can use 'info tar' instead.

> OK, I never use man , but a lot of other people seem to.
> I thought GNU tar was such an old program someone must have got around to 
> writing a man page for it.

Have you ever written a man page?  The syntax is horrendous, compared
to texinfo.  Furthermore, texinfo has the advantage that it works for
both straight text (info, html, and even man pages, if you get the right
filter) and printed manuals (dvi, ps, pdf) from the same source file; whereas
with troff input (aka man pages) do not render well in other formats.

And while tar may be old, some of its options are new (hence it being at
version 1.15.90 right now), and the upstream maintainer does not
want to document each new option in the man format, since GNU
coding standards do not require it.

Other packagers have different attitudes; coreutils uses a help2man script
to convert the --help output into a reasonable man page, and the findutils
packager actually maintains parallel man and info pages (and tries to
fix inconsistencies between them whenever they are pointed out).  But
as packager, my attitude is to do the minimal amount of work above
what the upstream maintainer does, as opposed to Debian's policy of
making every package consistent, even if that means Debian writes
their own man pages for packages like tar.

> 
> The issue with installing both .info.gz and .info- files though I think is a 
> real bug.  Info readers should show one or the other, but I don't think there 
> will be any gaurantee which.  It seemed to put Emacs in a tizzy on my machine 
> anyway.

But that problem wasn't related to the tar package, so I can't
do anything about it.

> 
> Thanks
> Rob

-- 
Eric Blake
volunteer cygwin tar maintainer

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Problem reports:       http://cygwin.com/problems.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/