[RFC] 1.7 Packaging: Documentation

[RFC] 1.7 Packaging: Documentation

[Yaakov (Cygwin Ports)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

A few ideas about package documentation for 1.7:

1) Info pages

Per a recent discussion on the main list, GNU info 'dir' will be managed
solely by _update-info-dir.  Packagers should no longer use postinstall
scripts for this purpose; the next version of cygport will have the
appropriate changes.

2) which docs to package

There has been an unofficial list of "standard" docs which are installed
into the docdir.  I think that among these, ABOUT-NLS and INSTALL should
be removed from the default list, as they generally serve no purpose for
a binary package.

As for license files, do we really need to install hundreds of copies of
the same license?  IANAL, so does a symlink to the copy in base-files
suffice, or is the mere presence of the latter enough?

3) where to install docs

Could we remove the versioning from the docdir and Cygwin README, IOW:

/usr/share/doc/foo/
/usr/share/doc/Cygwin/foo.README

Since only one version of foo can be installed at a time, this shouldn't
cause any difficulties, and would in fact alleviate several:

a) This is generally the default, and changing this for
non-autotool-based packages often requires a patch or an extra step in
src_install().

b) This means that the docdir isn't moving with every version bump,
which currently makes it a chore when e.g. bookmarking HTML docs for
viewing in your favorite browser (either Win32 or Cygwin).

c) Several programs, e.g. IDEs, include documentation browsers, but they
need to be told where to find the docs; hence a version bump currently
requires changing the settings of that program.

d) In at least one case (KDevelop), these external docdirs are
*hard-coded* into the program with a configure switch!

4) setup.hint

cgf confirmed recently that ldesc: is still unused.  Do we seriously
intend to ever use it, or should we forget it?


Yaakov
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEAREIAAYFAkilM68ACgkQpiWmPGlmQSNKIwCgtjeOHvheQr2XRkEHA5gKnqU2
n/UAoJFbjkYPmug+0G6eHj3ny6z9HnSC
=J926
-----END PGP SIGNATURE-----

Re: [RFC] 1.7 Packaging: Documentation

[Eric Blake]

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

According to Yaakov (Cygwin Ports) on 8/15/2008 1:43 AM:
> 
> As for license files, do we really need to install hundreds of copies of
> the same license?  IANAL, so does a symlink to the copy in base-files
> suffice, or is the mere presence of the latter enough?

I would prefer the symlink.  It's still nice to be able to read a
per-package license by following the symlink.

> 
> 3) where to install docs
> 
> Could we remove the versioning from the docdir and Cygwin README, IOW:
> 
> /usr/share/doc/foo/
> /usr/share/doc/Cygwin/foo.README

I like the idea.  It may be a while, though before all the packages have
caught up, so we'll see both types in the directory.  I'm assuming that if
you change cygport to help with this, the job for most of my packages will
be as simple as rebuilding.

- --
Don't work too hard, make some time for fun as well!

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

iEYEARECAAYFAkilcIIACgkQ84KuGfSFAYDrxgCgouzcIe6y8ycq68Ig7A211tlJ
n+kAn2FLS631LRhneJsefSFYzcR0Y6S2
=sisO
-----END PGP SIGNATURE-----

Re: [RFC] 1.7 Packaging: Documentation

[Reini Urban]

Eric Blake schrieb:
> According to Yaakov (Cygwin Ports) on 8/15/2008 1:43 AM:
>> As for license files, do we really need to install hundreds of copies of
>> the same license?  IANAL, so does a symlink to the copy in base-files
>> suffice, or is the mere presence of the latter enough?
> 
> I would prefer the symlink.  It's still nice to be able to read a
> per-package license by following the symlink.
> 
>> 3) where to install docs
>>
>> Could we remove the versioning from the docdir and Cygwin README, IOW:
>>
>> /usr/share/doc/foo/
>> /usr/share/doc/Cygwin/foo.README

docdir without version ++

But for the README I'd prefer the version.
Dummy users might have troubles finding out the installed version. 
Hardly anyone knows about /etc/setup/installed.db

I would also like a generated .lst MANIFEST file for the binary packages 
in the public setup dir.
-- 
Reini Urban
http://phpwiki.org/  http://murbreak.at/

Re: [RFC] 1.7 Packaging: Documentation

[Christopher Faylor]

On Fri, Aug 15, 2008 at 07:17:28PM +0200, Reini Urban wrote:
> Eric Blake schrieb:
>> According to Yaakov (Cygwin Ports) on 8/15/2008 1:43 AM:
>>> As for license files, do we really need to install hundreds of copies of
>>> the same license?  IANAL, so does a symlink to the copy in base-files
>>> suffice, or is the mere presence of the latter enough?
>> I would prefer the symlink.  It's still nice to be able to read a
>> per-package license by following the symlink.
>>> 3) where to install docs
>>>
>>> Could we remove the versioning from the docdir and Cygwin README, IOW:
>>>
>>> /usr/share/doc/foo/
>>> /usr/share/doc/Cygwin/foo.README
>
> docdir without version ++
>
> But for the README I'd prefer the version.
> Dummy users might have troubles finding out the installed version. Hardly 
> anyone knows about /etc/setup/installed.db

But everyone should know about cygcheck.  That's what we should be pushing.

cgf

Re: [RFC] 1.7 Packaging: Documentation

[Charles Wilson]

Reini Urban wrote:
> But for the README I'd prefer the version.
> Dummy users might have troubles finding out the installed version.
> Hardly anyone knows about /etc/setup/installed.db

cygcheck -cd foo

> I would also like a generated .lst MANIFEST file for the binary packages
> in the public setup dir.

cygcheck -l foo

--
Chuck

Re: [RFC] 1.7 Packaging: Documentation

[Yaakov (Cygwin Ports)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

cgf and/or Corinna, could I get your official opinion on these, so that
I can proceed with the necessary changes to cygport trunk if agreed:

This one gets into the legal category:

> As for license files, do we really need to install hundreds of copies of
> the same license?  IANAL, so does a symlink to the copy in base-files
> suffice, or is the mere presence of the latter enough?

This one changes the package layout slightly, for which I could make a
patch to setup.html to match:

> Could we remove the versioning from the docdir and Cygwin README, IOW:
> 
> /usr/share/doc/foo/
> /usr/share/doc/Cygwin/foo.README


Yaakov
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEAREIAAYFAkiy7lcACgkQpiWmPGlmQSMTVgCgotBMqK3V/kbqVl9WTBKTCQ3d
LXQAoIB2l3NlZEEean++OHXBixt66R3k
=gZX8
-----END PGP SIGNATURE-----

Re: [RFC] 1.7 Packaging: Documentation

[Christopher Faylor]

On Mon, Aug 25, 2008 at 12:39:35PM -0500, Yaakov (Cygwin Ports) wrote:
>-----BEGIN PGP SIGNED MESSAGE-----
>Hash: SHA256
>
>cgf and/or Corinna, could I get your official opinion on these, so that
>I can proceed with the necessary changes to cygport trunk if agreed:
>
>This one gets into the legal category:
>
>> As for license files, do we really need to install hundreds of copies of
>> the same license?  IANAL, so does a symlink to the copy in base-files
>> suffice, or is the mere presence of the latter enough?

My linux systems have a bunch of "LICENSE*" files in /usr/share/doc.  I
think it is safer to leave them there, even though no one ever reads
them.

cgf

Re: [RFC] 1.7 Packaging: Documentation

[Yaakov (Cygwin Ports)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Christopher Faylor wrote:
> My linux systems have a bunch of "LICENSE*" files in /usr/share/doc.  I
> think it is safer to leave them there, even though no one ever reads
> them.

Fine.  What about the docdir change?


Yaakov

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEAREIAAYFAkizBxIACgkQpiWmPGlmQSMaRgCfcEXHU309ovoQJf9TvLBRG8Gr
ih0AnjSTtQCTyO9SYZ9MKOi9GNWoHGc2
=8BCm
-----END PGP SIGNATURE-----