Bug#538665: debian-policy: Info documents section is outdated
On Sun, Aug 16, 2009 at 11:36:29AM -0700, Russ Allbery wrote: Bill Allombert bill.allomb...@math.u-bordeaux1.fr writes: On Fri, Aug 14, 2009 at 09:52:59AM -0700, Russ Allbery wrote: The generated file should contain a section like: @dircategory Individual utilities @direntry * example: (example). An example info directory entry. @end direntry which will cause makeinfo to generate the directory entry information. Probably this information should be included as a footnote in policy. It is -- that's a footnote in the current Policy document. Excellent! This has been in the patch since the start and I always managed to skip it. Cheers, -- Bill. ballo...@debian.org Imagine a large red swirl here. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
On Fri, Aug 14, 2009 at 12:14:16PM -0700, Russ Allbery wrote: Raphael Hertzog hert...@debian.org writes: On Fri, 14 Aug 2009, Russ Allbery wrote: --- a/policy.sgml +++ b/policy.sgml @@ -8867,7 +8867,10 @@ name [varsyshostname/var]: scripts. This is no longer necessary. The installation system now uses dpkg triggers. /footnote - This file must not be included in packages. + This file must not be included in packages. Packages containing + info documents should depend on ttdpkg (= 1.15.4) | + install-info/tt to ensure that the directory file is properly + rebuilt during upgrades from Debian 5.0 (lenny) and earlier. /p p Does that look good to everyone? Yes, but it really concerns partial upgrades only. So you might want to say so (s/upgrades/partial upgrades/). Okay, I'll make that change. One can argue that a full upgrade is just a sequence of partial upgrades, though this certainly makes 's/upgrades/partial upgrades/' more accurate. Cheers, -- Bill. ballo...@debian.org Imagine a large red swirl here. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
On Fri, Aug 14, 2009 at 09:52:59AM -0700, Russ Allbery wrote: Bill Allombert bill.allomb...@math.u-bordeaux1.fr writes: Reading the comment I will assume that debiandoc2info is the only package that need to be fixed and waive this part. I will also try to get debiandoc2info fixed. Hmm. debiandoc2info is just generating a texinfo file and call makeinfo on it. makeinfo does not generate START-INFO-DIR-ENTRY/END-INFO-DIR-ENTRY by itself. How are we supposed to proceeed ? The generated file should contain a section like: @dircategory Individual utilities @direntry * example: (example). An example info directory entry. @end direntry which will cause makeinfo to generate the directory entry information. Probably this information should be included as a footnote in policy. At this stage, it is still unclear to me what is the expected/correct process to get the START-INFO-DIR-ENTRY/END-INFO-DIR-ENTRY included in an info file. The data that used to be passed to install-menu now need to be provided higher in the chain. Cheers, -- Bill. ballo...@debian.org Imagine a large red swirl here. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
Bill Allombert bill.allomb...@math.u-bordeaux1.fr writes: On Fri, Aug 14, 2009 at 09:52:59AM -0700, Russ Allbery wrote: The generated file should contain a section like: @dircategory Individual utilities @direntry * example: (example). An example info directory entry. @end direntry which will cause makeinfo to generate the directory entry information. Probably this information should be included as a footnote in policy. It is -- that's a footnote in the current Policy document. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
On Tue, Aug 11, 2009 at 10:56:18AM -0700, Russ Allbery wrote: Bill Allombert bill.allomb...@math.u-bordeaux1.fr writes: 1) As written, the policy change induce maintainers to make changes to their packages that will cause them to have a bug. This is not acceptable. 2) As discussed previously, there are ways to tweak the process to avoid this bug while keeping the advantage of this change, and so it should be done. I'm happy to add a statement that packages should depend on dpkg (= 1.15.4) | install-info if they contain info documents. I think that's a reasonable thing to do as part of the transition. Would that address these two concerns? Yes, I would second the proposal with such an amendment. 4) While I have no technical objection to the 'START-INFO-DIR-ENTRY' / 'END-INFO-DIR-ENTRY' bits, currently at least one program generating info files (debiandoc2info) does not follow them. Packages using it to generate their info files would have a bug under this policy without an easy way to fix it, so maybe it is a bit premature. Reading the comment I will assume that debiandoc2info is the only package that need to be fixed and waive this part. I will also try to get debiandoc2info fixed. Cheers, -- Bill. ballo...@debian.org Imagine a large red swirl here. signature.asc Description: Digital signature
Bug#538665: debian-policy: Info documents section is outdated
On Fri, Aug 14, 2009 at 11:51:19AM +0200, Bill Allombert wrote: 4) While I have no technical objection to the 'START-INFO-DIR-ENTRY' / 'END-INFO-DIR-ENTRY' bits, currently at least one program generating info files (debiandoc2info) does not follow them. Packages using it to generate their info files would have a bug under this policy without an easy way to fix it, so maybe it is a bit premature. Reading the comment I will assume that debiandoc2info is the only package that need to be fixed and waive this part. I will also try to get debiandoc2info fixed. Hmm. debiandoc2info is just generating a texinfo file and call makeinfo on it. makeinfo does not generate START-INFO-DIR-ENTRY/END-INFO-DIR-ENTRY by itself. How are we supposed to proceeed ? Cheers, -- Bill. ballo...@debian.org Imagine a large red swirl here. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
Bill Allombert bill.allomb...@math.u-bordeaux1.fr writes: Reading the comment I will assume that debiandoc2info is the only package that need to be fixed and waive this part. I will also try to get debiandoc2info fixed. Hmm. debiandoc2info is just generating a texinfo file and call makeinfo on it. makeinfo does not generate START-INFO-DIR-ENTRY/END-INFO-DIR-ENTRY by itself. How are we supposed to proceeed ? The generated file should contain a section like: @dircategory Individual utilities @direntry * example: (example). An example info directory entry. @end direntry which will cause makeinfo to generate the directory entry information. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
Bill Allombert bill.allomb...@math.u-bordeaux1.fr writes: On Tue, Aug 11, 2009 at 10:56:18AM -0700, Russ Allbery wrote: I'm happy to add a statement that packages should depend on dpkg (= 1.15.4) | install-info if they contain info documents. I think that's a reasonable thing to do as part of the transition. Would that address these two concerns? Yes, I would second the proposal with such an amendment. Here's a proposed patch to the previous wording. --- a/policy.sgml +++ b/policy.sgml @@ -8867,7 +8867,10 @@ name [varsyshostname/var]: scripts. This is no longer necessary. The installation system now uses dpkg triggers. /footnote - This file must not be included in packages. + This file must not be included in packages. Packages containing + info documents should depend on ttdpkg (= 1.15.4) | + install-info/tt to ensure that the directory file is properly + rebuilt during upgrades from Debian 5.0 (lenny) and earlier. /p p Does that look good to everyone? -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
On Fri, 14 Aug 2009, Russ Allbery wrote: --- a/policy.sgml +++ b/policy.sgml @@ -8867,7 +8867,10 @@ name [varsyshostname/var]: scripts. This is no longer necessary. The installation system now uses dpkg triggers. /footnote - This file must not be included in packages. + This file must not be included in packages. Packages containing + info documents should depend on ttdpkg (= 1.15.4) | + install-info/tt to ensure that the directory file is properly + rebuilt during upgrades from Debian 5.0 (lenny) and earlier. /p p Does that look good to everyone? Yes, but it really concerns partial upgrades only. So you might want to say so (s/upgrades/partial upgrades/). Cheers, -- Raphaël Hertzog -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
Raphael Hertzog hert...@debian.org writes: On Fri, 14 Aug 2009, Russ Allbery wrote: --- a/policy.sgml +++ b/policy.sgml @@ -8867,7 +8867,10 @@ name [varsyshostname/var]: scripts. This is no longer necessary. The installation system now uses dpkg triggers. /footnote - This file must not be included in packages. + This file must not be included in packages. Packages containing + info documents should depend on ttdpkg (= 1.15.4) | + install-info/tt to ensure that the directory file is properly + rebuilt during upgrades from Debian 5.0 (lenny) and earlier. /p p Does that look good to everyone? Yes, but it really concerns partial upgrades only. So you might want to say so (s/upgrades/partial upgrades/). Okay, I'll make that change. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
Russ Allbery r...@debian.org writes: Bill Allombert bill.allomb...@math.u-bordeaux1.fr writes: 1) As written, the policy change induce maintainers to make changes to their packages that will cause them to have a bug. This is not acceptable. 2) As discussed previously, there are ways to tweak the process to avoid this bug while keeping the advantage of this change, and so it should be done. I'm happy to add a statement that packages should depend on dpkg (= 1.15.4) | install-info if they contain info documents. I think that's a reasonable thing to do as part of the transition. Would that address these two concerns? I've neither gotten a reply to this nor has anyone else weighed in who shares Bill's concerns. In the absence of any further discussion on this thread, my intention is to conclude: * A recommendation (should) for the above-mentioned dependency will be added to the new info document section before the 3.8.3 release. * Bill's other objections haven't met with any other agreement, so the consensus is to procede despite them. To use IETF terms, Bill's in the rough part of rough consensus. (I've been there before myself.) * Policy 3.8.3 will be released as originally planned on Saturday with the addition of a recommendation for the above dependency. If anyone disagrees with this, please say something *soon*. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
On Fri, Aug 07, 2009 at 03:37:56PM -0700, Russ Allbery wrote: Sven Joachim svenj...@gmx.de writes: Section 12.2, Info documents, contains outdated information. Nowadays info files are installed via a dpkg trigger provided by the install-info package, and maintainer scripts should not invoke install-info at all. Actually, packages using dh_installinfo will not call install-info if built with debhelper = 7.2.17. Any section information must be placed in the info files themselves, rather than passed as arguments to install-info. Here's a proposed update to the Policy section on info documents. I'm looking for feedback or seconds. diff --git a/policy.sgml b/policy.sgml index ffc721f..2a8934a 100644 --- a/policy.sgml +++ b/policy.sgml @@ -8846,37 +8846,49 @@ name [varsyshostname/var]: /p p - Your package should call prgninstall-info/prgn to update - the Info filedir/file file in its prgnpostinst/prgn - script when called with a ttconfigure/tt argument, for - example: - example compact=compact -install-info --quiet --section Development Development \ - /usr/share/info/foobar.info - /example/p - - p - It is a good idea to specify a section for the location of - your program; this is done with the tt--section/tt - switch. To determine which section to use, you should look - at file/usr/share/info/dir/file on your system and choose the most - relevant (or create a new section if none of the current - sections are relevant). Note that the tt--section/tt - flag takes two arguments; the first is a regular expression - to match (case-insensitively) against an existing section, - the second is used when creating a new one./p - - p - You should remove the entries in the prgnprerm/prgn - script when called with a ttremove/tt argument: - example compact=compact -install-info --quiet --remove /usr/share/info/foobar.info - /example/p + The prgninstall-info/prgn program maintains a directory of + installed info documents in file/usr/share/info/dir/file for + the use of info readers.footnote + It was previously necessary for packages installing info + documents to run prgninstall-info/prgn from maintainer + scripts. This is no longer necessary. The installation + system now uses dpkg hooks. + /footnote + This file must not be included in packages. + /p p - If prgninstall-info/prgn cannot find a description entry - in the Info file you must supply one. See manref - name=install-info section=8 for details./p + Info documents should contain section and directory entry + information in the document for the use + of prgninstall-info/prgn. The section should be specified + via a line starting with ttINFO-DIR-SECTION/tt followed by a + space and the section of this info page. The directory entry or + entries should be included between + a ttSTART-INFO-DIR-ENTRY/tt line and + an ttEND-INFO-DIR-ENTRY/tt line. For example: + example +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* example: (example). An example info directory entry. +END-INFO-DIR-ENTRY + /example + To determine which section to use, you should look + at file/usr/share/info/dir/file on your system and choose + the most relevant (or create a new section if none of the + current sections are relevant).footnote + Normally, info documents are generated from Texinfo source. + To include this information in the generated info document, if + it is absent, add commands like: + example +...@dircategory Individual utilities +...@direntry +* example: (example). An example info directory entry. +...@end direntry + /example + /footnote + to the Texinfo source of the document and ensure that the info + documents are rebuilt from source during the package build. + /p /sect sect I formally object to this change. 1) As written, the policy change induce maintainers to make changes to their packages that will cause them to have a bug. This is not acceptable. 2) As discussed previously, there are ways to tweak the process to avoid this bug while keeping the advantage of this change, and so it should be done. 3) Debian policy is not dpkg or any other package documentation. The mere fact a package change its interface is not ground to update policy without following the policy process (I am not claiming it ever happened). 4) While I have no technical objection to the 'START-INFO-DIR-ENTRY' / 'END-INFO-DIR-ENTRY' bits, currently at least one program generating info files (debiandoc2info) does not follow them. Packages using it to generate
Bug#538665: debian-policy: Info documents section is outdated
On Tue, 11 Aug 2009, Bill Allombert wrote: 1) As written, the policy change induce maintainers to make changes to their packages that will cause them to have a bug. This is not acceptable. 2) As discussed previously, there are ways to tweak the process to avoid this bug while keeping the advantage of this change, and so it should be done. No, it's not true. Quoting debhelper's changelog: * dh_installinfo: No longer inserts install-info calls into maintainer scripts, as that is now triggerized. Adds a dependency via misc:Depends to handle partial upgrades. So package have the required dependency and partial upgrades are correctly supported. And we should not enshrine in policy such transition details, we only describe the currently wanted behaviour. 3) Debian policy is not dpkg or any other package documentation. The mere fact a package change its interface is not ground to update policy without following the policy process (I am not claiming it ever happened). What are we doing here if not following the process? (In other words this remark is useless) 4) While I have no technical objection to the 'START-INFO-DIR-ENTRY' / 'END-INFO-DIR-ENTRY' bits, currently at least one program generating info files (debiandoc2info) does not follow them. Packages using it to generate their info files would have a bug under this policy without an easy way to fix it, so maybe it is a bit premature. You should consider switching away from debiandoc anyway (much like policy wants to move away from it). 5) I am sorry to have to resort to a formal objection for issues which are, in the big picture, small. However if less formal objections are ignored, let it be that way. They have not been ignored. Cheers, -- Raphaël Hertzog -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
Bill Allombert bill.allomb...@math.u-bordeaux1.fr writes: 1) As written, the policy change induce maintainers to make changes to their packages that will cause them to have a bug. This is not acceptable. 2) As discussed previously, there are ways to tweak the process to avoid this bug while keeping the advantage of this change, and so it should be done. I'm happy to add a statement that packages should depend on dpkg (= 1.15.4) | install-info if they contain info documents. I think that's a reasonable thing to do as part of the transition. Would that address these two concerns? 3) Debian policy is not dpkg or any other package documentation. The mere fact a package change its interface is not ground to update policy without following the policy process (I am not claiming it ever happened). I don't entirely agree. Policy needs to not be a roadblock for good things happening in Debian as long as there's general consensus. As long as we can get everything sorted out and consistent within a reasonable length of time, I think it's normal for Policy to not always be perfectly synchronized with other changes. There are, so far as I can see, two options going forward here: either we document how to make info documents work with the current system, since the previous documentation would result in buggy packages that aren't listed in /usr/share/info/dir, or we revert the change to install-info in the archive. Given that the install-info changes are both moving in the correct direction for the rest of the project (towards using triggers instead of maintainer scripts) and are part of resolving a very long-standing issue around divergence of the install-info command, I am opposed to reverting those changes. 4) While I have no technical objection to the 'START-INFO-DIR-ENTRY' / 'END-INFO-DIR-ENTRY' bits, currently at least one program generating info files (debiandoc2info) does not follow them. Packages using it to generate their info files would have a bug under this policy without an easy way to fix it, so maybe it is a bit premature. How is there not an easy way to fix it? I can name a trivial way just off the top of my head: patch those lines into the generated files as part of the build system. Since they go at the top of the info file, the patch is reasonably stable. In fact, since they can always start at the third line of the file, you don't even need to use patch. A simple sed command would do it. Note also that this change is intentionally a should rather than a must, since info documents missing from the dir file is a bug but not an RC bug. This Policy change does not make any packages more buggy than they already are, since any info documents without this metadata are already missing from the dir file and hence already have a bug from the user's perspective. 5) I am sorry to have to resort to a formal objection for issues which are, in the big picture, small. However if less formal objections are ignored, let it be that way. I read all of your objections. I just disagree with you, and so far as I could tell so did everyone else. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
On Tue, Aug 11, 2009 at 06:54:12PM +0200, Raphael Hertzog wrote: On Tue, 11 Aug 2009, Bill Allombert wrote: 1) As written, the policy change induce maintainers to make changes to their packages that will cause them to have a bug. This is not acceptable. 2) As discussed previously, there are ways to tweak the process to avoid this bug while keeping the advantage of this change, and so it should be done. No, it's not true. Quoting debhelper's changelog: * dh_installinfo: No longer inserts install-info calls into maintainer scripts, as that is now triggerized. Adds a dependency via misc:Depends to handle partial upgrades. So package have the required dependency and partial upgrades are correctly supported. That is very good news, but since use of dh_installinfo is not mandatory, the correct dependency to add should be documented. we only describe the currently wanted behaviour. And we should not enshrine in policy such transition details, The current wanted behavior for squeeze includes the dependency so it should be mentionned. There are lot of example of transition plans being mentionned in policy. 3) Debian policy is not dpkg or any other package documentation. The mere fact a package change its interface is not ground to update policy without following the policy process (I am not claiming it ever happened). What are we doing here if not following the process? (In other words this remark is useless) Or rather it serves a purpose in a different channel this message is also a part of. Sorry for the confusion. 4) While I have no technical objection to the 'START-INFO-DIR-ENTRY' / 'END-INFO-DIR-ENTRY' bits, currently at least one program generating info files (debiandoc2info) does not follow them. Packages using it to generate their info files would have a bug under this policy without an easy way to fix it, so maybe it is a bit premature. You should consider switching away from debiandoc anyway (much like policy wants to move away from it). Thanks you, but I like debiandoc very much. Cheers, -- Bill. ballo...@debian.org Imagine a large red swirl here. signature.asc Description: Digital signature
Bug#538665: debian-policy: Info documents section is outdated
On Fri, 07 Aug 2009, Russ Allbery wrote: Here's a proposed update to the Policy section on info documents. I'm looking for feedback or seconds. Seconded but: + at file/usr/share/info/dir/file on your system and choose + the most relevant (or create a new section if none of the + current sections are relevant).footnote + Normally, info documents are generated from Texinfo source. + To include this information in the generated info document, if + it is absent, add commands like: + example +...@dircategory Individual utilities +...@direntry +* example: (example). An example info directory entry. +...@end direntry + /example + /footnote + to the Texinfo source of the document and ensure that the info + documents are rebuilt from source during the package build. + /p I think you want to move the /footnote two lines further... Cheers, -- Raphaël Hertzog signature.asc Description: Digital signature
Bug#538665: debian-policy: Info documents section is outdated
Hi! On Fri, 2009-08-07 at 15:37:56 -0700, Russ Allbery wrote: Here's a proposed update to the Policy section on info documents. I'm looking for feedback or seconds. diff --git a/policy.sgml b/policy.sgml index ffc721f..2a8934a 100644 --- a/policy.sgml +++ b/policy.sgml @@ -8846,37 +8846,49 @@ name [varsyshostname/var]: /p p - Your package should call prgninstall-info/prgn to update - the Info filedir/file file in its prgnpostinst/prgn - script when called with a ttconfigure/tt argument, for - example: - example compact=compact -install-info --quiet --section Development Development \ - /usr/share/info/foobar.info - /example/p - - p - It is a good idea to specify a section for the location of - your program; this is done with the tt--section/tt - switch. To determine which section to use, you should look - at file/usr/share/info/dir/file on your system and choose the most - relevant (or create a new section if none of the current - sections are relevant). Note that the tt--section/tt - flag takes two arguments; the first is a regular expression - to match (case-insensitively) against an existing section, - the second is used when creating a new one./p - - p - You should remove the entries in the prgnprerm/prgn - script when called with a ttremove/tt argument: - example compact=compact -install-info --quiet --remove /usr/share/info/foobar.info - /example/p + The prgninstall-info/prgn program maintains a directory of + installed info documents in file/usr/share/info/dir/file for + the use of info readers.footnote + It was previously necessary for packages installing info + documents to run prgninstall-info/prgn from maintainer + scripts. This is no longer necessary. The installation + system now uses dpkg hooks. Probably better to spell it as “dpkg triggers”, we might be implementing new features to be referred to as “dpkg hooks” in the future. + /footnote + This file must not be included in packages. + /p p - If prgninstall-info/prgn cannot find a description entry - in the Info file you must supply one. See manref - name=install-info section=8 for details./p + Info documents should contain section and directory entry + information in the document for the use + of prgninstall-info/prgn. The section should be specified + via a line starting with ttINFO-DIR-SECTION/tt followed by a + space and the section of this info page. The directory entry or + entries should be included between + a ttSTART-INFO-DIR-ENTRY/tt line and + an ttEND-INFO-DIR-ENTRY/tt line. For example: + example +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* example: (example). An example info directory entry. +END-INFO-DIR-ENTRY + /example + To determine which section to use, you should look + at file/usr/share/info/dir/file on your system and choose + the most relevant (or create a new section if none of the + current sections are relevant).footnote + Normally, info documents are generated from Texinfo source. + To include this information in the generated info document, if + it is absent, add commands like: + example +...@dircategory Individual utilities +...@direntry +* example: (example). An example info directory entry. +...@end direntry + /example + /footnote + to the Texinfo source of the document and ensure that the info + documents are rebuilt from source during the package build. + /p /sect sect Seconded (ideally with the small wording change). regards, guillem signature.asc Description: Digital signature
Bug#538665: debian-policy: Info documents section is outdated
Guillem Jover guil...@debian.org writes: On Fri, 2009-08-07 at 15:37:56 -0700, Russ Allbery wrote: + The prgninstall-info/prgn program maintains a directory of + installed info documents in file/usr/share/info/dir/file for + the use of info readers.footnote +It was previously necessary for packages installing info +documents to run prgninstall-info/prgn from maintainer +scripts. This is no longer necessary. The installation +system now uses dpkg hooks. Probably better to spell it as “dpkg triggers”, we might be implementing new features to be referred to as “dpkg hooks” in the future. I knew I had the wrong term but I was blanking in the right one. Thanks, fixed in my version. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
Sven Joachim svenj...@gmx.de writes: Section 12.2, Info documents, contains outdated information. Nowadays info files are installed via a dpkg trigger provided by the install-info package, and maintainer scripts should not invoke install-info at all. Actually, packages using dh_installinfo will not call install-info if built with debhelper = 7.2.17. Any section information must be placed in the info files themselves, rather than passed as arguments to install-info. Here's a proposed update to the Policy section on info documents. I'm looking for feedback or seconds. diff --git a/policy.sgml b/policy.sgml index ffc721f..2a8934a 100644 --- a/policy.sgml +++ b/policy.sgml @@ -8846,37 +8846,49 @@ name [varsyshostname/var]: /p p - Your package should call prgninstall-info/prgn to update - the Info filedir/file file in its prgnpostinst/prgn - script when called with a ttconfigure/tt argument, for - example: - example compact=compact -install-info --quiet --section Development Development \ - /usr/share/info/foobar.info - /example/p - - p - It is a good idea to specify a section for the location of - your program; this is done with the tt--section/tt - switch. To determine which section to use, you should look - at file/usr/share/info/dir/file on your system and choose the most - relevant (or create a new section if none of the current - sections are relevant). Note that the tt--section/tt - flag takes two arguments; the first is a regular expression - to match (case-insensitively) against an existing section, - the second is used when creating a new one./p - - p - You should remove the entries in the prgnprerm/prgn - script when called with a ttremove/tt argument: - example compact=compact -install-info --quiet --remove /usr/share/info/foobar.info - /example/p + The prgninstall-info/prgn program maintains a directory of + installed info documents in file/usr/share/info/dir/file for + the use of info readers.footnote + It was previously necessary for packages installing info + documents to run prgninstall-info/prgn from maintainer + scripts. This is no longer necessary. The installation + system now uses dpkg hooks. + /footnote + This file must not be included in packages. + /p p - If prgninstall-info/prgn cannot find a description entry - in the Info file you must supply one. See manref - name=install-info section=8 for details./p + Info documents should contain section and directory entry + information in the document for the use + of prgninstall-info/prgn. The section should be specified + via a line starting with ttINFO-DIR-SECTION/tt followed by a + space and the section of this info page. The directory entry or + entries should be included between + a ttSTART-INFO-DIR-ENTRY/tt line and + an ttEND-INFO-DIR-ENTRY/tt line. For example: + example +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* example: (example). An example info directory entry. +END-INFO-DIR-ENTRY + /example + To determine which section to use, you should look + at file/usr/share/info/dir/file on your system and choose + the most relevant (or create a new section if none of the + current sections are relevant).footnote + Normally, info documents are generated from Texinfo source. + To include this information in the generated info document, if + it is absent, add commands like: + example +...@dircategory Individual utilities +...@direntry +* example: (example). An example info directory entry. +...@end direntry + /example + /footnote + to the Texinfo source of the document and ensure that the info + documents are rebuilt from source during the package build. + /p /sect sect -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
Package: debian-policy Version: 3.8.2.0 Severity: normal Section 12.2, Info documents, contains outdated information. Nowadays info files are installed via a dpkg trigger provided by the install-info package, and maintainer scripts should not invoke install-info at all. Actually, packages using dh_installinfo will not call install-info if built with debhelper = 7.2.17. Any section information must be placed in the info files themselves, rather than passed as arguments to install-info. -- System Information: Debian Release: squeeze/sid APT prefers unstable APT policy: (500, 'unstable') Architecture: i386 (x86_64) Kernel: Linux 2.6.30.2-rc1-amd64 (SMP w/2 CPU cores) Locale: LANG=de_DE.UTF-8, LC_CTYPE=de_DE.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/dash debian-policy depends on no packages. debian-policy recommends no packages. Versions of packages debian-policy suggests: ii doc-base 0.9.3 utilities to manage online documen -- no debconf information -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#538665: debian-policy: Info documents section is outdated
merge 534638 538665 thanks Uh, somehow I missed #534638. Sorry for the noise. Embarrassed, Sven -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
