Re: Request for Review: APT manpages
On Thu, May 24, 2012 at 11:07 AM, Justin B Rye <jbr@edlug.org.uk> wrote:
> Christian PERRIER wrote:
>>> David Kalnischkies <kalnischkies@gmail.com> writes:
>>>> I would like to ask if someone here is willing to do a (partial) review
>>>> of the manpages associated to debians beloved package manager APT.
> [...]
>> deity@lists.debian.org is the APT development mailing list. I think
>> that CC'ing the list wouldn't harm.
>
> Okay, just to test the waters here's a review for apt-cache.8.xml.
>
> First general point: the example given is pretty cobwebby.
>
> [...]
>> <para>Thus it may be seen that libreadline2, version 2.1-12, depends on
>> libc5 and ncurses3.0 which must be installed for libreadline2 to work.
>> In turn, libreadlineg2 and libreadline2-altdev depend on libreadline2. If
>> libreadline2 is installed, libc5 and ncurses3.0 (and ldso) must also be
>> installed; libreadlineg2 and libreadline2-altdev do not have to be
>> installed. For the specific meaning of the remainder of the output it
>> is best to consult the apt source code.</para></listitem>
>> </varlistentry>
>
> It doesn't matter so much that libreadline2 and libc5 are long dead;
I stumbled over the same a while ago but did nothing to improve it
so far beside writing it down for 'change at some point'…
Will try to brush up the example a bit, should be relatively easy to
do even in the po's with a bit of care.
> more significant is the passing reference to "ldso". Do I understand
> that was an essential package back in the nineties?
Good question, i don't know… lets see… #629983.
Sounds like a lot of readers will get the reference…
(will be nuked together with example rework)
> I've left this unchanged, but I *have* changed "the Debian GNU/Linux
> system" to "the Debian system" throughout.
Oh yeah, the old days with just one kernel…
(removed 'GNU/Linux' from all manpages and po(t)s)
> [...]
>> <listitem><para><literal>Total distinct</literal> versions is the number of package versions
>> found in the cache; this value is therefore at least equal to the
>> number of total package names. If more than one distribution (both
>> "stable" and "unstable", for instance), is being accessed, this value
>> can be considerably larger than the number of total package names.</para>
>> </listitem>
>
> Slightly unidiomatic and mis-punctuated. I suggest "If more than one
> distribution is being accessed (for instance, both "stable" and
> "unstable"), [...]"
>
> I suspect it's also very subtly cobwebby (pre-dating "testing"), but
Indeed. I looked through the translations and the few i can at least
barley understand seem to be more-or-less word-by-word, so fuzzing
here might benefit them, too. And as it is already fuzzy i removed the
"both" from the example - instant post-dating. ;)
> never mind. For all I know the word "architecture" (singular) might
> also need attention in one or two places, but I haven't tried to catch
> cases like this.
Good point, i will take a look at them. We might get away with it
as all commands work only on one architecture and treat
pkg:amd64 vs. pkg:armel as different packages instead of
e.g. the same package with different architecture…
>> <varlistentry><term><option>showsrc</option> <option><replaceable>&synopsis-pkg;</replaceable>…</option></term>
>> <listitem><para><literal>showsrc</literal> displays all the source package records that match
>> the given package names. All versions are shown, as well as all
>> records that declare the name to be a Binary.</para></listitem>
>> </varlistentry>
>
> A sudden unexplained technical term in Germancaps; I've substituted "a
> binary package".
Makes sense. fuzzy +1.
>> <varlistentry><term><option>dumpavail</option></term>
>> <listitem><para><literal>dumpavail</literal> prints out an available list to stdout. This is
>> suitable for use with &dpkg; and is used by the &dselect; method.</para></listitem>
>> </varlistentry>
>
> Obviously dated, but presumably still true. I would prefer it if it
> gave more of a hint that "an available list" is jargon (or even
> defined it), and maybe referred to "standard output", but that's not
> in my patch.
Mhh, yeah, that needs to be changed. How about:
+ <listitem><para><literal>dumpavail</literal> prints a list of all
+ available packages to standard output. This can be used as an
+ <filename>available</filename> file for &dpkg; and is used by
+ the &dselect; method.</para></listitem>
(you might actually need this nowadays again as dpkg forbids you
to set (uninstalled) packages on hold it doesn't know about.)
> [...]
>> <para>The resulting nodes will have several shapes; normal packages are boxes,
>> pure provides are triangles, mixed provides are diamonds,
>> missing packages are hexagons. Orange boxes mean recursion was stopped
>> [leaf packages], blue lines are pre-depends, green lines are conflicts.</para>
>
> The terms you defined above were "pure virtual packages" and "mixed
> virtual packages", so please use the jargon the translators have
> already worked out equivalents for, not this confusing alternative.
Right. Changed.
> Also (but not in my patch), why the []s?
Mhh. I don't know. I guess every bracket will do so changed to "normal" ().
>> <para>Caution, dotty cannot graph larger sets of packages.</para></listitem>
>> </varlistentry>
>>
>> <varlistentry><term><option>xvcg</option> <option><replaceable>&synopsis-pkg;</replaceable>…</option></term>
>> <listitem><para>The same as <literal>dotty</literal>, only for xvcg from the
>> <ulink url="http://rw4.cs.uni-sb.de/users/sander/html/gsvcg1.html";>VCG tool</ulink>.
>> </para></listitem></varlistentry>
>
> Very cobwebby; the homepage is a fossil, and the package was RMed when
> GraphViz went free. But presumably it's still true...
We should really get right of 'dotty' and 'xvcg' command and instead
deploy them as options for (r)depends… but yeah, as-is still true.
(even through i couldn't even find a program which can actually display
these (x)vcg graphs, but i tried not too hard…)
>> <varlistentry><term><option>madison</option> <option><replaceable>&synopsis-pkg;</replaceable>…</option></term>
>> <listitem><para><literal>apt-cache</literal>'s <literal>madison</literal> command attempts to mimic
>> the output format and a subset of the functionality of the Debian
>> archive management tool <literal>madison</literal>. It displays
>> available versions of a package in a tabular format. Unlike the
>> original <literal>madison</literal>, it can only display information for
>> the architecture for which APT has retrieved package lists
>> (<literal>APT::Architecture</literal>).</para></listitem>
>> </varlistentry>
>> </variablelist>
>> </refsect1>
>
> Madison has been an alias for "dak ls" for ages now (did users ever
> have access to it anyway?), so it's a bit unfair to use the term as if
> readers could be expected to know what functionality it implies.
Fishy indeed. In the long run i guess we are better of dropping this
'madison' reference altogether. The command itself can be useful at
times to know which versions (binary + source) are available,
but the name doesn't transport this at all, but using "dak ls" will not
really improve that either.
I would exchange the first and second sentence, but its such a minor
improvement that i am not sure we should bother translators with it.
>> <varlistentry><term><option>-i</option></term><term><option>--important</option></term>
>> <listitem><para>Print only important dependencies; for use with unmet and depends. Causes only Depends and
>> Pre-Depends relations to be printed.
>
> "Unmet" and "depends" need <literal> tags.
Thanks! (unfuzzied translations in which i could identify the words,
in one they seems to be translated - so good you got that)
>> <varlistentry><term><option>-a</option></term><term><option>--all-versions</option></term>
>> <listitem><para>Print full records for all available versions. This is the
>> default; to turn it off, use <option>--no-all-versions</option>.
>> If <option>--no-all-versions</option> is specified, only the candidate version
>> will displayed (the one which would be selected for installation).
> ^
> This is the only absolutely necessary English fix: insert "be".
Done. (unfuzzied all translations)
Thanks a lot! I have pushed that stuff and as Michael prepares a bugfix
release currently he merged it already, so you should see these changes
already live in a few hours (depending on buildd and dinstall).
So, who is next? ;)
Best regards
David Kalnischkies
Reply to: