Raphael Hertzog wrote: > I must admit I'm bored to have to fix minor documentation issues
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. >> 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. > > 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. 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). > 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. Right. I think that's a design bug, and definitely worth documenting explicitly for the unwary in the meantime. > 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>. 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: > | [...] > | 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). 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. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
