Re: Request for Review: APT manpages
On Fri, May 25, 2012 at 1:38 AM, Justin B Rye <jbr@edlug.org.uk> wrote:
> I'm skipping apt.conf for now because it's horrible, so next it's
> apt-config.
Like in "horrible good"? ;)
Yeah, it is the worst one… long, at times very technical…
But i don't want to discourage you completely. ;)
Your review already helped me quiet a bit to figure out what needs
to be done for wheezy+1 - beside all the correction itself of course.
>> <refsect1><title>Description</title>
>> <para><command>apt-config</command> is an internal program used by various
>> portions of the APT suite to provide consistent configurability. It accesses
>> the main configuration file <filename>/etc/apt/apt.conf</filename> in a
>> manner that is easy to use by scripted applications.</para>
> ^^
> "By" would need a passive or something; say "for".
Done.
>> <para>Unless the <option>-h</option>, or <option>--help</option> option is
>> given one of the commands below must be present.
>> </para>
>>
>> <variablelist>
>> <varlistentry><term><option>shell</option></term>
>> <listitem><para>
>> shell is used to access the configuration information from a shell
>> script. It is given pairs of arguments, the first being a shell
>> variable and the second the configuration value to query. As output
>> it lists a series of shell assignments commands for each present value.
> ^^^^^^^^^^^
> Drop this phrase - it lists one command for each value, not a series
> of commands for each value.
>
>> In a shell script it should be used like:
>
> s/like/as follows/
Thanks for both. The first is indeed strange and as at least the german
translation has the same strangeness i kept the string as fuzzy.
The second one would properly be okay to push as typo to the
translations, but as it is the same string…
>> <term><option>--format '<replaceable>%f "%v";%n</replaceable>'</option></term>
>> <listitem><para>Defines the output of each config option. %t will be replaced with the name of the option,
>> %f with the complete optionname and %v with the value of the option.
>> Use uppercase letters and special characters in the value will be encoded to ensure that
>> it can e.g. be savely used in a quoted-string as defined by RFC822. Additionally
>> %n will be replaced by a newline, %N by a tab. A % can be
>> printed by using %%.</para></listitem>
>
> The distinction between "the name of the option" and "the complete
> optionname" is a bit obscure; I've rephrased it as "its individual
> name" and "its full hierarchical name", and fixed s/savely/safely/.
Yeah! I talked with the german translator about that paragraph
(as it is a pretty new paragraph), but wasn't able to produce something
more meaningful than optionname (compared to tagname, which the
source uses and was my first try). Yours is much better already!
> But what is that bit about uppercase letters and special characters
> trying to say? I don't see anything in RFC822's definition of
> quoted-string about uppercase letters... how does the first clause of
> that sentence relate to the rest?
I had two different versions for this paragraph so far, so let me try
to describe what I intended to say and might be that makes a bit
of sense in the end so that we can come up with a better 3th version:
Lets imagine the option 'apt::l10ns' with the value 'en de fr'.
For this example the value for the placeholders would be:
%t == %T == language
%f == %F == apt::language
%v == en de fr
%V == en%20de%20fr
RFC822 doesn't say anything about uppercase letters - I am trying to say
that you can use uppercase letters in case you want output which can be
put into a quoted-string (which is defined by RFC822).
In the example above it is maybe not completely obvious, but imagine the
value contains any really "serious" special character like a newline or
even a quotation mark -- if you would have any of these in your quoted-
string you end up with a mess.
apt-config's audience should be one with a bit of coding background,
but even if not this paragraph is somehow intended give the underlying hint:
"Heh, don't be scared if you don't know what this means in detail,
just ignore it. If you need it you will know what it means"
That is also the reason for not making this a detailed paragraph with
an example and all that so far, i didn't want to let this sound to important…
That said, i notice now that this paragraph doesn't even mention
that this option only has an effect for 'dump', so this definitely
needs rework. And as said, the string is new, so for most translations
this is exchanging an untranslated with an untranslated string.
So feel free to suggest whatever you like most.
Best regards
David Kalnischkies
Reply to: