On Fri, Aug 07, 2009 at 03:37:56PM -0700, Russ Allbery wrote: > Sven Joachim <svenjoac@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 ["<var>syshostname</var>"]: > </p> > > <p> > - Your package should call <prgn>install-info</prgn> to update > - the Info <file>dir</file> file in its <prgn>postinst</prgn> > - script when called with a <tt>configure</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 <prgn>prerm</prgn> > - script when called with a <tt>remove</tt> argument: > - <example compact="compact"> > -install-info --quiet --remove /usr/share/info/foobar.info > - </example></p> > + The <prgn>install-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 <prgn>install-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 <prgn>install-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 <prgn>install-info</prgn>. The section should be specified > + via a line starting with <tt>INFO-DIR-SECTION</tt> followed by a > + space and the section of this info page. The directory entry or > + entries should be included between > + a <tt>START-INFO-DIR-ENTRY</tt> line and > + an <tt>END-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 their info files would have a bug under this policy without an easy way to fix it, so maybe it is a bit premature. 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. Cheers, -- Bill. <ballombe@debian.org> Imagine a large red swirl here.
Attachment:
signature.asc
Description: Digital signature