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

Re: [RFR] templates://fheroes2-pkg/{templates}



Okay, I can try to review it, but I need some input from the
maintainer, because I'm really not sure I understand it.

Christian PERRIER wrote:
>  Template: fheroes2-pkg/build
>  Type: boolean
>  Default: true
> -_Description: Continue?
> - This application is about to download, compile from source code and
> - install "${PKGG}${VER}" as Debian package (source files will be
> - downloaded from SourceForge).
> - .
> +_Description: Process with downloading and compiling fheroes2?
                     ^^^
It's "proceed" (as in a procession...)

If people are really doing "apt-get install fheroes2-pkg" and then
being surprised by this information (to the point that they say "no"),
it seems to me you need a better package description!

And then fheroes2-pkg/first-install seems to unconditionally perform
the same song and dance all over again.  Why?

>   fheroes2 AI is non-free due to not-for-sale restriction.
>   Also some images may be non-free.

Missing articles; I think you mean
    The fheroes2 AI is non-free due to a not-for-sale restriction, and
    some images may also be non-free.

> + .
> + As a consequence, the software has to be downloaded and compiled at
> + install time.

This is also what the next paragraph says.

> + .
> + The installation process is therefore about to download, compile from source code and
> + install "${PKGG}${VER}" as a binary deb package (source files will be
> + downloaded from SourceForge).

There's an opportunity in there for a Harvard comma, but it seems to
me we could just say:
    The installation process is therefore about to download the source files
    from SourceForge, compile them, and install the binary deb package
    "${PKGG}${VER}".

> + .
> + Please confirm whether you accept this to happen.

"Accept + infinitive" doesn't work.

    Please confirm whether you wish this to happen.

Or I suppose

    Please confirm that this should happen.
  
>  Template: fheroes2-pkg/first-install
>  Type: note
>  _Description:
>   fheroes2 AI is non-free due to not-for-sale restriction.
>   Also some images may be non-free.
>   .
> + The installation process is therefore about to download, compile from source code and
> + install "${PKGG}${VER}" as a binary deb package (source files will be
> + downloaded from SourceForge).

As above (why does it happen twice?)

> + .
> + Please remember to run "sudo dpkg-reconfigure ${PKGI}"
>   to build and install guest package(s) for the first time.

It's grammatical, but I don't understand it.  What "guest
package(s)" is it talking about?  Why don't we know if they're
singular or plural?  If it's talking about the same fheroes2 package
that it just claimed to be about to download/compile/install, why is
it now telling me that this won't happen yet?  *When* do I need to
"remember" to run this command?

>  Template: fheroes2-pkg/title_b-i
>  Type: title
> -_Description: Build and install ${PKGG}${VER}.
> +_Description: Build and install ${PKGG}${VER}
>  
>  Template: fheroes2-pkg/title_u
>  Type: title
> -_Description: Guest package(s) upgrade note.
> +_Description: Guest package(s) upgrade note

If this goes with fheroes2-pkg/upgrade, I would suggest that instead
of just labelling it as a note this title could say something like

  +_Description: Upgrade available for guest package(s)

Though again, if it's talking about fheroes2, why doesn't it say so?
If it's talking about some other packages, why hasn't it introduced
them?

>  Template: fheroes2-pkg/upgrade
>  Type: note
> @@ -36,39 +41,33 @@
>   An update to guest package(s) [${PKGG_ALL}] version ${VER} is available
>   but automatic upgrade is disabled.

We know the name(s) and we know the version (which is the same for all
of them) but we don't know whether it's a package or packages?

>  Template: fheroes2-pkg/post-invoke_hook-install
>  Type: boolean
>  Default: true
>  _Description: Install APT post-invoke hook?
>   APT post-invoke hook takes care of future automatic upgrades of guest
    ^The
> + package(s) on host package upgrade. If activated, the APT

Oh, now here we know we're talking about plural guest packages, so
we certainly don't need the "(s)".  How often was that true in
earlier templates where I couldn't be certain?

>   operations hook will check whenever guest package(s) can be updated.

Check what when?  Is it trying to say it checks on a regular basis
to see whether there are updates available?  Or is it saying that
whenever there are available updates it will check some other thing?
I think, rereading it, it's just saying the same thing as the
previous line, in which case just leave it out.

    If activated, the APT post-invoke hook takes care of future automatic
    upgrades of guest package(s) on host package upgrade. When an update
    is available, the hook will [...]

But I still don't understand what these "host" and "guest" packages
are.  Does it mean the installer (this very package doing the
talking) is the "host" and the fheroes2 package is the "guest"?  If
so, when are there ever plural guests?  And if we already know the
package-names, why are we going to such lengths to avoid mentioning
them?

> + The hook will then attempt to download, build and
> + install package(s) using "dpkg -i" but only if "apt-get check" reported
>   no errors.

So first it'll run "apt-get check", then if that's okay it'll try to
use "dpkg -i" to download-and-build-and-install the package(s)?  No:

    [...] When an update
    is available, the hook will attempt to download and build the package(s),
    and (if "apt-get check" reports no errors) install them with "dpkg -i".

> + Alternatively, guest package(s) can be built by manual invocation of
> + "dpkg-reconfigure ${PKGI}".

Again, we know we mean plural "guest packages" here.
 
>  Template: fheroes2-pkg/post-invoke_hook-remove
>  Type: boolean
>  Default: false
>  _Description: Remove APT post-invoke hook?
>   APT post-invoke hook takes care of future automatic upgrades of guest
    ^The
> + package(s) on host package upgrade. If activated, the APT
>   operations hook will check whenever guest package(s) can be updated.
> + The hook will then attempt to download, build and
> + install package(s) using "dpkg -i" but only if "apt-get check" reported
>   no errors.

Why is it telling us this now?  I gather we'll only see this if
we've got the hook installed, so haven't we already read this (and
seen the hook in action)?  At present the post-invoke_hook-install
and post-invoke_hook-remove templates are different only in the
first word of the short Description.  This one really ought to say
something like:

    If the hook is disabled, no automatic upgrades will occur.

But I'm too uncertain about what's going on to change it.

In the control file:
> -Description: download, build and install fheroes2 package
> - This package automatically download, build ${guest} from source code
> - and install the resulting package.
> +Description: fheroes2 package downloader and builder
> + This package automatically downloads and builds ${guest} from source code
> + and installs the resulting package.

    This package automatically downloads the ${guest} source code,
    builds it, and installs the resulting package.

>   .
>   Fheroes2 binaries are not distributable if built with AI due to
>   licensing conflict between GPL-2 code and not-for-sale AI.
    ^a                                       ^the

ObWhyTheName: the description of fheroes2 that gets appended to this
isn't bad, but it never quite states that the package's name is short
for "Free Heroes-(of-Might-and-Magic)-II".
-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package
diff -ru fheroes2-pkg-0+svn20130304-2.pristine/debian/control fheroes2-pkg-0+svn20130304-2/debian/control
--- fheroes2-pkg-0+svn20130304-2.pristine/debian/control	2013-09-15 16:27:03.000000000 +0100
+++ fheroes2-pkg-0+svn20130304-2/debian/control	2013-10-18 11:06:10.959890604 +0100
@@ -15,12 +15,12 @@
 Recommends: ${guest:Recommends} ,libcap2-bin
 Suggests: ${guest:Suggests}
          ,vrms
-Description: download, build and install fheroes2 package
- This package automatically download, build ${guest} from source code
- and install the resulting package.
+Description: fheroes2 package downloader and builder
+ This package automatically downloads the ${guest} source code,
+ builds it, and installs the resulting package.
  .
- Fheroes2 binaries are not distributable if built with AI due to
- licensing conflict between GPL-2 code and not-for-sale AI.
- Also Fheroes2 may contain some non-free images.
+ Fheroes2 binaries are not distributable if built with AI due to a
+ licensing conflict between GPL-2 code and the not-for-sale AI.
+ Fheroes2 may also contain some non-free images.
  .
  ${guest}: ${guest:Description}
diff -ru fheroes2-pkg-0+svn20130304-2.pristine/debian/templates fheroes2-pkg-0+svn20130304-2/debian/templates
--- fheroes2-pkg-0+svn20130304-2.pristine/debian/templates	2013-06-30 17:57:02.000000000 +0100
+++ fheroes2-pkg-0+svn20130304-2/debian/templates	2013-10-18 11:39:44.075227429 +0100
@@ -1,34 +1,36 @@
 Template: fheroes2-pkg/build
 Type: boolean
 Default: true
-_Description: Continue?
- This application is about to download, compile from source code and
- install "${PKGG}${VER}" as Debian package (source files will be
- downloaded from SourceForge).
+_Description: Proceed with downloading and compiling fheroes2?
+ The fheroes2 AI is non-free due to a not-for-sale restriction, and
+ some images may also be non-free.
+ .
+ The installation process is therefore about to download the source files
+ from SourceForge, compile them, and install the binary deb package
+ "${PKGG}${VER}".
  .
- fheroes2 AI is non-free due to not-for-sale restriction.
- Also some images may be non-free.
+ Please confirm whether you wish this to happen.
 
 Template: fheroes2-pkg/first-install
 Type: note
 _Description:
- This application automates download, compile from source code and
- install "${PKGG}${VER}" as Debian package (source files will be
- downloaded from SourceForge).
+ The fheroes2 AI is non-free due to a not-for-sale restriction, and
+ some images may also be non-free.
  .
- fheroes2 AI is non-free due to not-for-sale restriction.
- Also some images may be non-free.
+ The installation process is therefore about to download the source files
+ from SourceForge, compile them, and install the binary deb package
+ "${PKGG}${VER}".
  .
- Please remember to run `sudo dpkg-reconfigure ${PKGI}`
+ Please remember to run "sudo dpkg-reconfigure ${PKGI}"
  to build and install guest package(s) for the first time.
 
 Template: fheroes2-pkg/title_b-i
 Type: title
-_Description: Build and install ${PKGG}${VER}.
+_Description: Build and install ${PKGG}${VER}
 
 Template: fheroes2-pkg/title_u
 Type: title
-_Description: Guest package(s) upgrade note.
+_Description: Upgrades available for guest package(s)
 
 Template: fheroes2-pkg/upgrade
 Type: note
@@ -36,39 +38,29 @@
  An update to guest package(s) [${PKGG_ALL}] version ${VER} is available
  but automatic upgrade is disabled.
  .
- Please remember to run `sudo dpkg-reconfigure ${PKGI}` to build and
- install guest package(s) or consider installing APT post-invoke hook.
+ Please remember to run "sudo dpkg-reconfigure ${PKGI}" to build and
+ install guest package(s) or consider installing the APT post-invoke hook.
 
 Template: fheroes2-pkg/post-invoke_hook-install
 Type: boolean
 Default: true
 _Description: Install APT post-invoke hook?
- APT post-invoke hook takes care of future automatic upgrades of guest
- package(s) on host package upgrade. After end of batch of APT
- operations hook will check whenever guest package(s) can be updated.
- If upgrade detected then hook will attempt to download/build and
- install package(s) using `dpkg -i` but only if `apt-get check` reported
- no errors.
+ If activated, the APT post-invoke hook takes care of future automatic
+ upgrades of guest package(s) on host package upgrade. When an update
+ is available, the hook will attempt to download and build the package(s),
+ and (if "apt-get check" reports no errors) install them with "dpkg -i".
  .
- At the moment there are no known problems associated with APT
- post-invoke hook which maintainer recommends to use with this package.
- .
- Alternatively guest package(s) can be built by manual invocation of
- `dpkg-reconfigure ${PKGI}`.
+ Alternatively, guest packages can be built by manual invocation of
+ "dpkg-reconfigure ${PKGI}".
 
 Template: fheroes2-pkg/post-invoke_hook-remove
 Type: boolean
 Default: false
 _Description: Remove APT post-invoke hook?
