Re: Updated maint-guide contents, question on style, my thought
Hi,
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).
Fixed.
> >> 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
> first-persons.)
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
quilt.
I changed from "to easily manage..." to "to manage...". to avoid split
infinitive.
[...]
> > 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
> too?
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
policy.
> [...]
> >> 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.
Good night.
Osamu
Reply to: