[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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
> 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.


> 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

> 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.


Reply to: