gmirror provider name limit [Was: Re: geom_label: gpt/labelname for gmirror provider?]

[Ben Kaduk]

[swapping out -current for -doc ... and yes, I'm a bit behind on my mail]

On Thu, Jul 30, 2009 at 12:38 PM, Harald
Schmalzbauer<h.schmalzbauer at omnilan.de> wrote:
> Harald Schmalzbauer schrieb am 30.07.2009 08:37 (localtime):
>>
>> Dimitry Andric schrieb am 29.07.2009 22:30 (localtime):
>> ...
>>>
>>> Please try the following patch, to enable an error message, in case any
>>> of the providers' names exceeds the maximum length.  It should be enough
>>> to do "cd /usr/src/sbin/geom && make && sudo make install".
>>>
>>> I'm not very good at manpages, though... any takers? :)
>>
>> I always wanted to look into man pages from the editors side.
>> Expect something toady, otherwise I'll notify when I failed...
>
> Here's the best I could do. I suggest some native speakers should have a
> look on it.
>
> geom_man.diff
> --- src/sbin/geom/class/raid3/graid3.8.orig     2009-07-30
> 18:20:16.000000000 +0200
> +++ src/sbin/geom/class/raid3/graid3.8  2009-07-30 18:20:51.000000000 +0200
> @@ -83,7 +83,15 @@
>  The
>  .Nm
>  utility uses on-disk metadata (the provider's last sector) to store all
> needed
> -information.
> +information. For

New sentences should start on new lines, as house style.
(It makes diffs easier to read, and is less confusing to the mdoc parser.)

> +.Ar prov ,
> +it's possible to use a providers label (see

I would avoid the "it's" contraction in favor of "it is".
"provider's" is a possessive and needs the apostrophe.

> +.Xr geom_label 8 )
> +instead of the device node.
> +The size of

I think s/size/length/ is more clear, but I'm not sure whether
everyone would agree.

> +.Ar prov
> +is limited to 15 characters, so currently it's not possible to use the
> GPTID

Again, expand "it's" to "it is" (I think it is probably best to avoid
contractions in man pages as a general rule)

I think "the GPTID" should be "GPTIDs" for parallelism in the number
of GPTIDs/labels.


Hm, the rest of the files are touched with identical changes, so I
think these comments apply equally there.

-Ben Kaduk


> +nor custom defined labels which are longer than 15 characters.
>  .Pp
>  The first argument to
>  .Nm
> --- src/sbin/geom/class/shsec/gshsec.8.orig     2009-07-30
> 18:21:49.000000000 +0200
> +++ src/sbin/geom/class/shsec/gshsec.8  2009-07-30 18:25:26.000000000 +0200
> @@ -62,7 +62,16 @@
>  The secret is shared between the given providers.
>  To collect the secret, all providers are needed.
>  If one of the components is missing, there is no way to get any useful data
> from
> -the rest of them.
> +the rest of them. For
> +.Ar prov ,
> +it's possible to use a providers label (see
> +.Xr geom_label 8 )
> +instead of the device node.
> +The size of
> +.Ar prov
> +is limited to 15 characters, so currently it's not possible to use the
> GPTID
> +nor custom defined labels which are longer than 15 characters.
> +.Pp
>  The first argument to
>  .Nm
>  indicates an action to be performed:
> --- src/sbin/geom/class/stripe/gstripe.8.orig   2009-07-30
> 18:23:42.000000000 +0200
> +++ src/sbin/geom/class/stripe/gstripe.8        2009-07-30
> 18:24:10.000000000 +0200
> @@ -82,7 +82,15 @@
>  .Dq automatic
>  method uses on-disk metadata to detect devices.
>  Once devices are labeled, they will be automatically detected and
> -configured.
> +configured. For
> +.Ar prov ,
> +it's possible to use a providers label (see
> +.Xr geom_label 8 )
> +instead of the device node.
> +The size of
> +.Ar prov
> +is limited to 15 characters, so currently it's not possible to use the
> GPTID
> +nor custom defined labels which are longer than 15 characters.
>  .Pp
>  The first argument to
>  .Nm
> --- src/sbin/geom/class/concat/gconcat.8.orig   2009-07-30
> 18:16:12.000000000 +0200
> +++ src/sbin/geom/class/concat/gconcat.8        2009-07-30
> 18:26:06.000000000 +0200
> @@ -80,7 +80,15 @@
>  .Dq automatic
>  method uses on-disk metadata to detect devices.
>  Once devices are labeled, they will be automatically detected and
> -configured.
> +configured. For
> +.Ar prov ,
> +it's possible to use a providers label (see
> +.Xr geom_label 8 )
> +instead of the device node.
> +The size of
> +.Ar prov
> +is limited to 15 characters, so currently it's not possible to use the
> GPTID
> +nor custom defined labels which are longer than 15 characters.
>  .Pp
>  The first argument to
>  .Nm
> --- src/sbin/geom/class/journal/gjournal.8.orig 2009-07-30
> 18:26:21.000000000 +0200
> +++ src/sbin/geom/class/journal/gjournal.8      2009-07-30
> 18:29:15.000000000 +0200
> @@ -125,6 +125,16 @@
>  This could be a problem when an existing file system is converted to use
>  .Nm .
>  .Pp
> +For
> +.Ar prov ,
> +it's possible to use a providers label (see
> +.Xr geom_label 8 )
> +instead of the device node.
> +The size of
> +.Ar prov
> +is limited to 15 characters, so currently it's not possible to use the
> GPTID
> +nor custom defined labels which are longer than 15 characters.
> +.Pp
>  The first argument to
>  .Nm
>  indicates an action to be performed:
> --- src/sbin/geom/class/mirror/gmirror.8.orig   2009-07-30
> 18:11:17.000000000 +0200
> +++ src/sbin/geom/class/mirror/gmirror.8        2009-07-30
> 18:29:55.000000000 +0200
> @@ -106,7 +106,15 @@
>  utility uses on-disk metadata (stored in the provider's last sector) to
> store all needed
>  information.
>  Since the last sector is used for this purpose, it is possible to place a
> root
> -file system on a mirror.
> +file system on a mirror. For
> +.Ar prov ,
> +it's possible to use a providers label (see
> +.Xr geom_label 8 )
> +instead of the device node.
> +The size of
> +.Ar prov
> +is limited to 15 characters, so currently it's not possible to use the
> GPTID
> +nor custom defined labels which are longer than 15 characters.
>  .Pp
>  The first argument to
>  .Nm
>
> Best regards,
>
> -Harry
>
>