Hi, Today I was looking to make a bug fix that would involve using dpkg-trigger in a maintainer script directly. So, to the manpage. It says: SYNOPSIS dpkg-trigger [option...] trigger-name dpkg-trigger [option...] command Sounds promising! Now what values can trigger-name and command have? Unfortunately the manpage does not say. Hm, on second thought, I suppose "command" refers to the functional options like --help. So the remaining question is what the valid values for trigger-name are. $ MANWIDTH=80 man dpkg-trigger | wc -l 70 Thanks for making the package installation process smoother. Hints?
There's no explicit list of value... a trigger name is just that, the name of a trigger. Can you suggest a wording that would make it clearer for you because I don't see what can be improved. Cheers,
Raphael Hertzog wrote: Have you tried reading it as though you were a new packager, forgetting what you already know? Anyway, I think something like the following could help. EXAMPLES if dpkg --compare-versions "$2" lt-nl 5.12.0 then dpkg-trigger --no-await perl-major-upgrade fi Informs interested packages that a major perl upgrade has occured. Packages with "interest perl-major-upgrade" in their triggers control file will have the trigger added to their pending trigger list. For each interested package foo, "foo.postinst triggered '<list>'" will be run with <list> a space-separated list including perl-major-upgrade before foo is next used to satisfy dependencies, or at the end of the dpkg run at the latest. generate_font >/usr/share/fonts/truetype/foo/bar.ttf dpkg-trigger /usr/share/fonts/truetype/foo/bar.ttf Informs interested packages about a new or updated font under /usr/share/fonts, just as if it had been unpacked as part of the package's files list. The current package will not be used to satisfy dependencies until the fontconfig cache is regenerated, so this is safe even if the font is used in the maintainer scripts of other packages. Though I doubt that second example would actually work, and I imagine that it would be possible to come up with more realistic examples if wanted. Does the trigger name have to match exactly (i.e., "/usr/share/fonts")? I assume trigger names are not allowed to contain a space character and that trigger names not based on paths conventionally do not start with a forward slash. Are there any other relevant rules or conventions? Thanks and hope that helps. Jonathan
Hi, I must admit I'm bored to have to fix minor documentation issues when we have so many other reported bugs. I'm always glad to improve the documentation but this is the kind of thing where the barrier to entry is not high and where I always try to get the bug reporter to provide a patch or at least some wording. And to be honest, if you really want to improve the documentation for a new packager, you need much more than clarifying the value "trigger-name" can take... just look at the amount of infos that you put in the explanations of your samples... Ok. All this should not be in this manual page, it's completely unrelated to the dpkg-trigger interface. We would need a separate "triggers-howto" or "triggers-intro" in truth. Yes, it must match exactly. It's documented in /usr/share/doc/dpkg-dev/triggers.txt.gz: | NB that in the case of a file trigger the name of the trigger is | needed, not the name of a file which would match the trigger. Everything relevant is documented in /usr/share/doc/dpkg-dev/triggers.txt.gz. | Trigger names contain only printing 7-bit ascii characters (no | whitespace). Each trigger kind has a distinct subset of the trigger | name space so that the kind can be determined from the name. After we | run out of straightforward syntaxes, we will use <kind>:<details>. | [...] | Explicit triggers | ----------------- | | Explicit triggers have names with the same syntax as package names, | *but* should *not* normally be named identically to a package. | | When choosing an explicit trigger name it is usually good to include a | relevant package name or some other useful identifier to help make the | trigger name unique. On the other hand, explicit triggers should | generally not be renamed just because the interested or triggering | packages' names change. | | Explicit trigger names form part of the interface between packages. | Therefore in case of wider use of any trigger the name and purpose | should be discussed in the usual way and documented in the appropriate | packaging guidelines (eg, in policy). | | File triggers | ------------- | | File triggers have names of the form | /path/to/directory/or/file | and are activated when the specified filesystem object, or any object | under the specified subdirectory, is created, updated or deleted by | dpkg during package unpack or removal. The pathname must be absolute. | [...] | Because of the restriction on trigger names, it is not possible to | declare a file trigger for a directory whose name contains whitespace, | i18n characters, etc. Such a trigger should not be necessary. Cheers,
Raphael Hertzog wrote: Excellent. Obviously, you don't have to fix it; I am happy even if you tag it wontfix, or choose some other forum where further work should happen and tag it help. I was responding to "I don't see what can be improved", which sounded suspiciously like "That doesn't look like a bug to me". By the way, documentation is a great way for a new contributor to help, but they usually need the help of experienced people to make it accurate. So thanks for your thorough explanations (and I think you've answered it all well). Comments below are about mechanics. Until then, is it not sensible to put it here, and add a comment to the hypothetical wishlist bug for a triggers-howto that the text should be removed from here at the appropriate time? I would have put a pointer to a short, clear reference document about the relevant piece of behavior if it existed (in an ideal world this might be dpkg(1), or even better, the policy manual or a revived packaging system manual); alas, none exists (certainly triggers.txt is not such a thing). Right. I think that's a design bug, and definitely worth documenting explicitly for the unwary in the meantime. Thanks for a pointer. Note that this is a design document, and it was never meant to be used as reference documentation. Details that could be added on top: * "printing 7-bit ascii characters" means isgraph() in the C locale (i.e., ' ' + 1 to ASCII DEL) * explicit triggers use the same alphanumerics-and-minus-signs syntax as package names: This description would be a nice addition for policy, and until then it would be a nice addition for a NOTES section of the dpkg-trigger(1) manpage. Thanks for the pointers. I'll try to find time to get back to this. Barring that, at least there is this bug report to help the next hapless reader feeling her way through.