From: Russ Allbery <rra@debian.org>
Date: Fri, 7 Aug 2009 22:34:31 +0000 (-0700)
Subject: Rewrite info documents section
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=b4f1df6b844c4bb23b9526014cdd9f855e478b07;p=debian%2Fdebian-policy.git

Rewrite info documents section

install-info now uses dpkg hooks, so remove all requirements for running
install-info in package maintainer scripts.  Document the necessary info
directory information and provide Texinfo modification instructions in a
footnote.  Explicitly forbid packages from including /usr/share/info/dir.
---

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>