Re: Updated maint-guide contents, question on style, my thought
Hi Justin and Serafeim,
Thanks for your quick response. Since this is disscussed on
debian-l10n-english, let me move these.
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?
> 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
> +exempla</emphasis> (It's a long way by the rules, but short and efficient with
> +examples).
> s/is the very scarce resource./is a very scarce resource./
Both of you agreed.
> 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.
On Mon, Apr 18, 2011 at 11:45:04AM +0100, Justin B Rye wrote:
> Justin B Rye wrote:
> > Osamu Aoki wrote:
> >> Also, if you have time, can you read the English source and propose
> >> fixes.
> >
> > Certainly.
>
> Attached is a patch for chapter one. I won't try to explain all of
> the English language fixes, since I intend them to be
> "semantics-preserving", but I will add some commentary below for
> problems with the content (not acted on in the patch).
>
> 1 para 2: auto-updating variables are handy, but in contexts like:
> # This document has been updated for the Debian
> # <literal>&base-release;</literal> release.
> it seems unwise to let it *automatically* claim to have been revised.
I was wondering on this. This &base-release; is used only in 2 places.
It is not meant to be updated. Let me think.
> 1.2: This section's a bit pointless; it should either be expanded to
> include a full explanation of the roles of DDs/DMs/etc. (what happened
> to Debian Contributors?) or reduced to a paragraph of 1.1.
You mean to drop section title and make it part of 1.1. If so, I agree.
I need to update one link.
> 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.
> 1.3 para 4+: my patch sorts the lists into alphabetical order.
Thanks. I think it started as some kind of priority order by Joy. Now
that is is long, alphabetical order is good idea.
> In the explanation of quilt, what does "traveling into the stack"
> mean?
This expression was taken from the package description of quilt.
travel = push and pop action to move to particular level of patch stack.
> 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)
> 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?
> 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.
> 1.5 on DMs: see above on 1.2. Why is this stuck in between the bit
> about source packages and the bit about source versions?
I moved 1.2 from next to 1.5 to above. Any good idea to make these
tight.
> 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.
> And besides, full Debian version strings can be made up of three
> components - there are also epochs.
>
> I can't see how to do a semantics-preserving language-only revision of
> this section; I'll have to leave it untouched and come back to it.
Sure.
> 1.6: I should read "files in /usr/share/doc/dpkg"? I'm not sure
> what that's meant to be pointing at... maybe
> README.feature-removal-schedule?
maybe triggers.txt.gz But dpkg(1) and deb(5) may be what is needed
first.
> JBR with qualifications in linguistics, experience as a Debian
> sysadmin, and probably no clue about this particular package
> --- maint-guide.en.dbk.pristine 2011-04-17 14:35:41.052916002 +0100
> +++ maint-guide.en.dbk 2011-04-18 11:19:04.865258955 +0100
I will review these patches later.
Osamu
Reply to: