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 ["<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.
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 <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> Seconded (ideally with the small wording change). regards, guillem
signature.asc
Description: Digital signature
