user [email protected]
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
--
To UNSUBSCRIBE, email to [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]
Archive: http://lists.debian.org/20110403013502.GA26376@elie
