Bug#598645: cleanup: dike non-policy

[Jonathan Nieder <jrnieder@gmail.com>]

user debian-policy@packages.debian.org
package debian-policy
tags 598645 - patch
retitle 598645 cleanup: move text out of appendices
usertags 598645 = informative issue
quit

Hi Brian,

Brian Ryans wrote:

> I'd been looking into this for quite a bit, and I'm at an impasse: I
> can't seem to determine what appendices should go.

Thanks for working on this, and sorry for the long silence.  

> I'm proposing that the appendices <appendix id=pkg-*> be removed from
> policy.sgml for now [2], and look at it as "what from this should remain
> in policy or be funnelled elsewhere" instead of "what to remove from
> policy.sgml".

I can see how the appendices would be kind of daunting, but I don't
think that's a good solution.  The text could easily be just forgotten.
How about biting off a smaller piece, e.g. a single subsection of one
of the appendices and figuring out how to make that information easier
to find before removing it?

To illustrate, I have chosen section C.1.5 at random.

> -	<sect1 id="pkg-dpkg-distaddfile">
> -	  <heading>
> -	    <prgn>dpkg-distaddfile</prgn> - adds a file to
> -	    <file>debian/files</file>
> -	  </heading>

Luckily there is a manpage for dpkg-distaddfile(1) already, so our
task is most likely just to make it more easily discoverable and to
make its relationship to policy clearer.

Where is debian/files documented?  Policy §4.12, which says:

	This file is not a permanent part of the source tree; it is
	used while building packages to record which files are being
	generated. dpkg-genchanges uses it when it generates a
	.changes file.

It's a shame the file format is not described in policy; maybe we
should file a wishlist bug report for that?

	It should not exist in a shipped source package, and so it
	(and any backup files or temporary files such as
	files.new[26]) should be removed by the clean target. It may
	also be wise to ensure a fresh start by [etc]

(A normative component: "debian/rules clean" is supposed to remove
debian/files.)

	When dpkg-gencontrol is run for a binary package, it adds an
	entry to debian/files [etc]

Here we learn that the usual interface for generating the file is
dpkg-gencontrol.

	If a package upload includes files besides the source package
	and any binary packages whose control files were made with
	dpkg-gencontrol then [...] dpkg-distaddfile should
	be called to add the file to the list in debian/files.

Aha.  "debian/rules" is supposed to run dpkg-distaddfile for files
meant to be added to debian/files.  But with what arguments?  What
will the result?  Ah, well, the manpage explains that well enough, I
suppose.

> -	  <p>
> -	    Some packages' uploads need to include files other than
> -	    the source and binary package files.
> -	  </p>
> -
> -	  <p>
> -	    <prgn>dpkg-distaddfile</prgn> adds a file to the
> -	    <file>debian/files</file> file so that it will be included in
> -	    the <file>.changes</file> file when
> -	    <prgn>dpkg-genchanges</prgn> is run.
> -	  </p>

So far, already explained well in policy §4.12 but not in
dpkg-distaddfile(1).  Maybe some of this text should be summarized in
that manpage.

> -	  <p>
> -	    It is usually invoked from the <tt>binary</tt> target of
> -	    <file>debian/rules</file>:
> -	    <example>
> -  dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
> -	    </example>
> -	    The <var>filename</var> is relative to the directory where
> -	    <prgn>dpkg-genchanges</prgn> will expect to find it - this
> -	    is usually the directory above the top level of the source
> -	    tree.  The <file>debian/rules</file> target should put the
> -	    file there just before or just after calling
> -	    <prgn>dpkg-distaddfile</prgn>.
> -	  </p>
> -
> -	  <p>
> -	    The <var>section</var> and <var>priority</var> are passed
> -	    unchanged into the resulting <file>.changes</file> file.
> -	  </p>
> -	</sect1>

Footnote for §4.12, maybe?

Sorry to be vague.  Still, hope that helps.

Regards,
Jonathan