- APT post-invoke hook takes care of future automatic upgrades of guest
- package(s) on host package upgrade. After end of batch of APT
- operations hook will check whenever guest package(s) can be updated.
- If upgrade detected then hook will attempt to download/build and
- install package(s) using `dpkg -i` but only if `apt-get check` reported
- no errors.
- .
- At the moment there are no known problems associated with APT
- post-invoke hook which maintainer recommends to use with this package.
+ If activated, the APT post-invoke hook takes care of future automatic
+ upgrades of guest package(s) on host package upgrade. When an update
+ is available, the hook will attempt to download and build the package(s),
+ and (if "apt-get check" reports no errors) install them with "dpkg -i".
  .
- Alternatively guest package(s) can be built on manual invocation of
- `dpkg-reconfigure ${PKGI}`.
+ Alternatively, guest packages can be built by manual invocation of
+ "dpkg-reconfigure ${PKGI}".
Source: fheroes2-pkg
Section: contrib/games
Priority: optional
Maintainer: Dmitry Smirnov <onlyjob@debian.org>
Standards-Version: 3.9.4
Build-Depends: debhelper (>= 9)
Vcs-Browser: http://anonscm.debian.org/gitweb/?p=users/onlyjob/fheroes2-pkg.git
Vcs-Git: git://anonscm.debian.org/users/onlyjob/fheroes2-pkg.git

Package: fheroes2-pkg
Architecture: all
Provides: ${guest:Provides}
Depends: ${misc:Depends}, build-essential
        ,${guest:Build-Depends}
Recommends: ${guest:Recommends} ,libcap2-bin
Suggests: ${guest:Suggests}
         ,vrms
Description: fheroes2 package downloader and builder
 This package automatically downloads the ${guest} source code,
 builds it, and installs the resulting package.
 .
 Fheroes2 binaries are not distributable if built with AI due to a
 licensing conflict between GPL-2 code and the not-for-sale AI.
 Fheroes2 may also contain some non-free images.
 .
 ${guest}: ${guest:Description}
Template: fheroes2-pkg/build
Type: boolean
Default: true
_Description: Proceed with downloading and compiling fheroes2?
 The fheroes2 AI is non-free due to a not-for-sale restriction, and
 some images may also be non-free.
 .
 The installation process is therefore about to download the source files
 from SourceForge, compile them, and install the binary deb package
 "${PKGG}${VER}".
 .
 Please confirm whether you wish this to happen.

Template: fheroes2-pkg/first-install
Type: note
_Description:
 The fheroes2 AI is non-free due to a not-for-sale restriction, and
 some images may also be non-free.
 .
 The installation process is therefore about to download the source files
 from SourceForge, compile them, and install the binary deb package
 "${PKGG}${VER}".
 .
 Please remember to run "sudo dpkg-reconfigure ${PKGI}"
 to build and install guest package(s) for the first time.

Template: fheroes2-pkg/title_b-i
Type: title
_Description: Build and install ${PKGG}${VER}

Template: fheroes2-pkg/title_u
Type: title
_Description: Upgrades available for guest package(s)

Template: fheroes2-pkg/upgrade
Type: note
_Description:
 An update to guest package(s) [${PKGG_ALL}] version ${VER} is available
 but automatic upgrade is disabled.
 .
 Please remember to run "sudo dpkg-reconfigure ${PKGI}" to build and
 install guest package(s) or consider installing the APT post-invoke hook.

Template: fheroes2-pkg/post-invoke_hook-install
Type: boolean
Default: true
_Description: Install APT post-invoke hook?
 If activated, the APT post-invoke hook takes care of future automatic
 upgrades of guest package(s) on host package upgrade. When an update
 is available, the hook will attempt to download and build the package(s),
 and (if "apt-get check" reports no errors) install them with "dpkg -i".
 .
 Alternatively, guest packages can be built by manual invocation of
 "dpkg-reconfigure ${PKGI}".

Template: fheroes2-pkg/post-invoke_hook-remove
Type: boolean
Default: false
_Description: Remove APT post-invoke hook?
 If activated, the APT post-invoke hook takes care of future automatic
 upgrades of guest package(s) on host package upgrade. When an update
 is available, the hook will attempt to download and build the package(s),
 and (if "apt-get check" reports no errors) install them with "dpkg -i".
 .
 Alternatively, guest packages can be built by manual invocation of
 "dpkg-reconfigure ${PKGI}".

Reply to: