Am 09.04.2017 um 17:27 schrieb Guillem Jover: > 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 don't think that the maintscript format is well explained in man dh_installdeb and it just links back to dpkg-maintscript-helper. The man page states: "package.maintscript Lines in this file correspond to dpkg-maintscript-helper(1) commands and parameters. However, the "maint-script-parameters" should not be included as debhelper will add those automatically." It just references the documentation for dpkg-maintscript-helper for further information. Then there is one example for rm_conffile and that's it. No mention of the option to use a single maintscript file or examples for symlink_to_dir or dir_to_symlink. > 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. First of all if I were you I would update the DESCRIPTION. It should prominently mention maintscript files as the recommended way to use dpkg-maintscript-helper since manually editing postrm, prerm, postinst, preinst appears to be discouraged. https://wiki.debian.org/DpkgConffileHandling INTEGRATION IN PACKAGES When using a packaging helper, please check if it has native dpkg-maintscript-helper integration, which might make your life easier. See for example dh_installdeb(1). Is dpkg-maintscript-helper integrated in CDBS? Then I would expect a link or pointer to the respective documentation too. If not then debhelper is de facto the standard packaging helper in Debian and the man page should make a clear recommendation to use it. Packages without debhelper are the exception not the norm. >> 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. What I'm missing is the connection between dh_installdeb and maintscript files and the latter is not mentioned once. [...] >> 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. :) It could well be that I was just too ignorant to understand the beauty of dpkg-maintscript-helper and everything is just perfect. Let's leave it at that and apply your patch. By now I know how dpkg-maintscript-helper is supposed to work and if someone else is confused they will tell you in the future. Regards, Markus
signature.asc
Description: OpenPGP digital signature
