Dmitry Smirnov wrote:
>> This package downloads the sourcecode for ${PKGM} from ${UPSTREAM},
>> compiles it into binary deb package format, and installs the output
>> (${PKGM_ALL}).
>
> I like the use of word "software" but I do not like word "output" in this
> context.
"Software" seems the obvious solution, but in this particular context
it feels slightly less natural - something like:
This package downloads the sourcecode for ${PKGM} from ${UPSTREAM},
compiles it into binary deb package format, and installs the resulting
software (${PKGM_ALL}).
A third slightly awkward option would be to use "results", which would
be plural no matter how many packages it is:
This package downloads the sourcecode for ${PKGM} from ${UPSTREAM},
compiles it into binary deb package format, and installs the results
(${PKGM_ALL}).
There are lots of ways we could do this, and none of them require us
to give the user the impression we're arbitrarily withholding useful
information.
> I respectfully disagree that it is "unfriendly" to try sharing
> common parts between packages of similar design (but not necessary similar
> purpose). It is an attempt to deduplicate the maintenance (and translators)
> effort -- it have nothing to do with users noticing similarity.
Except that you aren't currently using a variable for ${UPSTREAM}, so
the above text would be a separate job from the previous one involving
SourceForge...
>> If it's unlikely to matter for this package, I'd recommend taking the
>> confusing explicitly-uninformative uses of "(s)" out of the templates.
>> If it *might* matter, I still recommend getting rid of them, but in this
>> case it would be worth doing the work to phrase things so that you don't
>> need any uses of "(s)".
>
> Would it be any less confusing if we always use plural form but sometimes
> actually mention only one package in square brackets?
There are certainly ways we could get away with that; after all over
time this package is going to be building several libdvdcss .deb
files... hmmm:
This package automates the process of doing downloads from ${UPSTREAM}
of the source files for ${PKGM}, compiling them, and installing the
binary deb packages (${PKGM_ALL}).
It might be harder to do the same trick each time... I'll try it and
see.
>> My point is that at present the template offers the user no such
>> background information. How are they expected to make a decision?
>
> Perhaps there is a room for improvements but I doubt such long explanations
> regarding design of the package can be expected to be given in debconf
> dialogs... I believe that just enough information to make decision is already
> provided, together with recommended defaults.
Explanations don't necessarily have to be longwinded. But if enough
information is provided, how come you're still shouting at me for not
understanding it? Is libdvd-pkg targeted exclusively at users who are
smarter than me?
>> Square brackets are meaningless line noise.
>
> I do not see brackets as "meaningless line noise". In theory we could present
> list of packages as bulleted list but I prefer comma-separated list inside
> brackets for greater visibility.
That would be perfectly fine, as long as you're using the en_GB sense
of "brackets" (en_US "parentheses")! Different kinds of parenthesis
have different conventional uses in English prose:
() = "bonus information" asides
[] = "metatextual" additions, such as "[sic]"
{} = never occur in traditional prose
Here we hardly even need to parenthesise them at all - it could almost
be:
This package automates the process of doing downloads from ${UPSTREAM}
of the sourcecode for ${PKGM}, compiling it, and installing the binary
deb packages: ${PKGM_ALL}.
It would be better with a conjunction in the case of multiple
packages, but that's true whether it's bracketed or not, and there's
no i18n-friendly way of automating it.
>> If you can tell me what
>> you're hoping to accomplish with them, I can try to find a solution that
>> actually conveys that. Is it maybe intended as Python list syntax? If
>> so, no, you don't get to do that; it's supposed to be self-evidently
>> comprehensible to English-speakers.
>
> It was not intended to be Python list syntax. I doubt English-speaking users
> would be so confused by list of packages in brackets. Do you really think
> brackets make it hard(er) to understand what's going on?
Any case where you replace conventional punctuation with
unconventional punctuation makes it slightly harder to follow*
>> You think the end users who chose to install this package because you
>> advertised it to them as providing a way of watching DVDs are going to
>> want to build and install -dev packages? That strikes me as
>> implausible.
>
> It doesn't matter. -dev package is in Provides field so it can be pulled
> despite of package description.
I don't follow.
> The latter is targeted for end user rather
> than developer but guest software is installed as completely as possible.
Will the same apply to -dbg packages?
> Besides -dev package is lightweight and there is no harm to have in
> installed.
I don't keep things installed on my jessie desktop that I don't use,
especially if they have big dependency chains. In this case a lot of
those dependencies are things that will already have been pulled in
for libdvd-pkg itself, but honestly, once libdvd-pkg had done its job
of giving me a version of libdvdcss, my next step would be to *purge*
libdvd-pkg so I could get rid of all those. If libdvdcss-dev makes
that harder (by counting as a manually-installed development package)
it would also reduce my keenness to ever reinstall libdvd-pkg.
(After all, why would I need to keep an installer package installed on
stable? If libdvdcss gets a security fix, I'll see the announcement.)
[...]
>> This is a particularly annoying sort of debconf note, since it's going
>> to come across as trying to nag me into enabling the hook.
>
> It gives you the choice -- either to allow automatic upgrades (as recommended
> mode of operation) or be notified when manual upgrade is necessary.
> "Annoying sort of debconf note" was introduced on demand by ftp-masters as
> condition for entering archive. Package can do what it is intended to do only
> when hook is enabled. If giving user more freedom in configuring the way
> package operates then so be it...
I'm not sure what the FTPmasters thought the point of this was, but
it seems to me that somebody is failing to take into account the
possibility that I might uninstall libdvd-pkg...
[...]
>> Yes, we've recently seen a definitely worse approach - your actual
>> software looks good, I'm just nitpicking at your choice of terminology
>> in the documentation. The "host/guest" distinction makes it sound as if
>> you're talking about a virtual machine.
>
> Thank you. I reckon "host" and "guest" are such a broad terms that they
> hardly imply virtualisation. Nevertheless I reckon I've used "host/guest" for
> the lack of better terms...
It's far too late to ask you to change the terminology in the
implementation, so my recommendation is just to avoid leaking it into
the documentation. The names for the categories shouldn't matter,
because you've got no reason for talking about them; you should be
talking about the specific packages that the user cares about.
>>> I'm a bit lost here but in theory one might copy packages to another
>>> machine manually...
>>
>> Or, as I say, put them in ~/var/www/debian/.
>
> README.Debian already mention where generated packages can be found (e.g.
> "/usr/src/libdvd-pkg").
And fortunately that's the first place I'd look anyway. But
~/var/www/debian happens to be where I'd copy it to so that it would
be available to install on my other machines. Or in fact I'd probably
never install libdvd-pkg on my desktop machine in the first place -
I'd do the build on another machine that has some development packages
installed.
>> But while *we* might want
>> to do this, as far as I can see libdvd-pkg always does the full
>> download/build/install process, so it's odd that it keeps omitting one
>> of those three stages from the list.
>
> I'm not sure I quite follow you here... Which operation is omitted?
Well, the template "title_b-i" says "Build and install", the template
"build" says "Proceed with downloading and compiling", "upgrade" says
"build and install"... I don't see any cases of "download and
install", though.
>>>> How about:
>>>>
>>>> _Description: Enable automatic upgrades for ${PKGG}?
>>>> If activated, the APT post-invoke hook takes care of future automatic
>>>> upgrades of autocompiled software on upgrades of the installer
>>>> package. When updates are available, the hook will attempt the
>>>> appropriate source downloads and package recompilations, and (if
>>>> "apt-get check" reports no errors) will install the packages with
>>>> "dpkg -i".
>>>
>>> No, no no. Upgrade of installer (i.e. "host") package is not necessary
>>> means re-compilation of guest packages.
>>
>> That's what you seemed to be implying with "automatic upgrades of guest
>> package(s) on host package upgrade". If it's not what you meant to
>> imply, you'll have to explain it more clearly.
>
> No we don't need to explain it more clearly in debconf dialogs. README.source
> explains some design concepts. As you may have already noticed host package
> version incorporates guest package version (including debian revision number)
> as "upstream" version. Host package have its own debian revision number which
> can change without triggering guest source package re-build. Only change to
> "upstream" part of the version triggers re-build. Certainly there is no need
> to explain that in full details anywhere but in README.source.
I'm not asking for a full explanation in the template, just a wording
that's less actively misleading! These so-called "automatic upgrades
of guest package(s) on host package upgrade" *aren't* automatic on
host package upgrade. Just make it something like "automatic upgrades
of $MARMOSET (which may be triggered by new versions of $INSTALLER)".
>>> Also I believe unnecessary technical
>>> details regarding particular implementation of check for DPKG database lock
>>> do not belong to debconf dialog. Please let's keep dialogs simple and
>>> introduce minimum changes, especially if you don't understand well enough
>>> how
>>> it works.
Now that I go back and look again, I see that the technical
implementation details you're accusing me of unnecessarily intruding
into the text in such an ignorant manner were already there in your
original version. Ahem.
I am entirely amenable to suggestions that these technical details
should be left out, just as I was already doing my best to reduce the
prominence of the terminology of APT post-invoke hooks - what matters
is the effect, "automatic upgrades".
(Incidentally, it's far from obvious that the "apt-get check" is just
testing for a lock - for a start that isn't one of the things the man
page says it does.)
What would be a good replacement text, though? Would it be
oversimplifying to go all the way down to:
When updates are available, the hook will launch the process
of downloading, recompiling, and installing the new versions.
Or is the probability of a dpkg lock problem high enough that there
needs to be a hint in that direction, like, say:
When updates are available, the hook will launch the process
of downloading the source, recompiling it, and (if it can acquire a lock
on the package database) using "dpkg -i" to install the new versions.
For now I'll count your requirement for minimal changes as a vote for
that version!
>> If you weren't prepared to allow us to review the templates and
>> package description, it would have helped if you had said so when we
>> asked.
>
> I have no objections against review and I'm not against it. Though I had no
> idea that I would have to defend technical design of the package. ;)
>
> It did not occur to me that I had to tell about how sensitive package
> description is but I'm quite all right with improving it even if there are
> limits to acceptable changes. Maybe we can focus on improving debconf dialogs
> first?
Part of the reason we include descriptions in template reviews is
that an installation procedure surprising and important enough to
justify a debconf note often ought to imply a warning in the package's
long description as well.
And when the whole point of a package is to summon the software that
must not be named - a forbidden algorithm so unspeakable that merely
contemplating it causes the FTPmasters 2d10 san loss - well, I'd have
thought there'd be some hint at that in the description.
>> (And sorry, but I'm not a developer. I won't see commits unless
>> you can give me URLs I can browse to.)
>
> Sorry I thought package metadata or link from PTS page makes it easy enough
> to find repository:
>
> https://anonscm.debian.org/cgit/pkg-multimedia/libdvd-pkg.git
You may be overestimating my ability to navigate git trees, but I
think I've found them. There's one commit where you take out a
reference to the package being illegal in some jurisdictions - I can
see why that might make FTPmasters unhappy - but I don't see anything
even vaguely similar to my description of CSS. It looks as if you
leapt straight from "this ridiculous thing is prohibited" to "all
relevant information is prohibited".
[...]
>> I'm not sure you even need to do that. Your package is aimed at users
>> who are *starting* by thinking "right, I've got a media player and a
>> DVD, is there some other thing I need?" - you don't have to include
>> adverts for the concept of watching DVDs on media players, you just need
>> to tell them what problem it solves. Except that apparently telling
>> them this is illegal?!
>
> Yeah, unfortunately package description can't reproduce any parts of
> libdvdcss description...
>
> On second thought it could be useful to know which players can take advantage
> of installed libdvdcss library. For that matter it makes perfect sense to
> mention particular players.
>
>> It's legal to provide this software, but it *isn't* legal to explain
>> what CSS is?
>
> Yes.
If this was the case, Wikipedia would be one vast scrum of lawyers,
but libdvdcss would have been available in Debian main all along.
> However even if we can't elaborate what it does at least we say what
> software is going to be installed so users can read about it elsewhere...
It would be nice if it did that, but it doesn't.
>> I can understand that we don't want to say "this package
>> is a tool for pirating DVDs by illegally bypassing CSS encryption", but
>> I really think we could get a whole lot closer to mentioning the point
>> of the exercise. For a start, with a minor tweak:
>>
>> Some features of the DVD-Video format use the Content Scramble
>> System (CSS). Software to bypass this encryption cannot be
>> distributed via the Debian repositories.
>
> I've been through this countless times. No, CSS can't be mentioned nor what
> Debian can (or can not) distribute.
Could you get the FTPmasters to produce a nice clear policy statement
about exactly what information can't be revealed? Then you could get
videolan.org to host that as a web page and link to it from the package
description.
My latest version is a strictly language-fixes-only revision, bringing
the description generally into line with DevRef recommendations but
brazenly flouting a Debian Policy 3.4 "should".
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff -ru libdvd-pkg-1.3.99-1.pristine/debian/control
libdvd-pkg-1.3.99-1/debian/control
--- libdvd-pkg-1.3.99-1.pristine/debian/control 2015-04-14 02:47:06.000000000
+0100
+++ libdvd-pkg-1.3.99-1/debian/control 2015-08-13 17:31:27.832193303 +0100
@@ -16,7 +16,7 @@
,${guest:Build-Depends}
Recommends: ${guest:Recommends} ,libcap2-bin
Suggests: ${guest:Suggests}
-Description: download and install software necessary to play video DVDs
- This package fetches, compiles from source code and installs library
- packages that are necessary to play all video DVDs with media
- player of your choice (like VLC, SMplayer, Totem, etc.).
+Description: DVD-Video playing library - installer
+ This package fetches, compiles from source code, and installs library
+ packages necessary for playing video DVDs with the media player of your
+ choice (such as VLC, SMplayer, Totem, etc.).
diff -ru libdvd-pkg-1.3.99-1.pristine/debian/templates
libdvd-pkg-1.3.99-1/debian/templates
--- libdvd-pkg-1.3.99-1.pristine/debian/templates 2014-12-17
03:00:49.000000000 +0000
+++ libdvd-pkg-1.3.99-1/debian/templates 2015-08-13 17:36:11.644334541
+0100
@@ -1,60 +1,68 @@
Template: libdvd-pkg/first-install
Type: note
_Description:
- This package downloads the ${PKGG} source files from videolan.org,
- compile them and install the binary deb package(s)
- [${PKGG_ALL}].
+ This package automates the process of doing downloads from videolan.org
+ of the source files for ${PKGG}, compiling them, and installing the
+ binary deb packages (${PKGG_ALL}).
.
- Please remember to run "sudo dpkg-reconfigure ${PKGI}"
- to build and install guest package(s) for the first time.
+ Please run "sudo dpkg-reconfigure ${PKGI}" to launch this process for
+ the first time.
Template: libdvd-pkg/title_b-i
Type: title
-_Description: Build and install ${PKGG}${VER}
+_Description: Download, build and install ${PKGG}${VER}
Template: libdvd-pkg/build
Type: boolean
Default: true
-_Description: Proceed with downloading and compiling ${PKGG}${VER}?
- The installation process is therefore about to download the source files
- from videolan.org, compile them, and install the binary deb package(s)
- [${PKGG_ALL}].
+_Description: Download, build, and install ${PKGG}${VER}?
+ This package automates the process of doing downloads from videolan.org
+ of the source files for ${PKGG}, compiling them, and installing the
+ binary deb packages (${PKGG_ALL}).
.
Please confirm whether you wish this to happen.
Template: libdvd-pkg/title_u
Type: title
-_Description: Upgrades available for guest package(s)
+_Description: Upgrade available for ${PKGG}
Template: libdvd-pkg/upgrade
Type: note
_Description:
- An update to guest package(s) [${PKGG_ALL}] version ${VER} is available
- but automatic upgrade is disabled.
+ This package automates the process of doing downloads from videolan.org
+ of the source files for ${PKGG}, compiling them, and installing the
+ binary deb packages (${PKGG_ALL}).
.
- Please remember to run "sudo dpkg-reconfigure ${PKGI}" to build and
- install guest package(s) or consider installing the APT post-invoke hook.
+ An update to version ${VER} is available, but automatic upgrades are
+ disabled.
+ .
+ Please run "sudo dpkg-reconfigure ${PKGI}" to launch this process
+ manually and/or activate automatic upgrades in future.
Template: libdvd-pkg/post-invoke_hook-install
Type: boolean
Default: true
-_Description: Install APT post-invoke hook?
+_Description: Enable automatic upgrades for ${PKGG}?
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".
+ upgrades of ${PKGG} (which may be triggered by new versions of
+ ${PKGI}). When updates are available, the hook will launch the
+ process of downloading the source, recompiling it, and (if it can
+ acquire a lock on the package database) using "dpkg -i" to install the
+ new versions.
.
- Alternatively, guest package(s) can be built by manual invocation of
- "dpkg-reconfigure ${PKGI}".
+ Alternatively, the process can be launched manually by running
+ "sudo dpkg-reconfigure ${PKGI}".
Template: libdvd-pkg/post-invoke_hook-remove
Type: boolean
Default: false
-_Description: Remove APT post-invoke hook?
+_Description: Disable automatic upgrades for ${PKGG}?
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".
+ upgrades of ${PKGG} (which may be triggered by new versions of
+ ${PKGI}). When updates are available, the hook will launch the
+ process of downloading the source, recompiling it, and (if it can
+ acquire a lock on the package database) using "dpkg -i" to install the
+ new versions.
.
- Alternatively, guest package(s) can be built by manual invocation of
- "dpkg-reconfigure ${PKGI}".
+ Alternatively, the process can be launched manually by running
+ "sudo dpkg-reconfigure ${PKGI}".
Template: libdvd-pkg/first-install
Type: note
_Description:
This package automates the process of doing downloads from videolan.org
of the source files for ${PKGG}, compiling them, and installing the
binary deb packages (${PKGG_ALL}).
.
Please run "sudo dpkg-reconfigure ${PKGI}" to launch this process for
the first time.
Template: libdvd-pkg/title_b-i
Type: title
_Description: Download, build and install ${PKGG}${VER}
Template: libdvd-pkg/build
Type: boolean
Default: true
_Description: Download, build, and install ${PKGG}${VER}?
This package automates the process of doing downloads from videolan.org
of the source files for ${PKGG}, compiling them, and installing the
binary deb packages (${PKGG_ALL}).
.
Please confirm whether you wish this to happen.
Template: libdvd-pkg/title_u
Type: title
_Description: Upgrade available for ${PKGG}
Template: libdvd-pkg/upgrade
Type: note
_Description:
This package automates the process of doing downloads from videolan.org
of the source files for ${PKGG}, compiling them, and installing the
binary deb packages (${PKGG_ALL}).
.
An update to version ${VER} is available, but automatic upgrades are
disabled.
.
Please run "sudo dpkg-reconfigure ${PKGI}" to launch this process
manually and/or activate automatic upgrades in future.
Template: libdvd-pkg/post-invoke_hook-install
Type: boolean
Default: true
_Description: Enable automatic upgrades for ${PKGG}?
If activated, the APT post-invoke hook takes care of future automatic
upgrades of ${PKGG} (which may be triggered by new versions of
${PKGI}). When updates are available, the hook will launch the
process of downloading the source, recompiling it, and (if it can
acquire a lock on the package database) using "dpkg -i" to install the
new versions.
.
Alternatively, the process can be launched manually by running
"sudo dpkg-reconfigure ${PKGI}".
Template: libdvd-pkg/post-invoke_hook-remove
Type: boolean
Default: false
_Description: Disable automatic upgrades for ${PKGG}?
If activated, the APT post-invoke hook takes care of future automatic
upgrades of ${PKGG} (which may be triggered by new versions of
${PKGI}). When updates are available, the hook will launch the
process of downloading the source, recompiling it, and (if it can
acquire a lock on the package database) using "dpkg -i" to install the
new versions.
.
Alternatively, the process can be launched manually by running
"sudo dpkg-reconfigure ${PKGI}".
Source: libdvd-pkg
Section: contrib/utils
Priority: optional
Maintainer: Debian Multimedia Maintainers
<pkg-multimedia-maintain...@lists.alioth.debian.org>
Uploaders: Dmitry Smirnov <only...@debian.org>
Standards-Version: 3.9.6
Build-Depends: debhelper (>= 9)
Vcs-Browser: http://anonscm.debian.org/cgit/pkg-multimedia/libdvd-pkg.git
Vcs-Git: git://anonscm.debian.org/pkg-multimedia/libdvd-pkg.git
Package: libdvd-pkg
Architecture: all
Provides: ${guest:Provides}
Depends: ${misc:Depends} ,build-essential
,wget | devscripts
,${guest:Build-Depends}
Recommends: ${guest:Recommends} ,libcap2-bin
Suggests: ${guest:Suggests}
Description: DVD-Video playing library - installer
This package fetches, compiles from source code, and installs library
packages necessary for playing video DVDs with the media player of your
choice (such as VLC, SMplayer, Totem, etc.).
