On Thu, May 24, 2012 at 11:07 AM, Justin B Rye <[email protected]> wrote: > Christian PERRIER wrote: >>> David Kalnischkies <[email protected]> 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. > [...] >> [email protected] 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 -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: http://lists.debian.org/caaz6_fajp7igzxtuc2ztdv1eesraxa9q75g5dtwar4omkgz...@mail.gmail.com
