On 07-Mar-2009, Steve Langasek wrote: > On Fri, Mar 06, 2009 at 11:03:57AM +1100, Ben Finney wrote: > > > === modified file 'policy.sgml' […] > > + for Debian. See the “Original source archive” > > + section, below, for policy details of this file. > > + </p> > > Surely, given that this is sgml, you should be referencing "Original > source archive" by id instead of "see below"? My SGML-fu is very weak. The existing text also doesn't give a reference, instead saying “the original source tar file format described below”. I've added a reference now. > > + > > + <p> > > + The actions for this target fetch the original source > > + package, corresponding to the Debian package version, > > This reads wrong. What are "actions for this target"? Should be > "This target fetches [...]" as in the original, or "The target > fetches [...]" if you're trying to avoid repetition. I'm trying to avoid repetition but also being more specific by following the Make documentation in distinguishing the target (which is just a label) from the commands run to achieve that target. But I used the wrong term; changed to “commands for this target”. > > + This target is <em>optional</em>. A common reason to […] > > Why is 'optional' emphasized? I misunderstood the “words … used to distinguish the significance of the various guidelines in this policy document” paragraphs in the “Scope” section, and thought they needed to be emphasised in order to have the described effect. That's not true, though, as I see from the rest of the document. Fixed. > I don't like the speculation about developers' reasons for forgoing (not > 'foregoing', btw) the target. […] > I also wonder if this ought to be a footnote instead. I don't think uscan > should be considered normative in policy. Fixed. Updated patch: === modified file 'policy.sgml' --- policy.sgml 2009-03-05 08:44:48 +0000 +++ policy.sgml 2009-03-07 22:22:45 +0000 @@ -1907,12 +1907,21 @@ <tag><tt>get-orig-source</tt> (optional)</tag> <item> <p> - This target fetches the most recent version of the - original source package from a canonical archive site - (via FTP or WWW, for example), does any necessary + This target generates the original source archive for + the package, such that its contents exactly match the + original source archive used to generate the package + for Debian. + </p> + + <p> + The commands for this target fetch the original source + package, corresponding to the Debian package version, + from a canonical archive site (for example, via FTP, + WWW, or a public VCS repository), do any necessary rearrangement to turn it into the original source - tar file format described below, and leaves it in the - current directory. + archive file format, and leave it in the current + directory. See <ref id="pkg-sourcearchives"> for + policy details of the original source archive. </p> <p> @@ -1922,8 +1931,14 @@ </p> <p> - This target is optional, but providing it if - possible is a good idea. + This target is optional, and in many cases is + unnecessary.<footnote>A common reason to omit this + target is that the upstream developers make available, + for direct download, canonical original source archive + files for each specific version. In these cases, it is + sufficient to create a <file>debian/watch</file> + configuration for <prgn>uscan</prgn> to fetch the + original source archive.</footnote> </p> </item> -- \ “If society were bound to invent technologies which could only | `\ be used entirely within the law, then we would still be sitting | _o__) in caves sucking our feet.” —Gene Kan, creator of Gnutella | Ben Finney <ben@benfinney.id.au>
Attachment:
signature.asc
Description: Digital signature