Re: Updated maint-guide contents, question on style, my thought
I applied Justin's patch. Thanks.
On Mon, Apr 18, 2011 at 10:22:16PM +0100, Justin B Rye wrote:
> Osamu Aoki wrote:
> > Sun, Apr 17, 2011 at 09:59:18PM +0200, Serafeim Zanikolas wrote:
> >> Hi Osamu,
> > ...
> >> It's certainly a step in the right direction. There's a number of style
> >> improvements that could be done:
> >> s/prospectus/prospective/
> > Justin kept this. Which is better?
> Did I? I changed it in at least one place.
> Prospective developers are people likely to become (or hoping to
> become) developers; prospectus developers are brochure designers. The
> package description uses "wannabe developer", which is a much more
> informal equivalent.
I see. Thanks
> >> s/pretty common language/simple language/
> > This part was Joy's phrases. (I do not speak Latin.)
> > Justin rephrased differently. I will take Justin's:
> >> +This document tries to describe the building of a Debian package to ordinary
> >> +Debian users and prospective developers. It uses fairly non-technical language, and
> >> +it's well covered with working examples. There is an old Latin saying:
> >> +<emphasis>Longum iter est per preacepta, breve et efficax per
> Whoops, mea culpa, the old version had "preaecepta", which is wrong,
> but I've taken out the wrong <e>! It's "longum iter est per
> praecepta, breve et efficax per exempla" (Seneca).
> >> Also, I find odd the use of first person, eg:
> >> Here are my observations of the social dynamism of Debian. I hope this
> >> will prepare you for the interaction with Debian.
> > This part was "I" since this was "my" observation and was not from any
> > agreeed-on things. ... if you also think these are general statement, I can
> > switch them to "we" or any other good statement you suggest.
> Come to think of it you can sneak your way round it like this:
> Here are some observations of Debian's social dynamics,
> presented in the hope that it will prepare you for
> interactions with Debian.
> (Or something. It's not worth doing if you still have leftover
I took this.
> >> In the explanation of quilt, what does "traveling into the stack"
> >> mean?
> > This expression was taken from the package description of quilt.
> (But not http://savannah.nongnu.org/projects/quilt)
I took this since this is not the place to go into pop and push for
I changed from "to easily manage..." to "to manage...". to avoid split
> > All long manual local links are PDF if available. (Better looking)
> For me in iceweasel, clicking fails, "Copy Link Location" and pasting
> it into the URL-bar succeeds. So I don't know what's going on there.
PLease install xpdf :-)
Oh, was not usable. So I touched up common.ent to allow it.
> >> 1.3 para 6+, 1.4: you insist that maintainers should "thoroughly read
> >> the documentation of each program, at least" (preferably more than
> >> once). This is only necessary if my trial package is written in mixed
> >> Fortran and Pascal using both autoconf and imake! On the other hand,
> >> I probably will need to skim the docs for make, and there's no "see
> >> man page" link for that because it's build-essential.
> > Very good point. I was wondering what to do. I agree people needs to
> > skim these first. Tey need to come back as needed. They still need to
> > read intensively for devscripts related things. Suggestion for good text?
> It might be enough simply to insert the word "relevant" somewhere and
> add a bulletpoint for make. Or would we need to cover gcc and so on
Let me thing a bit.
> >> 1.5 on source packages and binary packages: excuse me while I rant.
> >> It seems to me that newcomers are *entitled* to be confused by this
> >> terminology. A "source package" need contain no sourcecode (not all
> >> languages are compiled), and a "binary package" may contain nothing
> >> but ASCII text (it may even be sourcecode). I've never understood why
> >> we need to call the tarball plus separate .diff.gz and .dsc files a
> >> "package" in the first place! Alas, getting programmers to change
> >> their private jargon is a hopeless cause.
> > I initially got confused. Redhat SRPM was single archived file with all
> > of these. Let's think short nice inro.
> Oh, there's no need for this sort of spleen-venting to go into the
> text. Maybe if I can collect enough of these I should go and write a
> "Debian Jargon Origins" page in the wiki. Meanwhile, I need to do the
> opposite and find a good "positive" way of presenting it so it all
> seems to make sense... Here's a very rough idea:
> There are two types of packages.
> * binary package: these are ordinary installable packages in .deb
> format (or .udeb format, used by the Debian Installer);
> * source package: this is the name given to the set of files used as
> input to the Debian package-building process - usually a .tar.gz
> file, a .diff.gz and a .dsc file, whose functions will be
> explained later.
> Footnote: this terminology follows the analogy of program sourcecode
> being compiled into a binary. Never mind the fact that we're
> calling linux-source-2.6*.deb a binary package.
At this stage, we should not be too pedantic on these terminology.
Maybe we give basic idea and leave exact definition to dev-ref or
> >> 1.5 on versioning: this explanation of "versions" and "revisions"
> >> and "Debian versions" is wrong. Policy doesn't use the jargon
> >> described here; it just uses the variable names "upstream_version"
> >> and "debian_revision". Correcting that leaves us with vacuous
> >> non-definitions like this:
> >> * upstream source version: the upstream source version is referred
> >> to as the upstream version.
> > This is inherited. I think we need to standarize to "upstream_version"
> > and "debian_revision" if possible.
> >> But this still isn't true - the "upstream_version" is the
> >> Policy-compliant version string used for the Debianised sources. If
> >> the upstream author uses a version string beginning with a letter
> >> then the "upstream_version" will be a different string.
> > Since this is a convoluted problem, let me think a bit more before
> > acting on them.
> I've ended up with something that's getting much longer:
> The version numbering of Debian packages is formed from up to three
> elements (see policy 5.6.12):
> * the epoch: this may occur as a number prefixed to the Debian
> version string to deal with hiccups in the numbering scheme;
> * the upstream_version component: this is the version number for the
> source package, based on (usually identical to) the number used by
> upstream for the source release.
> * the debian_revision component: this is a secondary label used to
> distinguish successive forms of the same upstream source release,
> as packaged for Debian.
> The complete Debian package version for a normal binary package is
> built up as upstream_version-debian_revision (or
> epoch:upstream_version-debian_revision if an epoch is needed). For
> "native" packages, with no separate upstream [see ...], only an
> upstream_version is needed.
> But is this really something that needs to be explained here anyway?
> Maybe it would fit better in 2.4.
This is exactly along my thought. Anyway, this is introductory chapter.
Let's see how it comes out as html on web.