cvs commit: src/sbin/mdconfig mdconfig.8

[Giorgos Keramidas]

On 2007-05-19 08:07, Bruce Evans <bde at optusnet.com.au> wrote:
>On Fri, 18 May 2007, Giorgos Keramidas wrote:
>>On 2007-05-18 16:41, Kris Kennaway <kris at obsecurity.org> wrote:
>>>On Fri, May 18, 2007 at 01:57:17PM +0000, Giorgos Keramidas wrote:
>>>>keramida    2007-05-18 13:57:17 UTC
>>>>
>>>>  FreeBSD src repository (doc committer)
>>>>
>>>>  Modified files:
>>>>    sbin/mdconfig        mdconfig.8
>>>>  Log:
>>>>  Add an example which shows how mdconfig(8) can be used
>>>>  to mount an ISO 9660 CD image file.
> 
> I'm not sure this example should exist.

First of all, thanks for the insightful and thorough review, as usual :-)

I would be very happy if it did.

> There is not much special about cd9660 images.

Not as images per se, but they are kind of 'special', in that a lot of
stuff is distributed as ISO CD-ROM images.  Having a working example to
mount them doesn't really hurt, but it _does_ help people looking for a
way to mount them.  One could argue, however, that the mdconfig(8)
manpage is probably the wrong place to document ISO images, because
someone who already knows about mdconfig doesn't need the example
anyway.  Hence my proposal to Kris for an example in mount_cd9670
instead.

> The previous example works for all types of images, except it spells
> the mount command as plain "mount" so ffs is implied, but there are
> proposals or commits to determine the filesystem type automatically.

We can't really depend in the manpage on uncommitted code, so we can fix
the mount arguments after the auto-detection code is committed.  Does
that sound ok? :)

> Bugs in this example:
> - it says "To mount", but it actually creates an md disk and mounts a
>   file system.
> - it spells the mount command as mount_cd9660 instead of "mount -t cd9660".

Both right on the spot.  Would the following look better?

     To attach an md(4) device to an ISO 9660 CD-ROM image, and mount it:

         mdconfig -a -t vnode -u 10 -f cdimage.iso
         mount_cd9660 /dev/md10 /mnt

> Bugs in nearby examples:
> - the previous one says "To create ... a disk", but it actually
>   creates a mounted file system (it creates 3 things and mounts 1).

A better description would probably explain why the label is installed
and list newfs too.  How about this instead?

     To attach an md(4) device using a file as its storage backend,
     install a new label on the new md(4) device, create a file system
     on the new device and mount it:

         mdconfig -f somebackingfile -u 0
         bsdlabel -w md0 auto
         newfs md0c
         mount /dev/md0c /mnt

>>> An interesting trick is that bsdtar can read ISO files without
>>> needing to mount them - I wonder if a cross-reference is
>>> appropriate.
>>
>> Good idea.  I don't know right now of a good way to reference bsdtar,
>> but maybe we can extend the sample with something like:
>> 
>>     The bsdtar(1) utility can also be used to peek into ISO 9660 CD
>>     images, or even to ``extract'' files from them.
>> 
>> or would a reference like this be more appropriate to mount_cd9660(1),
>> in a part of the manpage which points to mdconfig(8) and bsdtar(1)?
> 
> Even bsdtar itself doesn't document this explicitly, at least in 6.2.
> It points to libarchive(5) for the complete list of supported formats.

There is no reference to ISO 9660 in the CURRENT manpage either.  Maybe
Tim Kientzle, who wrote it can help us there?

- Giorgos