Bug#793937: [RFR] templates://libdvd-pkg/{templates}

[Dmitry Smirnov]

On Thursday 13 August 2015 17:59:25 Justin B Rye wrote:
> "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}).

Indeed it feels awkward and it is not necessary better than the original 
version...

 
> 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'm really not sure... "binary deb package format"?? Also "results" feels 
weird in this context... I'm not sure I recognise the problem as you describe 
it ("give the user the impression we're arbitrarily withholding useful 
information")... Maybe I've forgotten your explanation from earlier emails 
but choice of brackets can hardly give such impression...


> 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...

Thanks for improvement idea. :)


> >> 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?

I'm not shouting and not even close. :) Sorry if what I write appears to be a 
bit cranky. Even if it is then it is only because I have little time on my 
hands to dedicate to this issue due to other priorities...
I'm definitely lacking eloquence to explain design concepts of this package 
or perhaps I should try allocate some time for improving "README.source"...


> Is libdvd-pkg targeted exclusively at users who are
> smarter than me?

Come on, we are both know that anyone might use it... :) I've never made 
assumptions about technical skills of potential users...


> > 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.

I'm not against round brackets. I think I might have chosen square brackets 
because I was thinking about printing package's versions as well... Shouldn't 
matter any more...


> > 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*

Understood. Thank you.


> >> 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.

"libdvd-pkg" advertises guest packages in "Provides" field so "libdvdcss2" is 
a virtual package. Therefore those who know that they need "libdvdcss2" to 
watch DVDs might do something like

    apt-get install libdvdcss2

which pulls "libdvd-pkg" which builds "libdvdcss2" package.
So it is possible that user may see no package description but only debconf 
dialogs.


> > 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?

I'll think about it when it comes to -dbg packages. :)
Probably not because -dbg packages are often heavy... Some kind of 
configuration or another debconf dialog may be needed to confirm whether to 
build -dbg package. That's where plural "packages" may be useful as well...


> > 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.

You can build "libdvdcss2" manually and never upgrade it if you wish.
The purpose of "libdvd-pkg" is to provide seamless upgrades at the cost of 
having guest package build-dependencies installed. This is similar to 
function and requirements of DKMS family of packages.
I don't know why one would want to purge "libdvd-pkg" and lost upgrade 
functionality.


> (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.)

If you are tracking announcements. Otherwise point release ship a patch for 
you and trigger rebuild.


> 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...

"libdvd-pkg" is not designed to be uninstalled as long as you don't want to 
uninstall the packages it generated... I reckon you could use "libdvd-pkg" 
merely as build script but that would defeat its purpose. By the way we are 
really going beyond the scope of translations. It is getting hard to answer 
such long emails... Maybe we can discuss package design in another thread?


> 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.

Makes sense.


> > 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.

Fair enough. :)


> 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.

But they are in case when post-install hook is activated. Not necessarily 
though if only a minor update to installer package is delivered without need 
to re-build guest packages...

> Just make it something like "automatic upgrades
> of $MARMOSET (which may be triggered by new versions of $INSTALLER)".

"which may be triggered" is confusing and probably misleading without 
explanations what is actually meant by this...


> >>> 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.

Sorry...


> 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".

That's right, "automatic upgrades". :) That's what I always wanted to say. :)


> (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.)

Did I say that "apt-get check" testing a lock? It does not. "apt-get check" 
is to see whether there are broken packages -- an unsafe condition to install 
generated guest packages.
DPKG database lock is tested with "dpkg -i /dev/zero".


> 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.

Maybe... That reads straightforward enough, isn't it? It might be nice to 
mention when it happens -- something like "at the end of APT transaction"...


> 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.

This version seems to express hook status by "if it can acquire a lock on the 
package database" which is not quite the same...


> For now I'll count your requirement for minimal changes as a vote for
> that version!

:)


> 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.

:) I love your sense of humour. :)  I couldn't have said it better myself. :)


> 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".

Then I reckon we may not have the full history of changes... I hope I won't 
have to dig my email for proof...


> >> 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.

I'm afraid it might be difficult for me to express how the legal side of it 
works but please remember that Debian is different from Wikipedia in terms of 
re-distributability. I think this level of indirection is necessary in some 
jurisdictions where CSS-circumventing software is illegal.


> 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.

Only as much as package description already reveals can be revealed but not 
more. We should be able to re-phrase a little.


> 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".

Thank you. I've applied most of your changes to "control" file (I've dropped 
only "of your choice" part) and I've merged most of your improvements to 
"templates" (I've changed "doing downloads" with "downloading"):

    https://anonscm.debian.org/cgit/pkg-multimedia/libdvd-pkg.git/commit/?id=bee536ee

Would it be OK to replace

    process of downloading of the source files for ${PKGG} from videolan.org

with 

    process of downloading ${PKGG} sources files from videolan.org

?

I really like most of your improvements to templates. Thanks to you now it is 
much easier to understand what package really does. I much appreciate your 
attention to details and thorough approach to translation. Thank you for 
taking so much time to understand how this package works.

I'm attaching new "control" and "templates" files for review.

-- 
All the best,
 Dmitry Smirnov.

---
Democracy is a pathetic belief in the collective wisdom of individual
ignorance.
        -- H. L. Mencken
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.alioth.debian.org/pipermail/pkg-multimedia-maintainers/attachments/20150817/7da1bda7/attachment-0001.sig>
-------------- next part --------------
Source: libdvd-pkg
Section: contrib/utils
Priority: optional
Maintainer: Debian Multimedia Maintainers <pkg-multimedia-maintainers at lists.alioth.debian.org>
Uploaders: Dmitry Smirnov <onlyjob at 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 media player
 (such as VLC, SMplayer, Totem, etc.).
-------------- next part --------------
Template: libdvd-pkg/first-install
Type: note
_Description:
 This package automates the process of downloading of the source files for
 ${PKGG} from videolan.org, 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 downloading of the source files for
 ${PKGG} from videolan.org, 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 downloading of the source files for
 ${PKGG} from videolan.org, 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 "apt-get check"
 reports no errors) use "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 "apt-get check"
 reports no errors) use "dpkg -i" to install the new versions.
 .
 Alternatively, the process can be launched manually by running
 "sudo dpkg-reconfigure ${PKGI}".