Bug 196281 - (php-manual-en) Review Request: php-manual-en - English language PHP manual
Review Request: php-manual-en - English language PHP manual
Status: CLOSED NEXTRELEASE
Product: Fedora
Classification: Fedora
Component: Package Review (Show other bugs)
rawhide
All Linux
medium Severity medium
: ---
: ---
Assigned To: Christopher Stone
Fedora Package Reviews List
:
Depends On:
Blocks: FE-ACCEPT
  Show dependency treegraph
 
Reported: 2006-06-22 09:20 EDT by Tim Jackson
Modified: 2007-11-30 17:11 EST (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2006-08-19 07:32:31 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Tim Jackson 2006-06-22 09:20:53 EDT
Spec URL: http://www.timj.co.uk/linux/specs/php-manual-en.spec
SRPM URL: http://www.timj.co.uk/linux/srpms/php-manual-en-20060527-1.src.rpm
Description: A documentation-only package containing the English language version of the PHP manual, split into a file per chapter.

See thread starting:
https://www.redhat.com/archives/fedora-extras-list/2006-May/msg00237.html

for a discussion of a number of issues relating to this package.

A few quick points:

- rpmlint says:

W: php-manual-en invalid-license Open Publication License v1.0

I think this is OK, since the above string is the correct and most accurate description of the package license

- Arguably the package should be php-manual-en-us, since in theory there might be an en_GB manual at some point, but I wonder whether this is going too far with the whole abstraction

- the Source URL is not really right for two reasons:

a) it has to have a silly /mirror/rubbish/junk on the end
b) it doesn't include the version in it

but this is an upstream problem.
Comment 1 Hugo Cisneiros 2006-06-22 09:34:46 EDT
(In reply to comment #0)
> W: php-manual-en invalid-license Open Publication License v1.0

Just "OPL" would be better?

> - Arguably the package should be php-manual-en-us, since in theory there
> might be an en_GB manual at some point, but I wonder whether this is going
> too far with the whole abstraction

Some other languages really requires the xx_YY naming... The package could 
contain php manuals from other languages too, don't you think? A source 
package could crate some packages, one for each language.

About the en vs. en-us, I think you should follow upstream on this. So 
only 'en' is IMO the right thing.

> - the Source URL is not really right for two reasons:
> 
> a) it has to have a silly /mirror/rubbish/junk on the end
> b) it doesn't include the version in it
> 
> but this is an upstream problem.

You should download and get the exact URL, for example:
http://us2.php.net/distributions/manual/php_manual_en.tar.gz

Comment 2 Tim Jackson 2006-06-26 10:34:54 EDT
> > W: php-manual-en invalid-license Open Publication License v1.0
> Just "OPL" would be better?

It doesn't include a version. We really ought to specify a version if the
package specifies one, because otherwise if there's (say) an OPL v3 in future
with different terms, we would be misleading users by implying they could
distribute it under the terms of OPL v3 whereas the authors might have only
specified OPL v1. We should respect the author's license. Note for example that
recent Core "php" packages have started explicitly mentioning license version.

That said, "OPL v1.0" is fine by me, but I'm pretty sure rpmlint doesn't know
that either and it's less descriptive.
 
> > - Arguably the package should be php-manual-en-us, since in theory there
> > might be an en_GB manual at some point, but I wonder whether this is going
> > too far with the whole abstraction
> Some other languages really requires the xx_YY naming... 

That's ok, they can name it "php-manual-pt-br" or whatever as necessary.

I could maybe make the current package Provide php-manual-en-us, for forward
compatibility in case it gets split in future. That would make sense.

> The package could contain php manuals from other languages too, don't you 
> think? 

Yes, but see linked thread: I don't want the responsibility of maintaining them.
Also if I included every language supplied by PHP then the source RPM would be
really huge.
Additionally in future it's possible that not all languages would get updated at
the same time, so it could in theory mean pushing a big update SRPM even though
many sources are unchanged.

> You should download and get the exact URL, for example:
> http://us2.php.net/distributions/manual/php_manual_en.tar.gz

Thanks, I didn't pick up on that direct URL.

Updated files:

Spec URL: http://www.timj.co.uk/linux/specs/php-manual-en.spec
SRPM URL: http://www.timj.co.uk/linux/srpms/php-manual-en-20060527-2.src.rpm
Comment 3 Christopher Stone 2006-07-08 01:21:16 EDT
Use %{_defaultdocdir} instead of %{_datadir}/doc

Use %{_defaultdocdir}/php-manual instead of %{_defaultdocdir}/php-manual/en in
your %files section.


Comment 4 Tim Jackson 2006-07-08 12:18:10 EDT
(In reply to comment #3)

> Use %{_defaultdocdir}/php-manual instead of %{_defaultdocdir}/php-manual/en in
> your %files section.

How does this take account of the i18n issues raised in the linked thread?

Comment 5 Christopher Stone 2006-07-08 15:16:58 EDT
There is no clear hierachry of directory ownership of the
%{_defaultdocdir}/php-manual so all packages that use this directory should own
this directory.

Unless there is some other issue I am missing?  I'm not sure what you are
referring to when you say "linked thread".
Comment 6 Tim Jackson 2006-07-09 13:24:15 EDT
(In reply to comment #5)

Are you trying to say I should *add* a %dir %{_defaultdocdir}/php-manual? If so,
yep, good call.

What you implied was that the docs should go in %{_defaultdocdir}/php-manual
instead of %{_defaultdocdir}/php-manual/en , which seems to not cater for
further internationalisation (e.g. future packages providing ....php-manual/fr
for example.

"Linked thread" refers to the thread mentioned in the bug description, namely:

https://www.redhat.com/archives/fedora-extras-list/2006-May/msg00237.html
Comment 7 Christopher Stone 2006-07-09 18:47:47 EDT
Yes this is what I'm trying to say. You can add the %dir, or I think just saying
%{_defaultdocdir}/php-manual in the %files section will accomplish the same
thing, either way you want to code it is fine.
Comment 8 Tim Jackson 2006-08-05 19:19:48 EDT
I think all this is sorted.

- rpmlint is quiet
- updated to latest ver
- docdir ownership is good

Spec URL: http://www.timj.co.uk/linux/specs/php-manual-en.spec
SRPM URL: http://www.timj.co.uk/linux/srpms/php-manual-en-20060725-1.src.rpm
Comment 9 Christopher Stone 2006-08-10 17:33:19 EDT
-rpmlint output clean
-package named according to Package Naming Guidelines
-spec file name matches package %{name}
-package licensed with open-source compatible license

O I could not find the license file in the package or on the web site.  Please
let me know where I can find the upstream license

-license file not included in %doc
-spec file written in American English
-spec file legible
-source matches upstream
a8ef43e9ff1da2ce18df90e67fc5758f  php_manual_en.tar.gz
-package successfully compiles and builds on FC-5 x86_64
-package does not need any BuildRequires
-spec file does not contain any locales
-package does not contain any shared libraries
-package is not relocatable
-package owns all directories it creates
-package does not contain any duplicate files in %files
-file permissions set properly
-package contains proper %clean section
-macro usage is consistent
-package contains permissible content
-use of -doc subpackage does not make sense in this context since package is
already a doc package
-package does not include %doc
-package does not include header files or static libraries
-package does not use pkgconfig
-package does not contain any .so files
-package does not build a -devel subpackage
-package does not contain any .la files
-package is not a GUI needing a .desktop file
-package does not own files or directories owned by other packages


==== MUST ====
- Explain where documentation is licensed

==== SHOULD ====
- include a license file and place it in %doc
Comment 10 Tim Jackson 2006-08-11 03:41:36 EDT
copyright.html describes the distribution license
opl.license.html and linked pages are the license itself

I'd be tempted to symlink these into %{doc}, except that they are generated HTML
pages that would have broken links out of context.

How does creating a "placeholder" LICENSE file in %{doc} that says "For
licensing information please see %{defaultdocdir}/php-manual/en/copyright.html"
sound?
Comment 11 Christopher Stone 2006-08-14 15:20:05 EDT
Actually, this is good enough.  I just needed to know where it was located in
order to complete the review.  You may want to add a comment in the spec file
indicating where the license is located, but not necessary.

Approved as is.
Comment 12 Tim Jackson 2006-08-19 07:32:31 EDT
Imported & built - job #14355. Thanks for all the input!

Note You need to log in before you can comment on or make changes to this bug.