Re: [ITR] templates://apt-cacher-ng/{apt-cacher-ng.templates}
Eduard Bloch wrote:
>>> _Description: Preconfigure apt-cacher-ng for transparent requests source rerouting?
>>
>> "Transparent requests source rerouting" is hard to make any sense
>> out of, and reading the documentation doesn't help, since it doesn't
>> use this term "rerouting" at all. Instead, anything more complex
>> than plain proxying (which you've told us isn't what you mean here)
>> is referred to in the docs as "URL remapping". Could you use the
>> same terminology here?
>
> I could. But would a user understand it without reading the introduction
> of the particular chapter in the docs? I doubt that. And if not, please
> suggest terminology that might be understood quickly in a debconf
> message and does not need another large paragraph.
This is just the short description. Novice users probaby have
little hope of understanding it on its own; but if you use the
established terminology, there's a chance the people who have read
the docs might recognise it. The trouble with "rerouting" is that
it sounds as if you're talking about the route that packets take to
reach a given Debian mirror. In fact the phrase "transparent
requests source rerouting" is hard even to parse. Is it
"transparent rerouting of the source of requests", or "source
rerouting of transparent requests", or what?
>> _Description: Configure apt-cacher-ng to use URL remapping?
>>
>>> Apt-cacher-ng can request packages from a mirror of your choosing, instead of
>>> the one requested by the client. One possible use of this feature is quick
>>> changing of the real download mirror for all users without modifying every
>>> single client system. To configure it, sets of source mirrors need to be
>>> configured for various distributions.
>>
>> That's promising, but then ends up unclear. I need to configure
>> source mirrors for... "various distributions"? Maybe you mean:
>>
>> single client system. To configure it, a set of URL remappings
>> needs to be set up for each APT source.
>
> Not at all. I see that "the apt source" is popular terminology among
> users but it's just not correct here. I.e. you can configure multiple
> APT sources, for different releases, for different package types
> (binary/source), for different parts of the repo, but they all could
> still refer to copies of the same origin, full or partial.
So you specifically mean origins? This is gradually getting
clearer. Should the line about "various distributions" have said
something like this?
single client system. To configure it, a set of URL remappings
needs to be set up for each APT origin.
>> (An example might help.)
>
> Examples tend to be long. Much longer than a sane debconf message
> should include, IMHO.
If you can't find a way of phrasing this debconf template that will
fit in the space available, you could always put it in a README and
tell users to read that before running dpkg-reconfigure. But it's
possible I might be able to find a way of phrasing it for you, if
you wouldn't mind starting by explaining it to me.
>>> NOTE: selecting "No automated setup" can leave previously created mirror
>>> configuration behind, which needs to be updated by cache administrator manually.
>>
>> If you select "No automated setup", any updates to an existing
>> configuration will need to be performed manually.
>
> First, isn't addressing the user directly is a bad style and should be
> avoided where possible?
It's bad style to shout at the user (NOTE that this is an
imperative form!), but there's no absolute rule against explicit
second person forms (compare "from a mirror of your choosing" a few
lines above). Avoiding them tends to make sentences longer and less
clear.
That doesn't mean we can talk about "your computer", or here "you
will need to update the configuration manually" - it might be the
company's computer, and you might have underlings to do this work.
But the person that the debconf template is asking to make a
decision is always guaranteed to be "you".
The rule I'm more worried about is that we shouldn't make direct
references to the machinery of answer-selection that might be
inaccurate on some debconf front-ends. I think we're okay with this
phrasing, though.
> Second, it should be mentioned that something is already there. Some
> users where bitching about old configuration left there and not kept
> uptodate anymore.
It covers that already - "any updates [...] will need to be
performed manually". Or is the problem that you can guarantee that
this process _will_ leave the admin with manual work to do? If so,
"any" is inappropriate there, and it should be something like
Selecting "No automated setup" will leave the existing configuration
unchanged. It will need to be updated manually.
(Getting rid of the second person pronoun in passing.)
>> In the control file, you've just reverted to the original. Instead
>
> Not exactly the original but a state in-between. I lost the changes
> applied after your last suggestions.
>
>> Description: caching proxy for APT sources
>> Apt-Cacher NG is yet another implementation of an HTTP proxy for
>> Debian-style software repositories.
>
> It can do RPM so why should I not mention it?
I was working on the basis that it makes more sense to start by
describing the use case this software is "primarily targeted at";
this is after all the description for a .deb that I'm downloading
via APT, not a blurb for the upstream website. However, it would be
easy enough to either add a mention of RPM-style software
repositories or just subtract the "Debian-style" - there's no need
to throw away the whole thing.
> Description: Caching proxy for distribution of software packages
And again you've reverted to the original, complete with
non-DevRef-compliant capitalisation.
> Apt-Cacher NG is yet another implementation of a HTTP proxy for
> software packages, primarily targeted at Debian/Ubuntu packages but
> may also be used with others types.
Didn't you just finish saying that this "yet another implementation"
stuff was lame? But here it is again, with all our fixes thrown
away. Must I go through line by line pointing out each individual
problem? For a start:
* it should be "an HTTP proxy", not "a HTTP proxy", because
aitch-tee-tee-pee begins with a vowel sound;
* there's no such thing as a proxy for packages - what
apt-cacher-ng proxies is requests to package repositories
(including requests for metadata files);
* either "aimed at" or "targeted on" would be more idiomatic;
* the "but may" clause doesn't follow on grammatically from the
"targeted" clause;
* "others types" is ungrammatical - you mean either "others" or
"other types";
* it's unclear whether you're saying that being usable with
non-.debs is a special feature of ACNG or whether it's something
that all the other implementations can do too.
Should I do that all the way through?
--
JBR
Ankh kak! (Ancient Egyptian blessing)
Reply to: