On Sat, 2017-04-08 at 23:06:01 +0200, Markus Koschany wrote: > Am 08.04.2017 um 05:05 schrieb Guillem Jover: > > On Fri, 2017-03-17 at 16:31:27 +0100, Markus Koschany wrote: > [...]
> At the moment the man page of dpkg-maintscript-helper appears to be the > only source of information how to handle the four use cases of > (rm_conffile, mv_conffile, symlink_to_dir and dir_to_symlink). Aside > from man dh_installdeb I couldn't find any information in debhelper > about *.maintscript files and how to use them correctly. Each part documents what it is responsible for. Repeating the commands in dh_installdeb would seem detrimental, as debhelper does not care about them, and would imply duplicating information that might easily get out-of-sync. The maintscript format is explained in detail in the dh_installdeb, which is the only thing that makes use of them. I guess my main issue with this bug report is, that TBH I don't really understand why any of this was confusing, and how to improve it while not adding layer violations or duplicating information were it does not belong. > If debhelper is the correct place to document this, then please reassign > to debhelper. Though at least I would expect a link or pointer to the > additional documentation in man dpkg-maintscript-helper. There's already a link to dh_installdeb(1) in dpkg-maintscript-helper. > >> It should be more obvious why the package argument is > >> needed at all when you have to create one $PACKAGE.maintscript file per > >> package anyway. > > > > This is rather confused, and has nothing to do with how > > dpkg-maintscript-helper operates, but rather how debhelper uses its > > files and how it might or might not add the package arguments on its > > own. > Exactly it is confusing and thus my bug report. According to > /usr/share/debhelper/autoscripts/maintscript-helper debhelper just calls > dpkg-maintscript-helper with the arguments provided in its maintscript > files. For me dpkg and debhelper are just two sides of the same coin. See above, I find the documentation explains in the detail how both sides work, and how debhelper interacts with dpkg-maintscript-helper. Just to be sure, did you read the entire dpkg-maintscript-helper(1) man page? If yes, what do you think (or remember) not being clear? > >> Please also clarify that [package] does not imply that a single maintscript > >> file will act on the binary[package]. > > > > I'm no sure what you mean here exactly, but this seems to me it's > > something for debhelper to document if at all. > > You need one maintscript file per binary package. I thought I could get > away with one maintscript file and use it like that > > symlink_to_dir /usr/share/doc/holotz-castle > /usr/share/doc/holotz-castle-data 1.3.14-8~ holotz-castle > symlink_to_dir /usr/share/doc/holotz-castle-editor > /usr/share/doc/holotz-castle-data 1.3.14-8~ holotz-castle-editor > > I understand that maintscript files work like every other debhelper file > now, but the reason what got me confused in the first place was the > [package] argument and the documentation in dpkg-maintscript-helper. Personally I think this is obvious from the dh_installdeb(1) man page when it mentions <package>.maintscript, but I guess making this explicit in debhelper. > >> I think an example how to use dpkg-maintscript-helper with debhelper's > >> maintscript files would also be appreciated. > > > > This would be a layer violation, I'm not planning on documenting how > > upper layers are using dpkg in this way. Please get debhelper to > > clarify any of this if it's not yet clear. > > As I said at the beginning I have no strong preferences but honestly the > man page of dpkg-maintscript-helper is the best place to document use > cases. At least I would appreciate it if you pointed to additional > information about maintscript files because that's what a lot of > maintainers actually use. This is there already by reference, by pointing to the dh_installdeb(1) man page, I don't feel very comfortable with mentioning «.maintscript» files there because it might make these even more confusing, and it's a debhelper implementation detail anyway. This is equivalent to requesting that many dpkg man pages such as dpkg-shlibdeps or several of the format ones explain how they are being used by frontends or other wrappers. Which would be wrong IMO. In any case, here's a small patch (targetting 1.19.x) that might clarify somehow the dpkg side. But see my comment above, that otherwise I don't really see what or why any of this would be confusing. :) Thanks, Guillem
From 2a819acbbd8ce776bcb06a3d07417c69d8ce30a8 Mon Sep 17 00:00:00 2001 From: Guillem Jover <guil...@debian.org> Date: Sun, 9 Apr 2017 16:53:28 +0200 Subject: [PATCH] man: Clarify behavior for dpkg-maintscript-helper Closes: #857852 --- man/dpkg-maintscript-helper.man | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/man/dpkg-maintscript-helper.man b/man/dpkg-maintscript-helper.man index c3b73ef35..0d608abd5 100644 --- a/man/dpkg-maintscript-helper.man +++ b/man/dpkg-maintscript-helper.man @@ -76,14 +76,16 @@ maintainer scripts in version \fB3.0\-1\fP, should set \fIprior-version\fP to \fB3.0\-1~\fP. .TP .I package -The package name. When the package is “Multi\-Arch: same” this parameter +The package name owning the pathname(s). +When the package is “Multi\-Arch: same” this parameter must include the architecture qualifier, otherwise it should \fBnot\fP usually include the architecture qualifier (as it would disallow cross-grades, or switching from being architecture specific to architecture \fBall\fP or vice versa). If the parameter is empty or omitted, the \fBDPKG_MAINTSCRIPT_PACKAGE\fP -and \fBDPKG_MAINTSCRIPT_ARCH\fP environment variables (as set by \fBdpkg\fP) -will be used to generate an arch-qualified package name. +and \fBDPKG_MAINTSCRIPT_ARCH\fP environment variables (as set by \fBdpkg\fP +when running the maintainer scripts) will be used to generate an +arch-qualified package name. .TP .B \-\- All the parameters of the maintainer scripts have to be forwarded to the -- 2.12.2.715.g7642488e1d
