Re: Updated maint-guide contents, question on style, my thought
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.
>> 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
first-persons.)
>> Justin B Rye wrote:
[...]
>> 1.3 para 2: the releasenotes say that these days apt-get is
>> preferred over aptitude for commandline package-management (besides,
>> aptitude might not be installed), so say "apt-get search foo".
>
> Not quite. It is recommended for the action of "apt-get dist-upgrade".
>
> "apt-cache show foo" and "aptitude show foo" are as good for this.
>
> Besides, aptitude is needed to make quick interactive package search.
Well, I won't push for it because in fact I'm a diehard textmode
aptitude user myself.
[...]
>> 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)
> travel = push and pop action to move to particular level of patch stack.
Yes, but here you're taking "pushing" and "popping" a stack for
granted as well-known concepts that you can use to explain "traveling
into the stack" as a metaphor. In the text, "pushing" and "popping"
are presented as actions that can be performed *by* "traveling into
the stack" (as if it meant that I could manipulate the patches by
simply pulling up on my joystick).
>> By the way, do these documentation pointers really need to use URIs
>> like "file:///usr/share/doc/quilt/quilt.pdf.gz"? If I'm reading
>> file:///usr/share/doc/maint-guide/ch-start.en.html, and quilt is also
>> installed, I would prefer a link to "../quilt/quilt.html" so I can
>> just open another tab in my browser...
>
> I made all HTML links to www.debian.org site. Only local files are
> mentioned in file:///... . It opens with my browser here with xpdf.
>
> 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.
>> 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?
>> 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.
[...]
>> 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.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: