Re: Request for Review: APT manpages
On Thu, May 24, 2012 at 9:29 PM, Justin B Rye <jbr@edlug.org.uk> wrote:
> Next in alphabetical order, apt-cdrom.8.xml:
>
> [...]
>> <refsect1><title>Description</title>
>> <para><command>apt-cdrom</command> is used to add a new CDROM to APTs list
> ^ ^
> Missing hyphen in "CD-ROM" (yes, the dictionary says there's a
> hyphen, even though it's usually written solid and lowercase in
> variable-names and so on);
Fixed in the docs. (Interestingly enough, most translators had this
already fixed for themselves, just not necessarily everywhere…)
With have this 'cdrom' and 'CDROM' thing also in the program translations
quiet a few times, so i will try to fix that there, too.
> There should probably be a mention somewhere of DVD/BD/etc media,
> and here is the obvious place for it - maybe something like:
>
> <para><command>apt-cdrom</command> is used to add new media
> (such as CD-ROMs or DVDs) to APT's list
I will leave that as is for now, but after wheezy this manpage needs some
improvements: It is not only that apt-cdrom supports CD, DVD and whatever
disc your kernel can mount, but also e.g. usb sticks and co.
So basically all removable data storage… this whole text needs an update,
but if i do this now Christian is properly going to kill me, right?
>> scan it and copy the index files. If the disc does not have a proper
>> <filename>disk</filename> directory you will be prompted for a descriptive
>> title.
>> </para>
>
> Is that really a "<filename>disk</filename> directory" or is this a
> typo?
I will check that later with a real CD, but the code suggests that the
directory is called ".disk", so really 'k' here (but a hidden directory,
so i added the dot). Doesn't make that much sense on first glance,
but in the end it is far from the first typo which is uncorrectable
nowadays (e.g. "HTTP referer" comes to mind).
In all other places i followed your suggestion with using "disc".
Never knew before that a disk is not a disc. I thought this was more
of a color vs. colour thing, but yeah, i never really used discs…
>> <varlistentry><term><option>-a</option></term><term><option>--thorough</option></term>
>> <listitem><para>Thorough Package Scan; This option may be needed with some
>> old Debian 1.1/1.2 discs that have Package files in strange places. It
>> takes much longer to scan the CD but will pick them all up.
>
> As it happens I've got a Debian 1.2 CD, but I wouldn't expect
> current APT to support installing things off it!
If you proceed reviewing, prepare yourself for more of these gems.
Fix a bug or remove code working around a bug and you will meet
at least one user who considers that a feature and will be very angry
that you fixed/removed that code up to a point that this is such an
unbearable circumstance that the "problem" is moved to debian-devel.
(see e.g. - even if it had a good outcome in the end - the complain about
an "undocumented change" in the repository format.)
I am waiting for the day on which such a bugfix will be a topic for the ctte.
Anyway, all other not specially mentioned suggestions applied, too.
Not in the branch online yet through, but will be.
Thanks again & best regards
David Kalnischkies
Reply to: